diffsplain 0.9.0 → 0.11.0

package/scripts/agent-usage.mjs

@@ -0,0 +1,141 @@
+const tokenFields = [
+  'inputTokens',
+  'outputTokens',
+  'cacheReadTokens',
+  'cacheWriteTokens',
+];
+
+function tokenCount(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function usageObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+}
+
+function usageEntries(value) {
+  return tokenFields.reduce((entries, field) => {
+    const count = tokenCount(value[field]);
+    return count === undefined ? entries : [...entries, [field, count]];
+  }, []);
+}
+
+function providerUsage(value) {
+  const usage = usageObject(value);
+  if (!usage) return undefined;
+  const tokens = Object.fromEntries(usageEntries(usage));
+  return Object.keys(tokens).length > 0 ? tokens : undefined;
+}
+
+function countOrZero(value) {
+  return tokenCount(value) || 0;
+}
+
+function summaryTokens(value) {
+  return providerUsage(value) || {};
+}
+
+export function emptyUsageAccumulator() {
+  return { calls: 0, reportedCalls: 0, tokens: {} };
+}
+
+function mergedTokens(left, right) {
+  const tokens = { ...left };
+  for (const [field, count] of Object.entries(right || {})) {
+    tokens[field] = (tokens[field] || 0) + count;
+  }
+  return tokens;
+}
+
+export function recordUsage(accumulator, usage) {
+  const reported = providerUsage(usage);
+  return {
+    calls: accumulator.calls + 1,
+    reportedCalls: accumulator.reportedCalls + Number(Boolean(reported)),
+    tokens: mergedTokens(accumulator.tokens, reported),
+  };
+}
+
+export function usageSummary(accumulator) {
+  if (accumulator.calls === 0) {
+    return {
+      status: 'complete',
+      calls: 0,
+      reportedCalls: 0,
+      tokens: { inputTokens: 0, outputTokens: 0 },
+    };
+  }
+  if (accumulator.reportedCalls === 0) {
+    return {
+      status: 'unavailable',
+      calls: accumulator.calls,
+      reportedCalls: 0,
+    };
+  }
+  return {
+    status: accumulator.reportedCalls === accumulator.calls
+      ? 'complete'
+      : 'partial',
+    calls: accumulator.calls,
+    reportedCalls: accumulator.reportedCalls,
+    tokens: { ...accumulator.tokens },
+  };
+}
+
+function accumulatorFromSummary(summary) {
+  const usage = usageObject(summary);
+  if (!usage) return emptyUsageAccumulator();
+  return {
+    calls: countOrZero(usage.calls),
+    reportedCalls: countOrZero(usage.reportedCalls),
+    tokens: summaryTokens(usage.tokens),
+  };
+}
+
+export function combineUsage(left, right) {
+  const first = accumulatorFromSummary(left);
+  const second = accumulatorFromSummary(right);
+  return usageSummary({
+    calls: first.calls + second.calls,
+    reportedCalls: first.reportedCalls + second.reportedCalls,
+    tokens: mergedTokens(first.tokens, second.tokens),
+  });
+}
+
+export function reviewUsage(agentNotes, reviewChat) {
+  return {
+    agentNotes,
+    reviewChat,
+    combined: combineUsage(agentNotes, reviewChat),
+  };
+}
+
+const terminalLabels = {
+  inputTokens: 'input',
+  outputTokens: 'output',
+  cacheReadTokens: 'cache read',
+  cacheWriteTokens: 'cache write',
+};
+
+function formatUsageTokens(tokens) {
+  return Object.entries(tokens || {})
+    .map(([field, count]) => `${terminalLabels[field]} ${count.toLocaleString('en-US')}`)
+    .join(', ');
+}
+
+export function formatUsage(label, summary) {
+  if (summary.status === 'unavailable') return `${label}: Unavailable`;
+  const totals = formatUsageTokens(summary.tokens);
+  const prefix = summary.status === 'partial' ? 'Partial, ' : '';
+  return `${label}: ${prefix}${totals || '0 tokens'}`;
+}
+
+export function formatReviewUsage(usage) {
+  return [
+    formatUsage('Agent note usage', usage.agentNotes),
+    formatUsage('Review chat usage', usage.reviewChat),
+    formatUsage('Combined agent usage', usage.combined),
+  ].join('\n');
+}

package/scripts/build-diff-data.mjs

@@ -32,6 +32,12 @@ import {
   createAgentReviewFingerprint,
 } from './agent-review.mjs';
 import { summaryPath } from './summary-path.mjs';
