diffsplain 0.9.0 → 0.11.0

package/scripts/generate-summaries.mjs

@@ -15,12 +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,
@@ -75,6 +85,7 @@ const valueFlags = new Set([
 const booleanFlags = new Set([
   '--checkout',
   '--force',
+  '--fast',
   '--support-record',
   '--worktree',
   '--no-checkout-access',
@@ -135,10 +146,11 @@ Options:
   --cache-dir PATH    Bare cache for fetched Git objects
   --agent NAME        Use codex, claude, copilot, cursor, or opencode
                       Cursor needs version 2026.08.11 or newer
-                      Without --agent, choose from usable agents in a terminal
+                      Overrides the configured default for this run
   --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
@@ -148,8 +160,9 @@ Options:
   --no-checkout-access
                       Limit notes to the supplied snapshot
 
-Without --agent, an interactive terminal is required. In scripts, pass
---agent NAME. Use diffsplain --no-agent for a plain review.`);
+Without --agent or a configured default, an interactive terminal is required.
+Use diffsplain config agent NAME to set a default. Use diffsplain --no-agent
+for a plain review.`);
   process.exit(0);
 }
 
@@ -176,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',
@@ -375,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(() => {
@@ -1037,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;
@@ -1063,6 +1094,7 @@ function summariesForSnapshot(summaries, snapshot) {
     meta: {
       ...summaries.meta,
       reviewFingerprint: snapshot.notes.reviewFingerprint,
+      usage: currentAgentUsage(),
     },
   };
 }
@@ -1206,14 +1238,20 @@ 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),
     );
   } catch (error) {
-    supportRecorder?.setProvider(requestedAgent || 'unknown');
+    supportRecorder?.setProvider(
+      codingAgentFromSelectionError(error) ||
+        selectedAgent ||
+        requestedAgent ||
+        'unknown',
+    );
     if (error instanceof Error) error.exitCode = 2;
     throw error;
   }
