Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

10.3 KB
Raw Blame
/**
 * Session usage accounting, shared across every host (Claude Code, Cursor, and
 * plain MCP). It answers the one question the README rests on: when an agent had
 * both graft and grep in front of it, which did it reach for, and how much did
 * that save?
 *
 * The counters (`graftReads`, `sourceReads`, `savedTokens`) already live on
 * {@link SessionState}; before this module nothing ever incremented the first
 * two, so `session_summary` telemetry shipped 0/0 for every session. Everything
 * here is a pure classify + read-modify-write over `graft/.cache/session/`, so a
 * host adapter is a few lines: parse its payload, call {@link recordToolUse}.
 *
 * Two payload shapes feed it, confirmed against the vendor docs rather than
 * guessed (the matcher depends on getting the names right):
 *
 *   - Claude Code `PostToolUse`  — `{ tool_name, tool_input: { command }, tool_response }`.
 *     A graft retrieval prints a `[graft] tokens saved ≈ N` footer into
 *     `tool_response`, which is itself proof graft ran.
 *   - Cursor `postToolUse`       — `{ tool_name, tool_input, tool_output, conversation_id }`
 *     (https://cursor.com/docs/hooks). `tool_output` is the JSON-stringified
 *     result; a Shell `graft …` call carries the same footer inside its stdout.
 *   - Cursor `afterMCPExecution` — `{ tool_name, tool_input, result_json, duration }`.
 *     Fires only for MCP tools, so a graft tool is recognised by its name and
 *     its savings read out of `result_json`.
 *
 * MCP tool names arrive host-prefixed in different shapes (`graft_find_code`,
 * `MCP:graft_find_code`, `mcp__graft__graft_find_code`). {@link isGraftMcpTool}
 * strips the prefix to the last delimited segment and checks it against the real
 * name list (`GRAFT_MCP_TOOL_NAMES`), so a graft tool is recognised across every
 * host format while a third-party tool that merely contains "graft" is not.
 */
import { statSync } from 'node:fs';
import { join } from 'node:path';
import { sumSavingsFooters } from '../context/savings.js';
import { dollarsSaved, formatDollars } from '../context/price.js';
import { readSession, writeSession, sessionDir, listSessionIds, type SessionState } from './state.js';
import type { AgentHost } from '../telemetry/contract.js';
import { GRAFT_MCP_TOOL_NAMES } from '../mcp/tool-names.js';
import { brand, cmd } from '../brand.js';

export type ToolKind = 'graft' | 'source';

/** Native tools that mean "the agent went to read source itself" — the grep/read
 *  path graft is meant to replace. These are the host tool NAMES (Claude Code and
 *  Cursor both use Read/Grep/Glob; Cursor adds Search); shell builtins like `ls`
 *  are commands, never tool names, so they belong to the Shell branch, not here.
 *  Compared lower-cased. */
const SOURCE_TOOLS = new Set(['read', 'grep', 'glob', 'search']);

/** The host's shell tool, whose `command` we then inspect for a graft invocation. */
function isShellTool(t: string): boolean {
  return t === 'bash' || t === 'shell';
}

/** An MCP-style tool name (server-prefixed), as opposed to a native Read/Shell.
 *  Used to hand graft MCP calls to the dedicated MCP hook so a host that fires
 *  BOTH a generic post-tool hook and an MCP hook can't double-count them. */
export function isMcpToolName(toolName: string): boolean {
  const t = toolName.toLowerCase();
  return t.startsWith('mcp') || t.includes(':') || t.includes('__');
}

/**
 * Whether a tool name is one of graft's MCP tools, across every host prefix.
 * Anchored on the real name list (`graft_find_code`, its legacy aliases, …), not
 * a loose `includes('graft')`: a third-party MCP tool whose name merely contains
 * "graft" (or a repo working on graft itself) must not count as a graft read —
 * the same care `commandInvokesGraft` takes for the CLI side. Strips the host
 * prefix first (`mcp__graft__graft_find_code`, `MCP:graft_find_code`) by taking
 * the last delimited segment. */
export function isGraftMcpTool(toolName: string): boolean {
  const t = toolName.toLowerCase();
  const bare = t.split(/[:./]|__/).pop() ?? t;
  return GRAFT_MCP_TOOL_NAMES.has(bare);
}

/** Whether a shell command line invokes the CLI under either name (any of its install shapes). */
export function commandInvokesGraft(command: string): boolean {
  const c = command.trim();
  // running from a source checkout
  if (/dist[/\\](cli|bin[/\\](trail|graft))\.js/.test(c)) return true;
  // `graft …`, `graft-dev …`, `npx [-y] [@nanonets/]graft …`, and the same for
  // `trail` / `@trailhq/trail-code`, at the start of the line or of a &&/;/| segment —
  // not "mygraft" or a path that merely contains it.
  return /(^|[|&;]\s*)(npx\s+(-y\s+)?(@nanonets\/|@trailhq\/)?)?(graft|trail)(-dev)?\b/i.test(c);
}

/**
 * Classify one tool use as a graft retrieval, a source read, or neither
 * (an edit, a task spawn, an unrelated shell command — no retrieval signal).
 * `command` is the shell command line when `toolName` is the host's shell tool.
 */
export function classifyToolUse(toolName?: string, command?: string): ToolKind | null {
  const t = (toolName ?? '').toLowerCase();
  if (!t) return null;
  if (isGraftMcpTool(t)) return 'graft';
  if (SOURCE_TOOLS.has(t)) return 'source';
  if (isShellTool(t) && command && commandInvokesGraft(command)) return 'graft';
  return null;
}

