diffsplain 0.10.0 → 0.11.0

package/scripts/coding-agents.mjs

@@ -11,11 +11,26 @@ import {
 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);
@@ -24,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(
@@ -89,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.`;
 }
@@ -463,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);
@@ -521,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) {
@@ -554,6 +741,7 @@ function codexRepoArgs(snapshotOnly) {
 
 function codexCommand({
   binary,
+  fast,
   model,
   reasoning,
   prompt,
@@ -565,6 +753,7 @@ function codexCommand({
   const args = [
     'exec',
     '--ephemeral',
+    '--json',
     '--sandbox',
     'read-only',
     ...codexIsolationArgs(snapshotOnly),
@@ -577,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(
@@ -596,6 +793,7 @@ function codexCommand({
 
 function claudeCommand({
   binary,
+  fast,
   model,
   prompt,
   schema,
@@ -612,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 {
@@ -764,6 +963,7 @@ export function agentCommand({
   binary = agent,
   model,
   reasoning,
+  fast = false,
   prompt,
   schema,
   schemaPath,
@@ -775,6 +975,7 @@ export function agentCommand({
   const checkoutAccess = accessMode?.mode === 'checkout-read-only';
   const options = {
     binary,
+    fast,
     inputPath,
     model,
     prompt,

package/scripts/generate-summaries.mjs

@@ -15,13 +15,22 @@ import { fileURLToPath } from 'node:url';
 import {
   agentCommand,
   agentReadOnlyWarning,
+  assertFastCompatible,
   assertReasoningSupported,
   codingAgentFromSelectionError,
   codingAgentAvailability,
   codingAgentBinary,
   parseAgentResponse,
+  parseAgentUsage,
   selectCodingAgent,
 } from './coding-agents.mjs';
+import {
+  emptyUsageAccumulator,
+  formatReviewUsage,
+  recordUsage,
+  reviewUsage,
+  usageSummary,
+} from './agent-usage.mjs';
 import {
   isBaseWorktreeTarget,
   reviewAccessMode,
@@ -76,6 +85,7 @@ const valueFlags = new Set([
 const booleanFlags = new Set([
   '--checkout',
   '--force',
+  '--fast',
   '--support-record',
   '--worktree',
   '--no-checkout-access',
@@ -140,6 +150,7 @@ Options:
   --codex-bin FILE    Codex CLI path (default: codex)
   --model NAME        Model passed to the coding agent
   --reasoning LEVEL   Agent reasoning effort when supported
+  --fast              Enable provider Fast mode for every agent call
   --batch-size COUNT  Maximum files per agent pass (default: 12)
   --jobs COUNT        Agent passes to run at once (default: 3)
   --support-record    Print a safe record if this run fails
@@ -178,6 +189,7 @@ let selectedAgent;
 let agentBinary;
 const model = option('--model');
 const reasoning = option('--reasoning');
+const fast = rawArgs.includes('--fast');
 const batchSizeValue = option('--batch-size') || '12';
 const reasoningLevels = new Set([
   'minimal',
@@ -377,6 +389,18 @@ const summariesPath = summaryPath({
 const ownershipPath = `${summariesPath}.lock`;
 let ownership;
 let ownershipHeartbeat;
+let agentUsage = emptyUsageAccumulator();
+
+function currentAgentUsage() {
+  return usageSummary(agentUsage);
+}
+
+function recordAgentUsage(usage) {
+  agentUsage = recordUsage(agentUsage, usage);
+  const emptyChatUsage = usageSummary(emptyUsageAccumulator());
+  console.log(formatReviewUsage(reviewUsage(currentAgentUsage(), emptyChatUsage)));
+}
+
 function acquireOwnership() {
   ownership = acquireLease(ownershipPath);
   ownershipHeartbeat = setInterval(() => {
@@ -1039,8 +1063,13 @@ function publishSnapshot(
       ...(state.errors.length ? { errors: state.errors } : {}),
       ...(model ? { model } : {}),
       ...(reasoning ? { reasoning } : {}),
+      fast,
       accessMode: accessMode.mode,
     },
+    usage: reviewUsage(
+      currentAgentUsage(),
+      usageSummary(emptyUsageAccumulator()),
+    ),
   };
   delete content.version;
   delete content.generatedAt;
@@ -1065,6 +1094,7 @@ function summariesForSnapshot(summaries, snapshot) {
     meta: {
       ...summaries.meta,
       reviewFingerprint: snapshot.notes.reviewFingerprint,
+      usage: currentAgentUsage(),
     },
   };
 }
@@ -1208,8 +1238,9 @@ async function selectAgentForNotes() {
         signal: selectionAbortController.signal,
       },
     );
-    assertReasoningSupported(selectedAgent, reasoning);
     agentBinary = codingAgentBinary(selectedAgent, { codexBin });
+    assertReasoningSupported(selectedAgent, reasoning);
+    assertFastCompatible(selectedAgent, agentBinary, fast);
     supportRecorder?.setProvider(
       selectedAgent,
       safeCommandVersion(selectedAgent, agentBinary),
@@ -1265,9 +1296,12 @@ function runAgent(invocation, input, { timeoutMs } = {}) {
     const timeout = timeoutMs
       ? setTimeout(() => {
         child.kill('SIGTERM');
-        rejectPromise(
-          new Error(`${selectedAgent} timed out`),
+        const error = new Error(`${selectedAgent} timed out`);
+        error.providerUsage = parseAgentUsage(
+          selectedAgent,
+          Buffer.concat(stdout).toString('utf8'),
         );
+        rejectPromise(error);
       }, timeoutMs)
       : undefined;
     timeout?.unref();
@@ -1316,14 +1350,18 @@ function runAgent(invocation, input, { timeoutMs } = {}) {
           .filter((line) => line.trim() && line.length < 600)
           .slice(-8)
           .join('\n');
-        rejectPromise(
-          new Error(
-            `${selectedAgent} exited with status ${status ?? signal}${detail ? `\n${detail}` : ''}`,
-          ),
+        const error = new Error(
+          `${selectedAgent} exited with status ${status ?? signal}${detail ? `\n${detail}` : ''}`,
         );
+        error.providerUsage = parseAgentUsage(selectedAgent, stdoutText);
+        rejectPromise(error);
         return;
       }
-      resolvePromise({ stdout: stdoutText, stderr: stderrText });
+      resolvePromise({
+        stdout: stdoutText,
+        stderr: stderrText,
+        providerUsage: parseAgentUsage(selectedAgent, stdoutText),
+      });
     });
     if (invocation.input === 'stdin') child.stdin.end(input);
     else child.stdin.end();
@@ -1333,8 +1371,16 @@ function runAgent(invocation, input, { timeoutMs } = {}) {
 async function requestAgent(invocation, input, normalize, snapshot) {
   supportRecorder?.addBytes('agentInput', Buffer.byteLength(input));
   return recordAsyncStage('agent', async () => {
-    const result = await runAgent(invocation, input);
+    let result;
+    try {
+      result = await runAgent(invocation, input);
+    } catch (error) {
+      assertAgentReviewFresh(snapshot);
+      recordAgentUsage(error?.providerUsage);
+      throw error;
+    }
     assertAgentReviewFresh(snapshot);
+    recordAgentUsage(result.providerUsage);
     if (result.stderr.trim()) {
       console.error(
         `${selectedAgent} wrote diagnostic output:\n${result.stderr.trim()}`,
@@ -1567,6 +1613,7 @@ try {
             generatedAt: new Date().toISOString(),
             ...(model ? { model } : {}),
             ...(reasoning ? { reasoning } : {}),
+            fast,
             accessMode: accessMode.mode,
           },
         };
@@ -1613,6 +1660,7 @@ try {
             generatedAt: new Date().toISOString(),
             ...(model ? { model } : {}),
             ...(reasoning ? { reasoning } : {}),
+            fast,
             accessMode: accessMode.mode,
           },
         };
@@ -1694,6 +1742,7 @@ try {
                   : 'complete',
               ...(model ? { model } : {}),
               ...(reasoning ? { reasoning } : {}),
+              fast,
               accessMode: accessMode.mode,
             },
           },
@@ -1749,6 +1798,7 @@ try {
             binary: agentBinary,
             model,
             reasoning,
+            fast,
             prompt: promptFor(batchPaths, { accessMode, includeChange: false }),
             schema: outputSchema(batchPaths, { includeChange: false }),
             schemaPath,
@@ -1875,6 +1925,7 @@ try {
               binary: agentBinary,
               model,
               reasoning,
+              fast,
               prompt: promptFor([], { accessMode }),
               schema,
               schemaPath,
@@ -1945,6 +1996,7 @@ try {
     } catch (error) {
       if (!(error instanceof ReviewChangedError)) throw error;
       reviewChanged = true;
+      agentUsage = emptyUsageAccumulator();
       console.log('The review changed while notes were generated. Rebuilding the snapshot.');
     }
   } while (reviewChanged && !interrupted);

package/scripts/present.mjs

@@ -20,6 +20,7 @@ import { helpText, parseCliArgs } from './cli-args.mjs';
 import { applyAgentConfigOperation } from './agent-config.mjs';
 import {
   agentReadOnlyWarning,
+  assertFastCompatible,
   assertReasoningSupported,
   codingAgentFromSelectionError,
   codingAgentAvailability,
@@ -33,6 +34,11 @@ import {
 } from './local-target.mjs';
 import { doctorReport } from './doctor.mjs';
 import { accessTokenDirectory } from './access-token.mjs';
+import {
+  emptyUsageAccumulator,
+  reviewUsage,
+  usageSummary,
+} from './agent-usage.mjs';
 import { cacheStatus, clearCache, formatCacheStatus, pruneCache } from './cache.mjs';
 import {
   agentFallbackRecordNeeded,
@@ -256,10 +262,11 @@ if (agentEnabled) {
           }),
       },
     );
-    assertReasoningSupported(selectedAgent, cli.reasoning);
     selectedAgentBinary = codingAgentBinary(selectedAgent, {
       codexBin: cli.codexBin,
     });
+    assertReasoningSupported(selectedAgent, cli.reasoning);
+    assertFastCompatible(selectedAgent, selectedAgentBinary, cli.fast);
     recordSelectedProvider(selectedAgent, selectedAgentBinary);
     supportRecorder?.addStage(
       'agent',
@@ -454,6 +461,7 @@ function chatAgentArguments() {
     ...chatAccessArguments(),
     ...optionalSiteArgument('--chat-model', cli.model),
     ...optionalSiteArgument('--chat-reasoning', cli.reasoning),
+    ...(cli.fast ? ['--chat-fast'] : []),
   ];
 }
 
@@ -778,15 +786,22 @@ function markSnapshotReady() {
 }
 
 function snapshotForPresentation(snapshot) {
-  if (snapshotStateFromSnapshot(snapshot).hasCurrentAgentNotes) {
-    return snapshot;
-  }
-  const content = {
+  const zeroUsage = usageSummary(emptyUsageAccumulator());
+  const hasCurrentNotes = snapshotStateFromSnapshot(snapshot)
+    .hasCurrentAgentNotes;
+  const current = {
     ...snapshot,
+    usage: reviewUsage(zeroUsage, zeroUsage),
+  };
+  if (hasCurrentNotes && snapshot.notes?.fast === cli.fast) return current;
+  const content = {
+    ...current,
     notes: {
       ...snapshot.notes,
-      complete: false,
-      status: 'generating',
+      fast: cli.fast,
+      ...(hasCurrentNotes
+        ? {}
+        : { complete: false, status: 'generating' }),
     },
   };
   delete content.version;

package/scripts/review-chat-context.mjs

@@ -307,8 +307,10 @@ export function makeInput({ kind, context, messages, question, accessMode }) {
   };
 }
 
-function providerResult(provider, input) {
-  return typeof provider === 'function' ? provider(input) : provider.run(input);
+function providerResult(provider, input, context) {
+  return typeof provider === 'function'
+    ? provider(input, context)
+    : provider.run(input, context);
 }
 
 function isExecution(value) {
@@ -324,8 +326,8 @@ function executionPromise(value) {
   return isExecution(value) ? value.promise : value;
 }
 
-export function providerExecution(provider, input) {
-  const result = providerResult(provider, input);
+export function providerExecution(provider, input, context) {
+  const result = providerResult(provider, input, context);
   return {
     promise: Promise.resolve(executionPromise(result)),
     cancel: cancellationFor(result),

package/scripts/review-chat-controller.mjs

@@ -130,9 +130,9 @@ function validatedAnswer(value, paths) {
   }
 }
 
-function executionResult(provider, input) {
+function executionResult(provider, input, context) {
   try {
-    return { execution: providerExecution(provider, input) };
+    return { execution: providerExecution(provider, input, context) };
   } catch (error) {
     return { error };
   }
@@ -424,7 +424,9 @@ export class ReviewChatController {
     thread.error = undefined;
     this.notify();
     this.supervise(thread, run);
-    const result = executionResult(this.provider, input);
+    const result = executionResult(this.provider, input, {
+      reviewFingerprint: run.fingerprint,
+    });
     if (result.error) {
       this.finishFailure(thread, run, result.error);
       return;