Function buildRecommendations

src/diagnostics/token-analyzer.ts:235–313

* Data-driven recommendations. Each one fires only when its threshold is hit, so the * advice is calibrated to THIS session, not a generic checklist. * * Thresholds intentionally on the strict side — we don't want noise.

(args: {
  totals: TokenReport['totals'];
  breakdowns: TurnBreakdown[];
  toolHotspots: TokenReport['toolHotspots'];
  fileHotspots: TokenReport['fileHotspots'];
})

 * Thresholds intentionally on the strict side — we don't want noise.
 */
function buildRecommendations(args: {
  totals: TokenReport['totals'];
  breakdowns: TurnBreakdown[];
  toolHotspots: TokenReport['toolHotspots'];
  fileHotspots: TokenReport['fileHotspots'];
}): string[] {
  const recs: string[] = [];
  const { totals, breakdowns, toolHotspots, fileHotspots } = args;
  const turnCount = breakdowns.length;
  if (turnCount === 0) return ['Session has no turns yet — run a task first.'];

  // 1. Tool schemas dominate? Each turn reships them, so total = perTurn * turnCount
  const schemasShare = totals.grandTotal > 0 ? totals.toolSchemas / totals.grandTotal : 0;
  if (schemasShare > 0.4) {
    recs.push(
      `Tool schemas account for ${Math.round(schemasShare * 100)}% of all tokens ` +
      `(${totals.toolSchemas.toLocaleString()} across ${turnCount} turns). ` +
      `Highest-leverage fix: enable prompt caching (cloud) or KV-cache reuse (local Ollama/MLX), ` +
      `OR slim tool descriptions. This is Lever 1 + Lever 2 in the optimization plan.`,
    );
  }

  // 2. System prompt similar
  const systemShare = totals.grandTotal > 0 ? totals.system / totals.grandTotal : 0;
  if (systemShare > 0.2 && turnCount > 3) {
    recs.push(
      `System prompt is reshipped every turn (${totals.system.toLocaleString()} total = ` +
      `${Math.round(systemShare * 100)}% of session). ` +
      `Same caching strategy applies — system + tools should be a single cached prefix.`,
    );
  }

  // 3. Repeated reads of the same file
  const repeatedFiles = fileHotspots.filter(f => f.reads >= 3);
  if (repeatedFiles.length > 0) {
    const top = repeatedFiles.slice(0, 3).map(f => `${f.path} (${f.reads}×)`).join(', ');
    recs.push(
      `Repeated reads detected: ${top}. ` +
      `Dedup with content hashing (Lever 3) would skip the redundant content. ` +
      `Each repeat costs the full file body in tokens.`,
    );
  }

  // 4. One tool dominates output
  if (toolHotspots.length > 0) {
    const top = toolHotspots[0]!;
    const topShare = totals.toolResults > 0 ? top.outputTokens / totals.toolResults : 0;
    if (topShare > 0.5 && top.outputTokens > 2000) {
      recs.push(
        `'${top.tool}' produced ${top.outputTokens.toLocaleString()} tokens of output ` +
        `(${Math.round(topShare * 100)}% of all tool results), ` +
        `avg ${top.avgPerCall.toLocaleString()} per call. ` +
        `Consider truncation at the tool level (e.g. max bytes) or summarisation of older results in history.`,
      );
    }
  }

  // 5. Total trajectory — is the session about to blow past a typical 32K context?