/** Sum every `[graft] tokens saved ≈ N` footer in a blob of tool output. Thin
 *  alias over {@link sumSavingsFooters}, which lives next to the code that writes
 *  the footer so the two can't drift. */
export function parseSavings(blob: string): number {
  return sumSavingsFooters(blob);
}

export interface ToolUse {
  /** 'graft' → graftReads++, 'source' → sourceReads++, null/absent → neither. */
  kind?: ToolKind | null;
  /** Tokens the retrieval saved, parsed from its footer. Added to the running total. */
  savedTokens?: number;
  /** The host recording this use. Stamped on the session file (once) so the
   * `session_summary` is attributed correctly no matter which host later flushes it. */
  host?: AgentHost;
}

/**
 * Fold one tool use into a session's counters. A no-op when there is nothing to
 * record (kind null and no savings), so a host can call it unconditionally after
 * every tool without first checking whether the tool was interesting — the
 * no-write path is what keeps it cheap on the Write/Edit/Task majority.
 *
 * Best-effort read-modify-write, not locked — mirroring `patchStats` in
 * util/state.ts. Two tool-use hooks racing on the same session file can lose a
 * count; that is acceptable for an episodic usage estimate (worst case is an
 * undercount by one, never corruption thanks to the atomic write), and a lock
 * here would contend with the build lock these hooks also touch.
 */
export function recordToolUse(dir: string, sessionId: string, use: ToolUse): void {
  const saved = use.savedTokens ?? 0;
  if (!use.kind && saved <= 0) return;
  const id = sessionId || 'default';
  const s = readSession(dir, id);
  if (use.kind === 'graft') s.graftReads = (s.graftReads ?? 0) + 1;
  else if (use.kind === 'source') s.sourceReads = (s.sourceReads ?? 0) + 1;
  if (saved > 0) s.savedTokens = (s.savedTokens ?? 0) + saved;
  // A graft use owes a tally in this turn's reply; the Stop hook (countTallyTurn)
  // resolves whether it got one and clears the flag. A flag, not a count — a turn
  // with several graft calls is still one reply to the user.
  if (use.kind === 'graft') s.turnUsedGraft = true;
  // Stamp the host once; the first tool use that lands owns the attribution.
  if (use.host && !s.host) s.host = use.host;
  writeSession(dir, id, s);
}

export interface SessionSummary extends SessionState {
  id: string;
}

/** The most-recently-touched session file for a repo, or null when none exist —
 *  what `graft stats` shows by default: the session you were just in. */
export function latestSession(dir: string): SessionSummary | null {
  const sdir = sessionDir(dir);
  let bestId: string | null = null;
  let bestMtime = -Infinity;
  for (const id of listSessionIds(dir)) {
    let mtime: number;
    try { mtime = statSync(join(sdir, `${id}.json`)).mtimeMs; } catch { continue; }
    if (mtime > bestMtime) { bestMtime = mtime; bestId = id; }
  }
  if (bestId === null) return null;
  return { id: bestId, ...readSession(dir, bestId) };
}

/**
 * A one-line-per-fact readout of a session's usage mix — Cursor has no
 * statusline, so this is how you see the numbers the Claude Code bar would show.
 * Reads local JSON only; sends nothing.
 */
/**
 * What this repo's most recent session has actually been paying per million
 * input tokens, or null when no turn has been billed yet.
 *
 * `latestSession` rather than a session id because the callers are CLI and MCP
 * processes answering one query: they know the repo, never the host's session
 * id. The rate belongs to the repo's current session, which is the one whose
 * reply the number is about to appear in.
 */
export function sessionInputRate(dir: string): number | null {
  const s = latestSession(dir);
  if (!s?.inputCostMicros || !s?.inputTokensBilled) return null;
  // Micro-dollars per token and dollars per million tokens are the same number:
  // both divide by 1e6 once. Returned as $/Mtok because that is the unit the
  // price table is written in and the one a reader can sanity-check against it.
  return s.inputCostMicros / s.inputTokensBilled;
}

export function formatSessionStats(s: SessionSummary | null): string {
  if (s === null) {
    return `${cmd('graft stats')}: no session recorded yet. Use ${brand()} in an agent session, then look again.`;
  }
  const graft = s.graftReads ?? 0;
  const source = s.sourceReads ?? 0;
  const saved = s.savedTokens ?? 0;
  const total = graft + source;
  const mix =
    total === 0 ? 'no retrieval yet' : `${Math.round((graft / total) * 100)}% graft`;
  const lines = [
    `${cmd('graft stats')}: session ${s.id}`,
    `  graft reads:   ${graft}`,
    `  source reads:  ${source}   (Read / Grep / Glob)`,
    `  mix:           ${mix}`,
    `  tokens saved:  ~${saved.toLocaleString()}`,
  ];
  // Omitted, not zeroed, when no turn has been billed yet: a host whose hooks
  // name no transcript can't know what a token costs here, and a made-up rate
  // would be worse than the silence.
  const usd = dollarsSaved(saved, s.inputCostMicros, s.inputTokensBilled);
  if (usd !== null) lines.push(`  value saved:   ~${formatDollars(usd)}`);
  if (s.promptAsks) lines.push(`  prompts asked: ${s.promptAsks}`);
  return lines.join('\n');
}