wisp-agents 0.15.0 → 0.17.0

package/server/adapters/grok.js

@@ -9,7 +9,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
 
 const BIN = process.env.WISP_GROK_BIN || 'grok';
 
@@ -19,6 +19,9 @@ const PERMISSION_MODES = {
   auto: 'bypassPermissions',
 };
 const EFFORT_ORDER = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+// A headless run refuses what would need approval and names it on stderr, once per call:
+// "permission required: Edit calc.py was not run, as a headless run cannot ask for approval".
+const REFUSED = /permission required: (\S+) ?(.*?) was not run\b/g;
 
 export default {
   id: 'grok',
@@ -75,6 +78,7 @@ export default {
     let session = null;
     let sawResult = false;
     let error = null;
+    let carry = ''; // a stderr line still being written
 
     const handle = spawnJsonl({
       bin: BIN,
@@ -82,6 +86,11 @@ export default {
       cwd,
       env: { ...process.env, GROK_DISABLE_AUTOUPDATER: '1' },
       onEvent,
+      onStderr(chunk) {
+        const lines = (carry + chunk).split('\n');
+        carry = lines.pop();
+        for (const [, tool, detail] of lines.join('\n').matchAll(REFUSED)) onEvent({ type: 'blocked', tool, detail: detail.replace(/ \(workflow .*\)$/, '') });
+      },
       onJson(msg) {
         if (msg.session_id && msg.session_id !== session) onEvent({ type: 'session', id: (session = msg.session_id) });
         // Subagent traffic carries its parent's tool id; only the main conversation is shown.
@@ -137,7 +146,7 @@ export default {
       },
       onClose({ code, signal, stderr, stopped }) {
         if (sawResult) return;
-        onEvent({ type: 'result', isError: true, stopped, text: error || stderr || `grok exited with ${signal || `code ${code}`}` });
+        onEvent({ type: 'result', isError: true, stopped, text: error || stderr || exitText('grok', code, signal) });
       },
     });
     handle.done.finally(() => fs.rmSync(tmp, { recursive: true, force: true }));
@@ -232,6 +241,12 @@ function describeMcp(tool, input) {
       return { kind: 'agent', label: `Delegating to ${clip([...new Set((input.tasks || []).map((t) => t.subagent))].join(', ') || 'subagents', 60)}` };
     case 'wisp__subagent_results':
       return { kind: 'agent', label: 'Waiting on subagents' };
+    case 'wisp__wisp_stats':
+      return { kind: 'tool', label: 'Reading wisp stats' };
+    case 'wisp__wisp_sessions':
+      return { kind: 'tool', label: 'Listing wisp tasks' };
+    case 'wisp__wisp_session':
+      return { kind: 'tool', label: `Reading wisp task ${clip(input?.id || '', 40)}` };
     default:
       return { kind: 'tool', label: `Using ${tool.split('__').join(' · ') || 'an integration'}` };
   }

package/server/adapters/index.js

@@ -7,9 +7,14 @@
 //                                                  efforts list wins); omit if the CLI has none
 //     askTool: string | null | undefined           how the agent sees wisp's ask_user MCP tool;
 //                                                  null = can't inject MCP, ask via a question block
+//     approveTool?: string                         its permission prompts go to wisp's `approve` MCP
+//                                                  tool (live approval); omit if it can't route them
+//     permission?(tool, input, cwd): { tool, action, detail, why? }   what a live approval is about
 //     detect(): Promise<{ available, version?, error?, models? }>   models overrides the static list
 //     resumeCommand({ resumeId, model, effort }): string[]   argv to continue the session interactively
-//     run({ prompt, cwd, resumeId, mode, model, effort, systemPrompt, onEvent }): { stop(), done: Promise }
+//     run({ prompt, cwd, resumeId, mode, model, effort, systemPrompt, grants, onEvent }): { stop(), done: Promise }
+//                                                  grants: `rule`s from its own blocked events the
+//                                                  user allowed, for this turn only
 //   }
 //
 // onEvent receives normalized events:
@@ -19,6 +24,8 @@
 //   { type: 'text', text }                          intermediate assistant prose
 //   { type: 'thinking' }
 //   { type: 'change', file, op, edits: [{ before, after }] }
+//   { type: 'blocked', tool, detail, rule? }        a call its permissions refused; rule: what allows
+//                                                  exactly that on a retry (none: retry in Full auto)
 //   { type: 'result', text, isError, stopped?, stats? }   exactly once, at the end
 //
 // mode is one of: plan (read-only), edits (auto-accept file edits), auto (no permission prompts).
@@ -31,7 +38,23 @@ import cursor from './cursor.js';
 import antigravity from './antigravity.js';
 import grok from './grok.js';
 
-export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity, grok].map((a) => [a.id, a]));
+// The shape above, checked when wisp starts: a missing piece fails loudly here, not mid-run.
+function checked(a) {
+  const missing = [
+    typeof a.id !== 'string' && 'id',
+    typeof a.name !== 'string' && 'name',
+    !Array.isArray(a.models) && 'models',
+    a.askTool !== null && a.askTool !== undefined && typeof a.askTool !== 'string' && 'askTool',
+    a.approveTool !== undefined && (typeof a.approveTool !== 'string' || typeof a.permission !== 'function') && 'approveTool + permission()',
+    typeof a.detect !== 'function' && 'detect()',
+    typeof a.run !== 'function' && 'run()',
+    a.resumeCommand !== undefined && typeof a.resumeCommand !== 'function' && 'resumeCommand()',
+  ].filter(Boolean);
+  if (missing.length) throw new Error(`adapter ${a.id || '?'}: missing or wrong ${missing.join(', ')}`);
+  return a;
+}
+
+export const adapters = Object.fromEntries([claude, codex, opencode, cursor, antigravity, grok].map((a) => [a.id, checked(a)]));
 
 const detected = new Map();
 

package/server/adapters/opencode.js

@@ -1,8 +1,26 @@
 // opencode adapter — drives `opencode run --format json` (one JSON event per line).
 
-import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { toolsDir } from '../util.js';
+import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
 
-const BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
+// Where opencode lives when it isn't on PATH: the copy wisp installs (POST /agents/install),
+// and the official install script's folder (it edits your shell profile, which an app started
+// from the Dock or a service never reads).
+export const fallbackBins = () => [path.join(toolsDir(), 'node_modules', '.bin', exe), path.join(os.homedir(), '.opencode', 'bin', process.platform === 'win32' ? 'opencode.exe' : 'opencode')];
+let BIN = process.env.WISP_OPENCODE_BIN || 'opencode';
+// Rate-limited (the free models, mostly), `opencode run` keeps retrying and prints nothing, so
+// the task would sit at "Starting up" for good. Its error log says so: give it this long to get
+// through, then stop and tell the user what to do.
+const rateLimitGrace = () => Number(process.env.WISP_RATE_LIMIT_GRACE_MS) || 60_000;
+const RATE_LIMITED = /Rate limit exceeded|Too Many Requests|status(?:Code)?[=: ]+429\b/i;
+// `run` answers every permission prompt itself and says so on stderr (cli/cmd/run.ts):
+// "! permission requested: bash (npm publish); auto-rejecting".
+const REJECTED = /permission requested: ([\w.-]+) \((.*?)\); auto-rejecting/g;
+const ANSI = /\x1b\[[0-9;]*m/g;
 
 export default {
   id: 'opencode',
@@ -16,7 +34,16 @@ export default {
   },
 
   async detect() {
-    const found = await detectVersion(BIN);
+    let found = await detectVersion(BIN);
+    if (!found.available && !process.env.WISP_OPENCODE_BIN) {
+      for (const bin of fallbackBins().filter((b) => fs.existsSync(b))) {
+        const there = await detectVersion(bin);
+        if (!there.available) continue;
+        BIN = bin;
+        found = there;
+        break;
+      }
+    }
     if (!found.available) return found;
     // `opencode models --verbose` prints each provider/model id followed by its JSON metadata;
     // the metadata's `variants` are the reasoning efforts `run --variant` accepts for that model.
@@ -38,9 +65,11 @@ export default {
     return { ...found, models: [this.models[0], ...models] };
   },
 
-  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, delegating = false, onEvent }) {
+  // grants: { permission, patterns } the user allowed after `run` rejected them, for this turn.
+  run({ prompt, attachments = [], cwd, resumeId, mode, model, effort, systemPrompt, mcpServers = {}, delegating = false, grants = [], onEvent }) {
     // The prompt goes on stdin; `run` appends piped stdin to the (empty) message.
-    const args = ['run', '--format', 'json'];
+    // Errors to stderr: the only place a rate limit shows up (see RATE_LIMITED).
+    const args = ['run', '--format', 'json', '--print-logs', '--log-level', 'ERROR'];
     if (mode === 'plan') args.push('--agent', 'plan');
     if (mode === 'auto') args.push('--auto');
     if (model) args.push('--model', model);
@@ -54,14 +83,20 @@ export default {
       mcp[name] = { type: 'local', command: [srv.command, ...(srv.args || [])], environment: srv.env || {}, enabled: true, timeout: ASK_TIMEOUT_MS };
     }
     const env = { ...process.env };
-    if (Object.keys(mcp).length) {
+    const allow = grants.filter((g) => g && typeof g.permission === 'string' && Array.isArray(g.patterns));
+    if (Object.keys(mcp).length || allow.length) {
       const inline = env.OPENCODE_CONFIG_CONTENT ? safeJson(env.OPENCODE_CONFIG_CONTENT) : {};
+      const permission = typeof inline.permission === 'object' ? { ...inline.permission } : inline.permission ? { '*': inline.permission } : {};
+      // Its built-in `task` subagents would bypass the user's team.
+      if (delegating) permission.task = 'deny';
+      for (const g of allow) {
+        const was = permission[g.permission];
+        permission[g.permission] = { ...(typeof was === 'object' ? was : was && { '*': was }), ...Object.fromEntries(g.patterns.map((p) => [String(p), 'allow'])) };
+      }
       env.OPENCODE_CONFIG_CONTENT = JSON.stringify({
         ...inline,
-        mcp: { ...inline.mcp, ...mcp },
-        experimental: { ...inline.experimental, mcp_timeout: ASK_TIMEOUT_MS },
-        // Its built-in `task` subagents would bypass the user's team.
-        ...(delegating && { permission: { ...(typeof inline.permission === 'object' ? inline.permission : inline.permission && { '*': inline.permission }), task: 'deny' } }),
+        ...(Object.keys(mcp).length && { mcp: { ...inline.mcp, ...mcp }, experimental: { ...inline.experimental, mcp_timeout: ASK_TIMEOUT_MS } }),
+        ...(Object.keys(permission).length && { permission }),
       });
     }
 
@@ -75,14 +110,30 @@ export default {
     const tokens = { input: 0, output: 0 };
     let cost = 0;
 
-    return spawnJsonl({
+    let limitTimer = null;
+    let limited = false;
+    let carry = ''; // a stderr line still being written
+    const proc = spawnJsonl({
       bin: BIN,
       args,
       cwd,
       env,
       input,
       onEvent,
+      onStderr(chunk) {
+        // Whole lines only: a chunk can end mid-line.
+        const lines = (carry + chunk).split('\n');
+        carry = lines.pop();
+        for (const [, permission, list] of lines.join('\n').replace(ANSI, '').matchAll(REJECTED)) {
+          const patterns = list.split(', ').filter(Boolean);
+          onEvent({ type: 'blocked', tool: permission, detail: patterns.join(', '), rule: { permission, patterns } });
+        }
+        if (limitTimer || limited || !RATE_LIMITED.test(chunk)) return;
+        limitTimer = setTimeout(() => ((limited = true), proc.stop()), rateLimitGrace());
+      },
       onJson(msg) {
+        // Anything coming through means a retry got an answer.
+        if (limitTimer && msg.type !== 'error') (clearTimeout(limitTimer), (limitTimer = null));
         if (msg.sessionID && msg.sessionID !== session) onEvent({ type: 'session', id: (session = msg.sessionID) });
         const part = msg.part || {};
         switch (msg.type) {
@@ -118,19 +169,28 @@ export default {
         }
       },
       onClose({ code, signal, stderr, stopped }) {
+        clearTimeout(limitTimer);
+        if (limited) {
+          const which = model ? `\`${model}\`` : 'opencode’s default model';
+          return onEvent({ type: 'result', isError: true, text: `${which} is rate-limited right now: opencode kept retrying for ${Math.round(rateLimitGrace() / 1000)}s without an answer. Try again in a few minutes, pick another model, or connect your own provider with \`opencode auth login\`.`, stats: { durationMs: Date.now() - started } });
+        }
         const ok = code === 0 && !error;
         onEvent({
           type: 'result',
           isError: !ok,
           stopped,
-          text: ok ? text.join('\n') : error || stderr || `opencode exited with ${signal || `code ${code}`}`,
+          text: ok ? text.join('\n') : error || lastLoggedError(stderr) || exitText('opencode', code, signal),
           stats: { durationMs: Date.now() - started, costUsd: cost || undefined, inputTokens: tokens.input, outputTokens: tokens.output },
         });
       },
     });
+    return proc;
   },
 };
 
+// stderr with --print-logs: the last logged error's message, else stderr as it is.
+const lastLoggedError = (stderr) => [...stderr.matchAll(/error\.error="((?:[^"\\]|\\.)*)"/g)].at(-1)?.[1] || stderr;
+
 function safeJson(s) {
   try {
     return JSON.parse(s) || {};
@@ -175,6 +235,12 @@ function describeTool(name, input, cwd) {
       return { kind: 'agent', label: `Delegated to ${clip([...new Set((input.tasks || []).map((t) => t.subagent))].join(', ') || 'subagents', 60)}` };
     case 'wisp_subagent_results':
       return { kind: 'agent', label: 'Collected subagent reports' };
+    case 'wisp_wisp_stats':
+      return { kind: 'tool', label: 'Reading wisp stats' };
+    case 'wisp_wisp_sessions':
+      return { kind: 'tool', label: 'Listing wisp tasks' };
+    case 'wisp_wisp_session':
+      return { kind: 'tool', label: `Reading wisp task ${clip(input?.id || '', 40)}` };
     default:
       return { kind: 'tool', label: `Using ${name.replace(/_/g, ' ')}` };
   }

package/server/checkpoint.js

@@ -1,22 +1,13 @@
-// Per-turn git checkpoints, single-file revert, turn rollback, and action command execution.
+// Per-turn git checkpoints, single-file revert and turn rollback.
 
-import { execFileSync, spawn as nodeSpawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { killTree } from './proc.js';
-import { MAX_SNAPSHOT, rel } from './adapters/common.js';
+import { gitSync } from './git.js';
+import { MAX_SNAPSHOT, rel } from './paths.js';
+import { bad } from './util.js';
 
-const MAX_EXEC_OUTPUT = 32 * 1024;
-const EXEC_TIMEOUT_MS = 60_000;
 
-function git(cwd, args, opts = {}) {
-  return execFileSync('git', args, {
-    cwd,
-    stdio: ['ignore', 'pipe', 'ignore'],
-    timeout: 5000,
-    ...opts,
-  });
-}
+const git = gitSync;
 
 function tryGit(cwd, args, opts) {
   try {
@@ -100,12 +91,12 @@ function writeDiskSnapshot(abs, content) {
 
 function resolveInsideCwd(cwd, file) {
   if (!file || typeof file !== 'string') {
-    throw Object.assign(new Error('file path required'), { status: 400 });
+    throw bad('file path required');
   }
   const abs = path.resolve(cwd, file);
   const relPath = path.relative(cwd, abs);
   if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) {
-    throw Object.assign(new Error(`File lies outside the project folder: ${file}`), { status: 400 });
+    throw bad(`File lies outside the project folder: ${file}`);
   }
   return { abs, relPath: rel(file, cwd) || relPath };
 }
@@ -128,7 +119,7 @@ export function revertFileChange(session, turn, file, { restore = false } = {})
   const entry = findChangeEntry(turn, file, cwd);
   const commit = turn.checkpoint?.commit;
   if (!entry && !commit) {
-    throw Object.assign(new Error(`No captured changes or checkpoint for ${relPath}`), { status: 404 });
+    throw bad(`No captured changes or checkpoint for ${relPath}`, 404);
   }
 
   if (restore) {
@@ -145,7 +136,7 @@ export function revertFileChange(session, turn, file, { restore = false } = {})
         writeDiskSnapshot(abs, cur);
       }
     } else {
-      throw Object.assign(new Error(`Nothing to re-apply for ${relPath}`), { status: 400 });
+      throw bad(`Nothing to re-apply for ${relPath}`);
     }
     if (entry) entry.reverted = false;
     if (turn.changes?.every((c) => !c.reverted)) delete turn.rolledBackAt;
@@ -200,7 +191,7 @@ function reverseEditsOnDisk(abs, entry) {
 export function rollbackToTurn(session, turn, { restore = false } = {}) {
   const cwd = sessionDir(session);
   const idx = session.turns.indexOf(turn);
-  if (idx < 0) throw Object.assign(new Error('No such turn'), { status: 404 });
+  if (idx < 0) throw bad('No such turn', 404);
   const affected = session.turns.slice(idx);
   const touchedFiles = [...new Set(affected.flatMap((t) => (t.changes || []).map((c) => c.file)))];
 
@@ -297,52 +288,5 @@ export function rollbackToTurn(session, turn, { restore = false } = {}) {
   return { files: touchedFiles, rolledBack: true, commit: cp?.head || cp?.commit || null };
 }
 
-// Run a shell command from an actionable presentation block inside `cwd`.
-export function execCommand(cwd, command, { timeoutMs = EXEC_TIMEOUT_MS } = {}) {
-  const cmd = String(command || '').trim();
-  if (!cmd) return Promise.reject(Object.assign(new Error('command required'), { status: 400 }));
-  const t0 = Date.now();
-
-  return new Promise((resolve) => {
-    const child = nodeSpawn(cmd, {
-      cwd,
-      env: { ...process.env, PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', CI: '1' },
-      shell: true,
-      windowsHide: true,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let out = '';
-    const append = (chunk) => {
-      if (out.length < MAX_EXEC_OUTPUT) out += chunk.toString('utf8').slice(0, MAX_EXEC_OUTPUT - out.length);
-    };
-    child.stdout.on('data', append);
-    child.stderr.on('data', append);
-
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      killTree(child);
-    }, timeoutMs);
-
-    child.on('error', (err) => {
-      clearTimeout(timer);
-      resolve({
-        command: cmd,
-        output: (out ? `${out}\n` : '') + err.message,
-        exitCode: 1,
-        durationMs: Date.now() - t0,
-      });
-    });
-
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      const suffix = timedOut ? `\n[timed out after ${Math.round(timeoutMs / 1000)}s]` : '';
-      resolve({
-        command: cmd,
-        output: (out.replace(/\s+$/, '') + suffix).trim(),
-        exitCode: timedOut ? 124 : (code ?? 1),
-        durationMs: Date.now() - t0,
-      });
-    });
-  });
-}
+// Moved to proc.js; kept here for anything that still imports it from checkpoint.
+export { execCommand } from './proc.js';

package/server/client.js

@@ -13,8 +13,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { DEFAULT_PORT } from './util.js';
 
-export const DEFAULT_PORT = 4477;
+export { DEFAULT_PORT };
 const BIN = fileURLToPath(new URL('../bin/wisp.js', import.meta.url));
 const MAX_WAIT_CALL = 280; // seconds per long-poll; fetch gives up on headers after 300s
 
@@ -135,7 +136,7 @@ export class WispClient {
     if (!agent || !mode || model === undefined) {
       const { defaults = {} } = await this.config();
       agent ||= defaults.agent || 'auto';
-      mode ||= defaults.mode || 'edits';
+      mode ||= defaults.mode || 'auto';
       model ??= defaults.models?.[agent] ?? (agent === defaults.agent ? defaults.model || '' : '');
     }
     return this.request('POST', '/sessions', { prompt, cwd: path.resolve(cwd), agent, mode, model, effort, attachments, worktree, compare, subagents, preset });
@@ -154,8 +155,9 @@ export class WispClient {
   usage = ({ days } = {}) => this.request('GET', `/usage${days ? `?days=${days}` : ''}`);
 
   // A follow-up. If the agent is blocked on ask_user, this answers it. queue: wait for the
-  // current run instead of interrupting it (default: the user's setting).
-  reply = (id, text, { attachments, queue, mode } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue, mode });
+  // current run instead of interrupting it (default: the user's setting). agent / model / effort:
+  // run it, and the follow-ups after it, on another harness, model or thinking level.
+  reply = (id, text, { attachments, queue, mode, agent, model, effort } = {}) => this.request('POST', `/sessions/${id}/reply`, { text, attachments, queue, mode, agent, model, effort });
 
   // Upload a file (path, Buffer or Uint8Array) to attach to a launch or reply. Returns { id, … }.
   async upload(file, { name, type } = {}) {

package/server/git.js

@@ -3,7 +3,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { execFile } from './proc.js';
+import { bad } from './util.js';
 
 const GIT = () => process.env.WISP_GIT_BIN || 'git';
 const GH = () => process.env.WISP_GH_BIN || 'gh';
@@ -22,6 +24,9 @@ export function run(bin, args, { cwd, timeout = 60_000 } = {}) {
   });
 }
 export const git = (cwd, args, opts) => run(GIT(), args, { cwd, ...opts });
+// Synchronous, for the few places that must not yield (checkpoints taken right before a turn
+// starts, file snapshots while a harness streams). Returns a Buffer; throws on failure.
+export const gitSync = (cwd, args, opts = {}) => execFileSync(GIT(), args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, env: { ...process.env, ...QUIET_ENV }, ...opts });
 export const gh = (cwd, args, opts) => run(GH(), args, { cwd, timeout: 120_000, ...opts });
 const quiet = (p) => p.catch(() => '');
 
@@ -161,13 +166,13 @@ export async function ship(wt, { title, body = '', draft = false, pr }) {
   await ensureWorktree(wt);
   const dir = wt.path;
   if (await quiet(git(dir, ['status', '--porcelain']))) {
-    if (!String(title || '').trim()) throw Object.assign(new Error('A commit message is required.'), { status: 400 });
+    if (!String(title || '').trim()) throw bad('A commit message is required.');
     await git(dir, ['add', '-A']);
     await git(dir, ['commit', '--quiet', '--no-verify', '-m', title.trim(), ...(body.trim() ? ['-m', body.trim()] : [])]);
   }
   const { ahead } = await worktreeStatus(wt);
-  if (!ahead) throw Object.assign(new Error('Nothing to ship: this branch has no changes.'), { status: 400 });
-  if (!wt.remote) throw Object.assign(new Error('This repo has no origin remote to push to.'), { status: 400 });
+  if (!ahead) throw bad('Nothing to ship: this branch has no changes.');
+  if (!wt.remote) throw bad('This repo has no origin remote to push to.');
   await git(dir, ['push', '--quiet', '-u', wt.remote, `HEAD:refs/heads/${wt.branch}`], { timeout: 120_000 });
   if (pr?.state === 'OPEN') return prView(dir, pr.number);
   const url = (await gh(dir, ['pr', 'create', '--base', wt.base, '--head', wt.branch, '--title', title.trim(), '--body', body.trim() || ' ', ...(draft ? ['--draft'] : [])])).split('\n').pop();
@@ -178,7 +183,7 @@ export async function ship(wt, { title, body = '', draft = false, pr }) {
 export async function merge(wt, number) {
   const dir = fs.existsSync(wt.path) ? wt.path : wt.root;
   let pr = await prView(dir, number);
-  if (pr.state !== 'OPEN') throw Object.assign(new Error(`PR #${number} is ${pr.state.toLowerCase()}.`), { status: 400 });
+  if (pr.state !== 'OPEN') throw bad(`PR #${number} is ${pr.state.toLowerCase()}.`);
   if (pr.draft) await gh(dir, ['pr', 'ready', String(number)]);
   await gh(dir, ['pr', 'merge', String(number), '--squash', '--match-head-commit', pr.head]);
   pr = await prView(dir, number);

package/server/handoff.js

@@ -0,0 +1,71 @@
+// Switching harness in a follow-up. Each harness keeps its own conversation (native session id),
+// so a harness picked up mid-task hasn't seen the turns that ran elsewhere. handoffNote() writes
+// those turns out (requests, reports, files touched) and goes ahead of the follow-up's prompt.
+// A harness that ran earlier in the task resumes its own session and only hears what it missed.
+
+import { textMentions } from './mentions.js';
+import { blocksToMarkdown } from './render.js';
+import { clip, truncate } from './util.js';
+
+const BUDGET = 24_000; // characters of earlier turns, newest kept first
+const PER_TURN = 6_000;
+// The parts of a report worth passing on. Diffs, code and terminal output are on disk or in git.
+const KEEP = new Set(['hero', 'markdown', 'steps', 'stats', 'files', 'tests', 'commits', 'checklist', 'callout', 'question', 'next']);
+
+// The turns before the current one that `agent` hasn't seen: everything after the last turn it
+// ran, or all of them when it has no conversation of its own to resume (resumeId). Only a gap
+// that another harness filled counts: on its own, a harness has nothing to catch up on.
+export function missedTurns(session, agent, resumeId) {
+  const prior = session.turns.slice(0, -1);
+  const missed = resumeId ? prior.slice(prior.findLastIndex((t) => (t.agent || agent) === agent) + 1) : prior;
+  return missed.some((t) => (t.agent || agent) !== agent) ? missed : [];
+}
+
+function turnText(t, n, name) {
+  const blocks = (t.presentation?.blocks || []).filter((b) => KEEP.has(b?.type));
+  const report = t.status === 'running' ? '' : blocksToMarkdown(blocks, t) || clip(t.raw, 1500);
+  const files = (t.changes || []).filter((c) => !c.reverted).map((c) => `\`${c.file}\``);
+  return truncate(
+    [
+      `### Turn ${n} · ${name(t)}${t.model ? ` (${t.model})` : ''}${t.status === 'stopped' ? ' · stopped' : t.status === 'error' ? ' · failed' : ''}${t.rolledBackAt ? ' · rolled back, its edits were undone' : ''}`,
+      `**User:** ${textMentions(t.prompt)}`,
+      report && `**Report:**\n\n${report}`,
+      files.length && `**Files it edited:** ${files.join(', ')}`,
+    ]
+      .filter(Boolean)
+      .join('\n\n'),
+    PER_TURN,
+  );
+}
+
+// The note for `agent` taking the next turn, or '' when it has seen everything.
+// name(turn) → the harness's display name for that turn.
+export function handoffNote(session, agent, resumeId, name) {
+  const missed = missedTurns(session, agent, resumeId);
+  if (!missed.length) return '';
+  const all = session.turns.slice(0, -1);
+  const parts = [];
+  let used = 0;
+  for (let i = missed.length - 1; i >= 0; i--) {
+    const text = turnText(missed[i], all.indexOf(missed[i]) + 1, name);
+    if (used + text.length > BUDGET && parts.length) break;
+    parts.unshift(text);
+    used += text.length;
+  }
+  const dropped = missed.length - parts.length;
+  const fresh = !resumeId;
+  const others = [...new Set(missed.filter((t) => t.agent !== agent).map(name))].join(', ');
+  const intro = fresh
+    ? `You are taking over a task that another coding agent (${others}) has been working on. Its work is already in this folder. Below is what happened so far, oldest first; read the files and \`git diff\` for the details, then carry on with the follow-up.`
+    : `While you were away, this task continued on another coding agent (${others}). Its work is already in this folder. Below is what happened since your last turn, oldest first; check the files and \`git diff\` before you rely on what you remember.`;
+  return [
+    '## Earlier in this task',
+    intro,
+    dropped ? `_${dropped} earlier turn${dropped > 1 ? 's' : ''} left out for length._` : '',
+    ...parts,
+    '---',
+    '## Follow-up',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}

package/server/http/respond.js

@@ -0,0 +1,59 @@
+// Writing responses and reading request bodies. The API speaks JSON; a few routes stream.
+
+const MAX_BODY = 2e6;
+
+export function send(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+export function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    let tooLarge = false;
+    req.on('data', (c) => {
+      if (tooLarge) return;
+      data += c;
+      if (data.length > MAX_BODY) {
+        // Stop buffering: the rest of the body is dropped, not held in memory.
+        tooLarge = true;
+        data = '';
+        reject(Object.assign(new Error('body too large'), { status: 413 }));
+      }
+    });
+    req.on('end', () => {
+      if (tooLarge) return;
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        reject(Object.assign(new Error('invalid json'), { status: 400 }));
+      }
+    });
+  });
+}
+
+// Pass a machine's raw response (images, markdown, uploads) straight through.
+export function pipeFrom(res, r) {
+  const headers = { 'content-type': r.headers['content-type'] || 'application/octet-stream' };
+  if (r.headers['content-length']) headers['content-length'] = r.headers['content-length'];
+  res.writeHead(r.statusCode, headers);
+  r.pipe(res);
+}
+
+// Server-sent events: every open /api/events stream gets every broadcast.
+export function eventStream() {
+  const clients = new Set();
+  return {
+    clients,
+    attach(req, res) {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      res.write(`event: hello\ndata: {}\n\n`);
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+    },
+    broadcast(event, data) {
+      const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+      for (const res of clients) res.write(frame);
+    },
+  };
+}