diffsplain 0.9.0 → 0.10.0

package/scripts/present.mjs

@@ -17,9 +17,11 @@ 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,
   assertReasoningSupported,
+  codingAgentFromSelectionError,
   codingAgentAvailability,
   codingAgentBinary,
   selectCodingAgent,
@@ -126,6 +128,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(
@@ -263,7 +281,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 +361,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();
@@ -506,59 +527,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 +752,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 +777,37 @@ function markSnapshotReady() {
   );
 }
 
+function snapshotForPresentation(snapshot) {
+  if (snapshotStateFromSnapshot(snapshot).hasCurrentAgentNotes) {
+    return snapshot;
+  }
+  const content = {
+    ...snapshot,
+    notes: {
+      ...snapshot.notes,
+      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-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')) };
@@ -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,6 +423,7 @@ export class ReviewChatController {
     thread.status = run.kind === 'compact' ? 'compacting' : 'running';
     thread.error = undefined;
     this.notify();
+    this.supervise(thread, run);
     const result = executionResult(this.provider, input);
     if (result.error) {
       this.finishFailure(thread, run, result.error);
@@ -401,13 +502,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

@@ -41,10 +41,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) {

package/scripts/serve-built.mjs

@@ -11,6 +11,7 @@ import {
   createCodingAgentChatProvider,
   createReviewChat,
 } from './review-chat.mjs';
+import { publicError } from './review-chat-context.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const clientRoot = resolve(root, 'dist');
@@ -366,6 +367,38 @@ 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)}`);
+}
+
 const chatProviderAccess = chatAccessMode === 'checkout-read-only'
   ? { mode: chatAccessMode, root: resolve(chatAccessRoot) }
   : { mode: chatAccessMode, reason: 'target-mismatch' };
@@ -383,6 +416,7 @@ const reviewChat = createReviewChat({
   provider: chatProvider,
   accessMode: chatProviderAccess,
   onChange: () => broadcastEvent('chat'),
+  onLifecycle: logChatLifecycle,
 });
 
 function requestAuthorityError(request) {
@@ -473,6 +507,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 +600,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) => {