@@ -1258,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();
@@ -1309,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();
@@ -1326,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()}`,
@@ -1560,6 +1613,7 @@ try {
             generatedAt: new Date().toISOString(),
             ...(model ? { model } : {}),
             ...(reasoning ? { reasoning } : {}),
+            fast,
             accessMode: accessMode.mode,
           },
         };
@@ -1606,6 +1660,7 @@ try {
             generatedAt: new Date().toISOString(),
             ...(model ? { model } : {}),
             ...(reasoning ? { reasoning } : {}),
+            fast,
             accessMode: accessMode.mode,
           },
         };
@@ -1687,6 +1742,7 @@ try {
                   : 'complete',
               ...(model ? { model } : {}),
               ...(reasoning ? { reasoning } : {}),
+              fast,
               accessMode: accessMode.mode,
             },
           },
@@ -1742,6 +1798,7 @@ try {
             binary: agentBinary,
             model,
             reasoning,
+            fast,
             prompt: promptFor(batchPaths, { accessMode, includeChange: false }),
             schema: outputSchema(batchPaths, { includeChange: false }),
             schemaPath,
@@ -1868,6 +1925,7 @@ try {
               binary: agentBinary,
               model,
               reasoning,
+              fast,
               prompt: promptFor([], { accessMode }),
               schema,
               schemaPath,
@@ -1938,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

@@ -17,9 +17,12 @@ import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { helpText, parseCliArgs } from './cli-args.mjs';
+import { applyAgentConfigOperation } from './agent-config.mjs';
 import {
   agentReadOnlyWarning,
+  assertFastCompatible,
   assertReasoningSupported,
+  codingAgentFromSelectionError,
   codingAgentAvailability,
   codingAgentBinary,
   selectCodingAgent,
@@ -31,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,
@@ -126,6 +134,22 @@ if (cli.version) {
   console.log(`diffsplain ${packageJson.version}`);
   process.exit(0);
 }
+if (cli.config) {
+  try {
+    const result = applyAgentConfigOperation(cli.config);
+    if (result.kind === 'show') {
+      console.log(result.agent ?? 'No default coding agent is configured.');
+    } else if (result.kind === 'set') {
+      console.log(`Default coding agent set to "${result.agent}".`);
+    } else {
+      console.log('Default coding agent unset.');
+    }
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
 if (cli.doctor) {
   if (cli.doctor.deep) {
     console.error(
@@ -238,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',
@@ -263,7 +288,12 @@ if (agentEnabled) {
       agentArgs.push('--provider-read-only-warning-emitted');
     }
   } catch (error) {
-    recordSelectedProvider(cli.agent || 'unknown');
+    recordSelectedProvider(
+      codingAgentFromSelectionError(error) ||
+        selectedAgent ||
+        cli.agent ||
+        'unknown',
+    );
     supportRecorder?.addStage(
       'agent',
       performance.now() - selectionStarted,
@@ -338,9 +368,7 @@ writeFileSync(accessPath, access, { mode: 0o600 });
 chmodSync(accessPath, 0o600);
 if (agentEnabled) {
   feedArgs.push('--ignore-summary-watch');
-  if (accessMode.mode === 'snapshot-only') {
-    agentArgs.push('--snapshot', rawSnapshotPath);
-  }
+  agentArgs.push('--snapshot', rawSnapshotPath);
 }
 
 const snapshotStarted = performance.now();
@@ -433,6 +461,7 @@ function chatAgentArguments() {
     ...chatAccessArguments(),
     ...optionalSiteArgument('--chat-model', cli.model),
     ...optionalSiteArgument('--chat-reasoning', cli.reasoning),
+    ...(cli.fast ? ['--chat-fast'] : []),
   ];
 }
 
@@ -506,59 +535,91 @@ function startSite() {
   child.on('error', handleSiteError);
 }
 
+function savedReviewFingerprint(notes) {
+  if (!notes) return undefined;
+  if (notes.agentReviewFingerprint) return notes.agentReviewFingerprint;
+  return notes.reviewFingerprint;
+}
+
+function snapshotReviewFingerprint(snapshot) {
+  const savedFingerprint = savedReviewFingerprint(snapshot.notes);
+  if (savedFingerprint) return savedFingerprint;
+  const reviewData = {
+    repo: {
+      name: snapshot.repo.name,
+      base: snapshot.repo.base,
+      head: snapshot.repo.head,
+      branch: snapshot.repo.branch,
+      baseBranch: snapshot.repo.baseBranch,
+      remote: snapshot.repo.remote,
+      targetKind: snapshot.repo.target?.kind,
+    },
+    change: {
+      title: snapshot.change.title,
+      number: snapshot.change.number,
+    },
+    files: snapshot.files.map((file) => ({
+      path: file.path,
+      oldPath: file.oldPath,
+      status: file.status,
+      additions: file.additions,
+      deletions: file.deletions,
+      isBinary: file.isBinary,
+      patch: file.patch,
+    })),
+  };
+  return createHash('sha256')
+    .update(JSON.stringify(reviewData))
+    .digest('hex');
+}
+
+function noteMetadataMatches(notes, fingerprint) {
+  return [
+    notes.complete,
+    notes.fresh,
+    notes.generatedFor === fingerprint,
+    notes.accessMode === accessMode.mode,
+  ].every(Boolean);
+}
+
+function normalizedAgentSetting(value) {
+  return value ?? null;
+}
+
+function agentSettingsMatch(notes) {
+  return [
+    notes.agent === selectedAgent,
+    normalizedAgentSetting(notes.model) === normalizedAgentSetting(cli.model),
+    normalizedAgentSetting(notes.reasoning) ===
+      normalizedAgentSetting(cli.reasoning),
+  ].every(Boolean);
+}
+
+function emptyReview(files) {
+  return Array.isArray(files) && files.length === 0;
+}
+
+function hasCurrentAgentNotes(snapshot, fingerprint) {
+  const notes = snapshot.notes;
+  if (!savedReviewFingerprint(notes)) return false;
+  if (!noteMetadataMatches(notes, fingerprint)) return false;
+  if (emptyReview(snapshot.files)) return true;
+  return agentSettingsMatch(notes);
+}
+
+function snapshotStateFromSnapshot(snapshot) {
+  const fingerprint = snapshotReviewFingerprint(snapshot);
+  return {
+    fingerprint,
+    hasCurrentAgentNotes: hasCurrentAgentNotes(snapshot, fingerprint),
+  };
+}
+
 function snapshotState() {
   try {
-    const snapshot = JSON.parse(readFileSync(reviewSnapshotPath, 'utf8'));
-    if (snapshot.notes?.reviewFingerprint) {
-      const fingerprint =
-        snapshot.notes.agentReviewFingerprint ||
-        snapshot.notes.reviewFingerprint;
-      const emptyReview =
-        Array.isArray(snapshot.files) && snapshot.files.length === 0;
-      return {
-        fingerprint,
-        hasCurrentAgentNotes:
-          snapshot.notes.complete &&
-          snapshot.notes.fresh &&
-          snapshot.notes.generatedFor === fingerprint &&
-          snapshot.notes.accessMode === accessMode.mode &&
-          (emptyReview ||
-            (snapshot.notes.agent === selectedAgent &&
-              (snapshot.notes.model || null) === (cli.model || null) &&
-              (snapshot.notes.reasoning || null) ===
-                (cli.reasoning || null))),
-      };
-    }
-    const reviewData = {
-      repo: {
-        name: snapshot.repo.name,
-        base: snapshot.repo.base,
-        head: snapshot.repo.head,
-        branch: snapshot.repo.branch,
-        baseBranch: snapshot.repo.baseBranch,
-        remote: snapshot.repo.remote,
-        targetKind: snapshot.repo.target?.kind,
-      },
-      change: {
-        title: snapshot.change.title,
-        number: snapshot.change.number,
-      },
-      files: snapshot.files.map((file) => ({
-        path: file.path,
-        oldPath: file.oldPath,
-        status: file.status,
-        additions: file.additions,
-        deletions: file.deletions,
-        isBinary: file.isBinary,
-        patch: file.patch,
-      })),
-    };
-    return {
-      fingerprint: createHash('sha256')
-        .update(JSON.stringify(reviewData))
-        .digest('hex'),
-      hasCurrentAgentNotes: false,
-    };
+    return snapshotStateFromSnapshot(
+      JSON.parse(readFileSync(reviewSnapshotPath, 'utf8')),
+    );
   } catch {
     return undefined;
   }
@@ -699,12 +760,16 @@ function scheduleAgent(fingerprint) {
   if (agent) {
     if (selectedFingerprint !== agentFingerprint) {
       queuedFingerprint = selectedFingerprint;
+      console.log(
+        'Review changed while notes were generated. Restarting agent notes...',
+      );
       agent.kill('SIGTERM');
     }
     return;
   }
   clearTimeout(agentTimer);
   const delay = agentFingerprint ? 300 : 0;
+  console.log('Preparing agent notes...');
   agentTimer = setTimeout(() => runAgent(selectedFingerprint), delay);
 }
 
@@ -720,11 +785,44 @@ function markSnapshotReady() {
   );
 }
 
+function snapshotForPresentation(snapshot) {
+  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,
+      fast: cli.fast,
+      ...(hasCurrentNotes
+        ? {}
+        : { complete: false, status: 'generating' }),
+    },
+  };
+  delete content.version;
+  delete content.generatedAt;
+  return {
+    version: createHash('sha256')
+      .update(JSON.stringify(content))
+      .digest('hex')
+      .slice(0, 12),
+    generatedAt: new Date().toISOString(),
+    ...content,
+  };
+}
+
 function seedPresentationSnapshot() {
-  const raw = readFileSync(rawSnapshotPath);
+  const snapshot = snapshotForPresentation(
+    JSON.parse(readFileSync(rawSnapshotPath, 'utf8')),
+  );
   mkdirSync(dirname(outputPath), { recursive: true });
   const pendingOutput = `${outputPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
-  writeFileSync(pendingOutput, raw);
+  writeFileSync(pendingOutput, `${JSON.stringify(snapshot, null, 2)}\n`);
   renameSync(pendingOutput, outputPath);
 }
 

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),