+import {
+  combineUsage,
+  emptyUsageAccumulator,
+  reviewUsage,
+  usageSummary,
+} from './agent-usage.mjs';
 
 const args = process.argv.slice(2);
 const fail = (message) => {
@@ -1338,10 +1344,18 @@ function build() {
       ...(typeof summaryDoc.meta?.reasoning === 'string'
         ? { reasoning: summaryDoc.meta.reasoning }
         : {}),
+      fast: summaryDoc.meta?.fast === true,
       ...(typeof summaryDoc.meta?.accessMode === 'string'
         ? { accessMode: summaryDoc.meta.accessMode }
         : {}),
     },
+    usage: reviewUsage(
+      combineUsage(
+        sourceSummaries.meta?.usage,
+        usageSummary(emptyUsageAccumulator()),
+      ),
+      usageSummary(emptyUsageAccumulator()),
+    ),
   };
   const version = createHash('sha256')
     .update(JSON.stringify(content))
@@ -1465,23 +1479,29 @@ const refresh = () => {
   }
 };
 
-const started = refresh();
+let watcher;
+const stopWatching = (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+  if (watcher) clearInterval(watcher);
+};
+let initialFingerprint;
+let startupFailed = false;
+if (watching) {
+  try {
+    initialFingerprint = fingerprint();
+  } catch (error) {
+    startupFailed = true;
+    stopWatching(error);
+  }
+}
+const started = !startupFailed && refresh();
 if (watching && started) {
-  let last;
+  let last = initialFingerprint;
   let remoteWait = 0;
-  let watcher;
-  const stopWatching = (error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-    if (watcher) clearInterval(watcher);
-  };
   const poll = () => {
     try {
       const next = fingerprint();
-      if (last === undefined) {
-        last = next;
-        return true;
-      }
       remoteWait += watchInterval;
       const remoteDue = remoteMode && remoteWait >= remoteRefreshInterval;
       if (next !== last || remoteDue || watchContent) {

package/scripts/cli-args.mjs

@@ -42,6 +42,7 @@ export const cliOptions = defineCliOptions({
   '--no-agent': { kind: 'no-agent' },
   '--no-checkout-access': { kind: 'flag' },
   '--force': { kind: 'flag' },
+  '--fast': { kind: 'flag' },
   '--worktree': { kind: 'flag' },
   '--no-browser': { kind: 'flag' },
   '--support-record': { kind: 'flag' },
@@ -82,6 +83,8 @@ Commands:
   doctor [--json] [--deep]
                       Check review, agent, and pull request capabilities
   cache               Show or prune saved agent notes
+  config agent [NAME|--unset]
+                      Show, set, or unset the default coding agent
 
 Targets:
   --branch NAME       Show a remote branch against its default branch
@@ -100,6 +103,7 @@ Options:
   --exclude PATTERN   Omit matching files from automatic agent context
   --model NAME        Model for agent notes
   --reasoning LEVEL   Agent reasoning effort when supported
+  --fast              Enable provider Fast mode for agent notes and chat
   --batch-size COUNT  Maximum files per agent pass (default: ${batchSizeOption.default})
   --jobs COUNT        Agent passes to run at once (default: ${jobsOption.default})
   --force             Regenerate all agent notes
@@ -118,8 +122,8 @@ Options:
   -v, --version       Show the installed version
 
 Agent choice:
-  Without --agent, an interactive terminal lists usable agents. In scripts,
-  pass --agent NAME or --no-agent.
+  Choice order is --no-agent, --agent, then the configured default.
+  Without any choice, an interactive terminal lists usable agents.
 
 Cursor:
   Requires Cursor Agent 2026.08.11 or newer. Uses the signed-in CLI in the
@@ -195,6 +199,31 @@ export function parseCliArgs(
     pathExists = existsSync,
   } = {},
 ) {
+  if (rawArgs[0] === 'config') {
+    if (rawArgs[1] !== 'agent') {
+      fail('Use: diffsplain config agent [NAME|--unset]');
+    }
+    if (rawArgs.length === 2) {
+      return { config: { kind: 'show' } };
+    }
+    if (rawArgs.length !== 3) {
+      fail('Use: diffsplain config agent [NAME|--unset]');
+    }
+    const value = rawArgs[2];
+    if (value === '--unset') {
+      return { config: { kind: 'unset' } };
+    }
+    if (value.startsWith('--')) {
+      fail('Use: diffsplain config agent [NAME|--unset]');
+    }
+    if (!codingAgents.includes(value)) {
+      fail(
+        `Unsupported agent "${value}". Choose ${enabledCodingAgents.join(', ')}.`,
+      );
+    }
+    return { config: { kind: 'set', agent: value } };
+  }
+
   if (rawArgs[0] === 'doctor') {
     const options = new Set(rawArgs.slice(1));
     for (const option of options) {
@@ -284,6 +313,9 @@ export function parseCliArgs(
     fail('Pass the repo once, either as REPO or with --repo');
   }
   if (noAgent && agentSet) fail('--agent and --no-agent cannot be used together');
+  if (noAgent && options.has('--fast')) {
+    fail('--fast and --no-agent cannot be used together');
+  }
   if (noAgent && options.has('--summaries')) {
     fail('--no-agent cannot be used with --summaries');
   }
@@ -390,6 +422,7 @@ export function parseCliArgs(
     agentArgs.push(`--exclude=${pattern}`);
   }
   if (options.has('--force')) agentArgs.push('--force');
+  if (options.has('--fast')) agentArgs.push('--fast');
   for (const name of [
     '--codex-bin',
     '--model',
@@ -499,5 +532,6 @@ export function parseCliArgs(
     host,
     browserEnabled: !options.has('--no-browser'),
     forceSummaryRegeneration: options.has('--force'),
+    fast: options.has('--fast'),
   };
 }

package/scripts/coding-agents.mjs

@@ -8,13 +8,29 @@ import {
   isAbsolute,
   join,
 } from 'node:path';
+import { readConfiguredAgent } from './agent-config.mjs';
 
 export const codingAgentCapabilities = {
-  codex: { binary: 'codex', model: true, reasoning: true },
-  claude: { binary: 'claude', model: true, reasoning: false },
-  copilot: { binary: 'copilot', model: true, reasoning: false },
-  cursor: { binary: 'cursor-agent', model: true, reasoning: false },
-  opencode: { binary: 'opencode', model: true, reasoning: true },
+  codex: {
+    binary: 'codex',
+    model: true,
+    reasoning: true,
+    fast: { label: 'Codex CLI', minimumVersion: '0.108.0' },
+  },
+  claude: {
+    binary: 'claude',
+    model: true,
+    reasoning: false,
+    fast: { label: 'Claude Code', minimumVersion: '2.1.36' },
+  },
+  copilot: { binary: 'copilot', model: true, reasoning: false, fast: false },
+  cursor: {
+    binary: 'cursor-agent',
+    model: true,
+    reasoning: false,
+    fast: false,
+  },
+  opencode: { binary: 'opencode', model: true, reasoning: true, fast: false },
 };
 
 export const codingAgents = Object.keys(codingAgentCapabilities);
@@ -23,6 +39,10 @@ export function agentSupportsReasoning(agent) {
   return codingAgentCapabilities[agent]?.reasoning === true;
 }
 
+export function agentSupportsFast(agent) {
+  return Boolean(codingAgentCapabilities[agent]?.fast);
+}
+
 export function assertReasoningSupported(agent, reasoning) {
   if (reasoning && !agentSupportsReasoning(agent)) {
     throw new Error(
@@ -88,6 +108,67 @@ function versionAtLeast(current, minimum) {
   return true;
 }
 
+function semanticVersion(value) {
+  const match = value?.match(/(?:^|\D)(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?/);
+  if (!match) return undefined;
+  return {
+    parts: match.slice(1, 4).map(Number),
+    prerelease: Boolean(match[4]),
+  };
+}
+
+export function inspectFastCompatibility(
+  agent,
+  command,
+  {
+    env = process.env,
+    timeout = 5_000,
+    run = spawnSync,
+  } = {},
+) {
+  const capability = codingAgentCapabilities[agent]?.fast;
+  if (!capability) {
+    return {
+      compatible: false,
+      reason: `--fast is supported only by codex and claude; ${agent} does not support it.`,
+    };
+  }
+  const result = run(command, ['--version'], {
+    encoding: 'utf8',
+    env,
+    timeout,
+    windowsHide: true,
+  });
+  const version = firstLine(`${result.stdout || ''}\n${result.stderr || ''}`);
+  const current = semanticVersion(version);
+  const minimum = semanticVersion(capability.minimumVersion);
+  const compatible = current && minimum &&
+    (versionAtLeast(current.parts, minimum.parts) &&
+      !(current.prerelease &&
+        current.parts.every((part, index) => part === minimum.parts[index])));
+  if (result.error || result.status !== 0 || !version || !current) {
+    return {
+      compatible: false,
+      version,
+      reason: `${capability.label} ${capability.minimumVersion} or newer is required for --fast, but its version could not be checked. Upgrade ${capability.label}.`,
+    };
+  }
+  if (!compatible) {
+    return {
+      compatible: false,
+      version,
+      reason: `${capability.label} ${capability.minimumVersion} or newer is required for --fast; found ${version}. Upgrade ${capability.label}.`,
+    };
+  }
+  return { compatible: true, version };
+}
+
+export function assertFastCompatible(agent, command, fast, options) {
+  if (!fast) return;
+  const inspection = inspectFastCompatibility(agent, command, options);
+  if (!inspection.compatible) throw new Error(inspection.reason);
+}
+
 function cursorCompatibilityError(detail) {
   return `Cursor Agent is incompatible: ${detail} ${cursorRequirementSummary} Upgrade Cursor Agent.`;
 }
@@ -263,15 +344,57 @@ function nonInteractiveSelectionError() {
   );
 }
 
-async function selectRequestedCodingAgent(requested, available) {
-  if (!codingAgents.includes(requested)) {
-    throw new Error(
-      `Unsupported agent "${requested}". Choose ${enabledCodingAgents.join(', ')}.`,
+class CodingAgentSelectionError extends Error {
+  constructor(agent, message) {
+    super(message);
+    this.agent = agent;
+  }
+}
+
+export function codingAgentFromSelectionError(error) {
+  return error instanceof CodingAgentSelectionError
+    ? error.agent
+    : undefined;
+}
+
+function unsupportedSelectionError(requested, configured) {
+  if (configured) {
+    return new CodingAgentSelectionError(
+      requested,
+      `Configured coding agent "${requested}" is unsupported. Choose ${enabledCodingAgents.join(', ')} with diffsplain config agent NAME, or use --agent NAME for this run.`,
     );
   }
+  return new CodingAgentSelectionError(
+    requested,
+    `Unsupported agent "${requested}". Choose ${enabledCodingAgents.join(', ')}.`,
+  );
+}
+
+function unavailableSelectionError(requested, result, configured) {
+  if (!configured) {
+    return new CodingAgentSelectionError(
+      requested,
+      unavailableAgentError(requested, result).message,
+    );
+  }
+  const reason = typeof result === 'object' ? result.reason : undefined;
+  return new CodingAgentSelectionError(
+    requested,
+    `Configured coding agent "${requested}" is not available.${reason ? ` ${reason}` : ''} Change it with diffsplain config agent NAME, or use --agent NAME for this run.`,
+  );
+}
+
+async function selectRequestedCodingAgent(
+  requested,
+  available,
+  { configured = false } = {},
+) {
+  if (!codingAgents.includes(requested)) {
+    throw unsupportedSelectionError(requested, configured);
+  }
   const result = await available(requested);
   if (!availableResult(result)) {
-    throw unavailableAgentError(requested, result);
+    throw unavailableSelectionError(requested, result, configured);
   }
   return requested;
 }
@@ -340,15 +463,23 @@ export async function selectCodingAgent(
   requested,
   {
     available = commandAvailable,
+    configuredAgent = readConfiguredAgent,
     input = process.stdin,
     output = process.stderr,
     signal,
   } = {},
 ) {
-  if (requested) {
+  if (requested !== undefined) {
     return selectRequestedCodingAgent(requested, available);
   }
 
+  const configured = await configuredAgent();
+  if (configured !== undefined) {
+    return selectRequestedCodingAgent(configured, available, {
+      configured: true,
+    });
+  }
+
   if (!input?.isTTY || !output?.isTTY) {
     throw nonInteractiveSelectionError();
   }
@@ -412,6 +543,27 @@ function parseClaudeResponse(stdout) {
   return envelope;
 }
 
+function jsonLines(stdout) {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  if (!lines.length) return undefined;
+  const events = lines.map(parseEvent);
+  return events.every(Boolean) ? events : undefined;
+}
+
+function parseCodexResponse(stdout) {
+  const events = jsonLines(stdout);
+  const message = events && [...events]
+    .reverse()
+    .find((event) =>
+      event.type === 'item.completed' &&
+      event.item?.type === 'agent_message' &&
+      typeof event.item.text === 'string',
+    );
+  return message
+    ? parseJsonText(message.item.text, 'Codex')
+    : parseJsonText(stdout, 'Codex');
+}
+
 function parseEvent(line) {
   try {
     return JSON.parse(line);
@@ -470,8 +622,94 @@ export function parseAgentResponse(agent, stdout) {
   if (agent === 'claude') return parseClaudeResponse(stdout);
   if (agent === 'opencode') return parseOpenCodeResponse(stdout);
   if (agent === 'cursor') return parseCursorResponse(stdout);
-  const label = agent === 'copilot' ? 'Copilot' : 'Codex';
-  return parseJsonText(stdout, label);
+  if (agent === 'codex') return parseCodexResponse(stdout);
+  return parseJsonText(stdout, 'Copilot');
+}
+
+function addUsageField(totals, [field, count]) {
+  if (!Number.isSafeInteger(count) || count < 0) return;
+  totals[field] = (totals[field] || 0) + count;
+}
+
+function addProviderUsage(totals, usage) {
+  Object.entries(usage).forEach((entry) => addUsageField(totals, entry));
+  return totals;
+}
+
+function sumProviderUsage(usages) {
+  const totals = usages.reduce(addProviderUsage, {});
+  return Object.keys(totals).length ? totals : undefined;
+}
+
+function providerUsage(inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens) {
+  return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+}
+
+function codexEventUsage(event) {
+  if (event.type !== 'turn.completed' || !event.usage) return undefined;
+  const usage = event.usage;
+  return providerUsage(
+    usage.input_tokens,
+    usage.output_tokens,
+    usage.cached_input_tokens,
+    usage.cache_write_input_tokens,
+  );
+}
+
+function eventPartTokens(event, type) {
+  if (event.type !== type) return undefined;
+  return event.part?.tokens;
+}
+
+function openCodeEventUsage(event) {
+  const tokens = eventPartTokens(event, 'step_finish');
+  if (!tokens) return undefined;
+  const cache = tokens.cache || {};
+  return providerUsage(
+    tokens.input,
+    tokens.output,
+    cache.read,
+    cache.write,
+  );
+}
+
+function eventUsage(stdout, extractUsage) {
+  const events = jsonLines(stdout) || [];
+  return sumProviderUsage(events.map(extractUsage).filter(Boolean));
+}
+
+function codexUsage(stdout) {
+  return eventUsage(stdout, codexEventUsage);
+}
+
+function safeProviderEnvelope(stdout, label) {
+  try {
+    return parseJsonText(stdout, label);
+  } catch {
+    return undefined;
+  }
+}
+
+function claudeUsage(stdout) {
+  const usage = safeProviderEnvelope(stdout, 'Claude')?.usage;
+  if (!usage || typeof usage !== 'object') return undefined;
+  return sumProviderUsage([providerUsage(
+    usage.input_tokens,
+    usage.output_tokens,
+    usage.cache_read_input_tokens,
+    usage.cache_creation_input_tokens,
+  )]);
+}
+
+function openCodeUsage(stdout) {
+  return eventUsage(stdout, openCodeEventUsage);
+}
+
+export function parseAgentUsage(agent, stdout) {
+  if (agent === 'codex') return codexUsage(stdout);
+  if (agent === 'claude') return claudeUsage(stdout);
+  if (agent === 'opencode') return openCodeUsage(stdout);
+  return undefined;
 }
 
 function codexIsolationArgs(snapshotOnly) {
@@ -503,6 +741,7 @@ function codexRepoArgs(snapshotOnly) {
 
 function codexCommand({
   binary,
+  fast,
   model,
   reasoning,
   prompt,
@@ -514,6 +753,7 @@ function codexCommand({
   const args = [
     'exec',
     '--ephemeral',
+    '--json',
     '--sandbox',
     'read-only',
     ...codexIsolationArgs(snapshotOnly),
@@ -526,6 +766,14 @@ function codexCommand({
     schemaPath,
     ...codexConfigArgs(snapshotOnly),
   ];
+  if (fast) {
+    args.push(
+      '--config',
+      'service_tier="fast"',
+      '--config',
+      'features.fast_mode=true',
+    );
+  }
   if (model) args.push('--model', model);
   if (reasoning) {
     args.push(
@@ -545,6 +793,7 @@ function codexCommand({
 
 function claudeCommand({
   binary,
+  fast,
   model,
   prompt,
   schema,
@@ -561,6 +810,7 @@ function claudeCommand({
     ...(snapshotOnly ? ['--tools', ''] : ['--permission-mode', 'plan']),
     '--no-session-persistence',
   ];
+  if (fast) args.push('--settings', JSON.stringify({ fastMode: true }));
   if (model) args.push('--model', model);
   args.push(prompt);
   return {
@@ -713,6 +963,7 @@ export function agentCommand({
   binary = agent,
   model,
   reasoning,
+  fast = false,
   prompt,
   schema,
   schemaPath,
@@ -724,6 +975,7 @@ export function agentCommand({
   const checkoutAccess = accessMode?.mode === 'checkout-read-only';
   const options = {
     binary,
+    fast,
     inputPath,
     model,
     prompt,