diffsplain 0.9.0 → 0.11.0

package/scripts/review-chat-controller.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
 import {
   ReviewChatError,
   chatInputLimit,
@@ -21,6 +22,45 @@ import {
 
 const noChange = () => {};
 const snapshotOnly = { mode: 'snapshot-only' };
+const defaultRunTimeoutMs = 120_000;
+const maximumProgressIntervalMs = 30_000;
+
+function runTimeout(options) {
+  const timeoutMs = options.runTimeoutMs ?? defaultRunTimeoutMs;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error('Review chat run timeout must be a positive integer');
+  }
+  return timeoutMs;
+}
+
+function progressInterval(timeoutMs) {
+  return Math.min(maximumProgressIntervalMs, Math.max(10, Math.floor(timeoutMs / 2)));
+}
+
+function timeoutError(timeoutMs) {
+  const duration = timeoutMs >= 1_000
+    ? `${Math.round(timeoutMs / 1_000)} seconds`
+    : `${timeoutMs}ms`;
+  return new Error(`The chat provider timed out after ${duration}.`);
+}
+
+function lifecycleError(error) {
+  return typeof error?.lifecycleMessage === 'string'
+    ? error.lifecycleMessage
+    : publicError(error);
+}
+
+function compactedMessages(run, answer) {
+  return [{ role: 'compacted', answer }, ...run.preserved];
+}
+
+function oversizedCompaction(thread, run, answer, inputLimitBytes) {
+  if (run.kind !== 'compact') return false;
+  return inputBytes(
+    compactedMessages(run, answer),
+    thread.pendingQuestion,
+  ) > inputLimitBytes;
+}
 function snapshotRead(path) {
   try {
     return { value: JSON.parse(readFileSync(path, 'utf8')) };
@@ -90,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 };
   }
@@ -133,6 +173,10 @@ export class ReviewChatController {
     this.snapshotPath = chatSnapshotPath(options);
     this.provider = options.provider;
     this.onChange = typeof options.onChange === 'function' ? options.onChange : noChange;
+    this.onLifecycle = typeof options.onLifecycle === 'function'
+      ? options.onLifecycle
+      : noChange;
+    this.runTimeoutMs = runTimeout(options);
     this.inputLimitBytes = chatInputLimit(options);
     this.accessMode = options.accessMode || snapshotOnly;
     this.threads = new Map();
@@ -237,6 +281,53 @@ export class ReviewChatController {
     thread.activeRunId = undefined;
   }
 
+  elapsed(run) {
+    return Math.max(0, Math.round(performance.now() - run.startedAt));
+  }
+
+  emitLifecycleSafely(type, run, details = {}) {
+    try {
+      this.onLifecycle({
+        type,
+        kind: run.kind,
+        runId: run.id,
+        elapsedMs: this.elapsed(run),
+        terminal: details.terminal === true,
+        ...(details.error ? { error: lifecycleError(details.error) } : {}),
+      });
+    } catch {}
+  }
+
+  clearSupervision(run) {
+    if (run.timeoutTimer) clearTimeout(run.timeoutTimer);
+    if (run.progressTimer) clearInterval(run.progressTimer);
+    run.timeoutTimer = undefined;
+    run.progressTimer = undefined;
+  }
+
+  finishLifecycle(run, type, error) {
+    if (run.lifecycle !== 'active') return false;
+    run.lifecycle = type;
+    this.clearSupervision(run);
+    this.emitLifecycleSafely(type, run, { terminal: true, error });
+    return true;
+  }
+
+  supervise(thread, run) {
+    run.lifecycle = 'active';
+    run.startedAt = performance.now();
+    this.emitLifecycleSafely('start', run);
+    run.progressTimer = setInterval(() => {
+      if (run.lifecycle === 'active') this.emitLifecycleSafely('progress', run);
+    }, progressInterval(this.runTimeoutMs));
+    run.progressTimer.unref?.();
+    run.timeoutTimer = setTimeout(
+      () => this.timeoutRun(thread, run),
+      this.runTimeoutMs,
+    );
+    run.timeoutTimer.unref?.();
+  }
+
   markFailure(thread, run, error) {
     this.clearRun(thread);
     thread.error = publicError(error);
@@ -244,7 +335,9 @@ export class ReviewChatController {
   }
 
   markUnavailableRun(thread, run) {
-    this.markFailure(thread, run, new Error('The current review snapshot is not available.'));
+    const error = new Error('The current review snapshot is not available.');
+    if (!this.finishLifecycle(run, 'failure', error)) return;
+    this.markFailure(thread, run, error);
     this.refresh({ notify: false });
     this.notify();
   }
@@ -266,6 +359,7 @@ export class ReviewChatController {
 
   finishFailure(thread, run, error) {
     if (this.fenceChangedReview(thread, run)) return;
+    if (!this.finishLifecycle(run, 'failure', error)) return;
     this.markFailure(thread, run, error);
     this.notify();
   }
@@ -281,15 +375,7 @@ export class ReviewChatController {
   }
 
   completeCompaction(thread, run, answer) {
-    const messages = [{ role: 'compacted', answer }, ...run.preserved];
-    if (inputBytes(messages, thread.pendingQuestion) > this.inputLimitBytes) {
-      this.finishFailure(
-        thread,
-        run,
-        new Error('The compacted chat history still exceeds the input limit.'),
-      );
-      return;
-    }
+    const messages = compactedMessages(run, answer);
     this.clearRun(thread);
     thread.messages = messages;
     thread.needsCompaction = false;
@@ -309,6 +395,20 @@ export class ReviewChatController {
       this.finishFailure(thread, run, result.error);
       return;
     }
+    if (oversizedCompaction(
+      thread,
+      run,
+      result.answer,
+      this.inputLimitBytes,
+    )) {
+      this.finishFailure(
+        thread,
+        run,
+        new Error('The compacted chat history still exceeds the input limit.'),
+      );
+      return;
+    }
+    if (!this.finishLifecycle(run, 'complete')) return;
     this.completeRun(thread, run, result.answer);
   }
 
@@ -323,7 +423,10 @@ export class ReviewChatController {
     thread.status = run.kind === 'compact' ? 'compacting' : 'running';
     thread.error = undefined;
     this.notify();
-    const result = executionResult(this.provider, input);
+    this.supervise(thread, run);
+    const result = executionResult(this.provider, input, {
+      reviewFingerprint: run.fingerprint,
+    });
     if (result.error) {
       this.finishFailure(thread, run, result.error);
       return;
@@ -401,13 +504,35 @@ export class ReviewChatController {
     }
   }
 
+  timeoutRun(thread, run) {
+    if (!this.currentRun(thread, run)) return;
+    const error = timeoutError(this.runTimeoutMs);
+    if (!this.finishLifecycle(run, 'timeout', error)) return;
+    this.clearRun(thread);
+    this.cancelProvider(run);
+    thread.error = publicError(error);
+    Object.assign(thread, runState(run));
+    this.notify();
+  }
+
+  prepareCancellation(thread, run) {
+    if (!this.finishLifecycle(run, 'cancel')) return false;
+    this.clearRun(thread);
+    this.cancelProvider(run);
+    return true;
+  }
+
+  restoreCancelledState(thread, run, stale) {
+    if (stale) return;
+    Object.assign(thread, cancelledState(run));
+    thread.error = undefined;
+  }
+
   cancelRun(thread, { stale = false } = {}) {
     const run = thread.run;
     if (!run) return false;
-    this.clearRun(thread);
-    this.cancelProvider(run);
-    if (!stale) Object.assign(thread, cancelledState(run));
-    if (!stale) thread.error = undefined;
+    if (!this.prepareCancellation(thread, run)) return false;
+    this.restoreCancelledState(thread, run, stale);
     return true;
   }
 

package/scripts/review-chat-provider.mjs

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import {
   agentCommand,
   parseAgentResponse,
+  parseAgentUsage,
 } from './coding-agents.mjs';
 
 const maximumProviderOutputBytes = 1024 * 1024;
@@ -41,10 +42,21 @@ function childOutput(chunks) {
   return Buffer.concat(chunks).toString('utf8');
 }
 
-function childFailure(agent, status, signal, stdout, stderr) {
+function childStatus(status, signal) {
+  return status ?? signal;
+}
+
+function childDiagnosticSuffix(stdout, stderr) {
   const detail = stderr.trim() || stdout.trim();
-  const suffix = detail ? `: ${detail.slice(-600)}` : '';
-  return new Error(`${agent} exited with status ${status ?? signal}${suffix}`);
+  return detail ? `: ${detail.slice(-600)}` : '';
+}
+
+function childFailure(agent, status, signal, stdout, stderr) {
+  const observedStatus = childStatus(status, signal);
+  const suffix = childDiagnosticSuffix(stdout, stderr);
+  const error = new Error(`${agent} exited with status ${observedStatus}${suffix}`);
+  error.lifecycleMessage = `${agent} exited with status ${observedStatus}`;
+  return error;
 }
 
 function aborted(signal) {
@@ -88,8 +100,10 @@ function providerOptions(options) {
     binary: providerBinary(options, agent),
     model: options.model,
     reasoning: options.reasoning,
+    fast: options.fast === true,
     accessMode: options.accessMode,
     env: providerEnvironment(options),
+    onUsage: typeof options.onUsage === 'function' ? options.onUsage : noChange,
   };
 }
 
@@ -113,6 +127,7 @@ function providerInvocation(options, request, paths) {
     binary: options.binary,
     model: options.model,
     reasoning: options.reasoning,
+    fast: options.fast,
     prompt: request.prompt,
     schema: request.responseSchema,
     schemaPath: paths.schemaPath,
@@ -134,12 +149,15 @@ function preparedProviderRequest(options, request) {
 }
 
 class ChildExecution {
-  constructor({ invocation, input, agent, signal, temporary }) {
+  constructor({ invocation, input, agent, signal, temporary, onUsage, usageContext }) {
     this.invocation = invocation;
     this.input = input;
     this.agent = agent;
     this.signal = signal;
     this.temporary = temporary;
+    this.onUsage = onUsage;
+    this.usageContext = usageContext;
+    this.usageReported = false;
     this.child = undefined;
     this.settled = false;
     this.closed = false;
@@ -266,11 +284,23 @@ class ChildExecution {
   finishClose() {
     if (this.closed) return;
     this.closed = true;
+    this.reportUsage();
     this.clearForceKill();
     removeTemporary(this.temporary);
     this.resolveFinished();
   }
 
+  reportUsage() {
+    if (this.usageReported) return;
+    this.usageReported = true;
+    try {
+      this.onUsage({
+        ...this.usageContext,
+        usage: parseAgentUsage(this.agent, childOutput(this.stdout)),
+      });
+    } catch {}
+  }
+
   resolve(value) {
     this.settle(this.resolvePromise, value);
   }
@@ -289,6 +319,7 @@ class ChildExecution {
 
   closeChild(status, signal) {
     this.clearForceKill();
+    this.reportUsage();
     if (!this.settled) {
       const error = closeError(this, status, signal);
       if (error) this.reject(error);
@@ -314,7 +345,7 @@ function trackExecution(executions, execution) {
   return execution;
 }
 
-function runRequest(options, executions, request) {
+function runRequest(options, executions, request, usageContext = {}) {
   const prepared = preparedProviderRequest(options, request);
   const controller = new AbortController();
   const execution = providerChild({
@@ -323,6 +354,8 @@ function runRequest(options, executions, request) {
     agent: options.agent,
     signal: controller.signal,
     temporary: prepared.temporary,
+    onUsage: options.onUsage,
+    usageContext,
   });
   const tracked = trackExecution(executions, execution);
   return {
@@ -342,8 +375,8 @@ export function createCodingAgentChatProvider(options = {}) {
   const configured = providerOptions(options);
   const executions = new Set();
   return {
-    run(request) {
-      return runRequest(configured, executions, request);
+    run(request, context) {
+      return runRequest(configured, executions, request, context);
     },
     close() {
       closeExecutions(executions);

package/scripts/serve-built.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { watchFile, unwatchFile } from 'node:fs';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFileSync, watchFile, unwatchFile } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { dirname, extname, resolve, sep } from 'node:path';
@@ -11,6 +11,14 @@ import {
   createCodingAgentChatProvider,
   createReviewChat,
 } from './review-chat.mjs';
+import { publicError } from './review-chat-context.mjs';
+import {
+  emptyUsageAccumulator,
+  formatReviewUsage,
+  recordUsage,
+  reviewUsage,
+  usageSummary,
+} from './agent-usage.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const clientRoot = resolve(root, 'dist');
@@ -37,6 +45,7 @@ const chatAgent = option('--chat-agent');
 const chatBinary = option('--chat-binary', chatAgent);
 const chatModel = option('--chat-model');
 const chatReasoning = option('--chat-reasoning');
+const chatFast = rawArgs.includes('--chat-fast');
 const chatAccessMode = option('--chat-access-mode', 'snapshot-only');
 const chatAccessRoot = option('--chat-access-root');
 if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
@@ -265,7 +274,7 @@ function matchingAccess(value, expectedValue) {
 
 async function fetchAsset(url) {
   if (url.pathname === '/diff-data.json') {
-    return fileResponse(output, { live: true });
+    return liveSnapshotResponse();
   }
   const pathname = decodeURIComponent(url.pathname);
   const file = resolve(
@@ -278,6 +287,44 @@ async function fetchAsset(url) {
   return fileResponse(file);
 }
 
+async function parsedLiveSnapshot() {
+  try {
+    return JSON.parse(await readFile(output, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function liveSnapshotVersion(snapshot, usage) {
+  return createHash('sha256')
+    .update(JSON.stringify({ version: snapshot.version, usage }))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+function snapshotNoteSummary(snapshot) {
+  return snapshot?.usage?.agentNotes ||
+    usageSummary(emptyUsageAccumulator());
+}
+
+function snapshotResponse(snapshot, usage) {
+  return jsonResponse({
+    ...snapshot,
+    version: liveSnapshotVersion(snapshot, usage),
+    usage,
+  });
+}
+
+async function liveSnapshotResponse() {
+  const snapshot = await parsedLiveSnapshot();
+  if (!snapshot) return fileResponse(output, { live: true });
+  const fingerprint = snapshot?.notes?.reviewFingerprint;
+  if (!fingerprint) return fileResponse(output, { live: true });
+  const chatSummary = currentChatUsage(fingerprint);
+  const usage = reviewUsage(snapshotNoteSummary(snapshot), chatSummary);
+  return snapshotResponse(snapshot, usage);
+}
+
 function jsonResponse(value, status = 200) {
   return webResponse(JSON.stringify(value), {
     status,
@@ -366,6 +413,85 @@ function broadcastEvent(name, data = {}) {
   }
 }
 
+function lifecycleKind(kind) {
+  return kind === 'compact' ? 'history compaction' : 'answer';
+}
+
+function lifecycleStatus(type) {
+  return {
+    start: 'started',
+    progress: 'still running',
+    complete: 'completed',
+    failure: 'failed',
+    timeout: 'timed out',
+    cancel: 'cancelled',
+  }[type] || type;
+}
+
+function elapsedText(milliseconds) {
+  if (milliseconds < 1_000) return `${milliseconds}ms`;
+  return `${Math.round(milliseconds / 1_000)}s`;
+}
+
+function logChatLifecycle(event) {
+  const elapsed = event.type === 'start' ? '' : ` (${elapsedText(event.elapsedMs)})`;
+  const error = event.error ? `: ${event.error}` : '';
+  console.log(
+    `Diffsplain chat #${event.runId}: ${lifecycleKind(event.kind)} ${lifecycleStatus(event.type)}${elapsed}${error}`,
+  );
+}
+
+function logObservedError(area, error) {
+  console.log(`Diffsplain ${area.replaceAll('-', ' ')} error: ${publicError(error)}`);
+}
+
+let chatUsageFingerprint;
+let chatUsage = emptyUsageAccumulator();
+let reviewChat;
+
+function snapshotUsageState() {
+  try {
+    const snapshot = JSON.parse(readFileSync(output, 'utf8'));
+    return {
+      agentNotes: snapshot.usage?.agentNotes,
+      fingerprint: snapshot.notes?.reviewFingerprint,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function currentChatUsage(fingerprint) {
+  return fingerprint === chatUsageFingerprint
+    ? usageSummary(chatUsage)
+    : usageSummary(emptyUsageAccumulator());
+}
+
+function resetChatUsage(fingerprint) {
+  if (fingerprint === chatUsageFingerprint) return;
+  chatUsageFingerprint = fingerprint;
+  chatUsage = emptyUsageAccumulator();
+}
+
+function recordChatUsage({ reviewFingerprint, usage }) {
+  const snapshot = snapshotUsageState();
+  if (
+    !reviewFingerprint ||
+    snapshot.fingerprint !== reviewFingerprint ||
+    reviewChat?.getState().fingerprint !== reviewFingerprint
+  ) {
+    return;
+  }
+  resetChatUsage(reviewFingerprint);
+  chatUsage = recordUsage(chatUsage, usage);
+  const totals = reviewUsage(
+    snapshot.agentNotes || usageSummary(emptyUsageAccumulator()),
+    usageSummary(chatUsage),
+  );
+  console.log(formatReviewUsage(totals));
+  broadcastEvent('update');
+}
+
 const chatProviderAccess = chatAccessMode === 'checkout-read-only'
   ? { mode: chatAccessMode, root: resolve(chatAccessRoot) }
   : { mode: chatAccessMode, reason: 'target-mismatch' };
@@ -375,14 +501,17 @@ const chatProvider = chatAgent
       binary: chatBinary,
       model: chatModel,
       reasoning: chatReasoning,
+      fast: chatFast,
       accessMode: chatProviderAccess,
+      onUsage: recordChatUsage,
     })
   : undefined;
-const reviewChat = createReviewChat({
+reviewChat = createReviewChat({
   snapshotPath: chatSnapshot,
   provider: chatProvider,
   accessMode: chatProviderAccess,
   onChange: () => broadcastEvent('chat'),
+  onLifecycle: logChatLifecycle,
 });
 
 function requestAuthorityError(request) {
@@ -473,6 +602,7 @@ async function sendChatCommand(request, response) {
     const status = result.accepted ? 202 : 200;
     await send(response, jsonResponse(result.state, status));
   } catch (error) {
+    logObservedError('chat-command', error);
     const failure = chatCommandError(error);
     await send(response, jsonResponse({ error: failure.message }, failure.status));
   }
@@ -565,9 +695,10 @@ async function containHandlerFailure(response) {
 }
 
 const server = createServer((request, response) => {
-  void handleRequest(request, response).catch(() =>
-    containHandlerFailure(response),
-  );
+  void handleRequest(request, response).catch((error) => {
+    logObservedError('request-handler', error);
+    return containHandlerFailure(response);
+  });
 });
 
 watchFile(output, { interval: 100 }, (current, previous) => {
@@ -575,6 +706,7 @@ watchFile(output, { interval: 100 }, (current, previous) => {
     return;
   }
   reviewChat.refresh();
+  resetChatUsage(reviewChat.getState().fingerprint);
   broadcastEvent('update');
 });