jaitus 0.3.0

package/src/agent/loop.js

@@ -0,0 +1,548 @@
+// ─── The agent loop ─────────────────────────────────────────────────────────────
+//
+// Send the conversation to Jaitus, stream the reply, run any tools it asked for, append
+// the results, and go again — until it stops asking for tools. That is the whole idea;
+// everything else here is making it behave under real conditions.
+//
+// Notes on the parts that are easy to get wrong:
+//
+//   • Streaming is parsed as server-sent events. Tool arguments arrive as `input_json_delta`
+//     fragments that only become valid JSON once concatenated, so they are buffered per
+//     content block and parsed at the end, never incrementally.
+//   • The assistant turn is appended EXACTLY as the model produced it, tool_use blocks
+//     included. Paraphrasing it breaks the pairing with tool_result and the next turn
+//     is rejected.
+//   • Every tool_use must get a tool_result, including ones that failed or were refused.
+//     A missing result is a malformed conversation, and the error text is also how the
+//     model learns to try something else.
+//   • A hard iteration cap. A model that gets stuck in a read-file loop would otherwise
+//     spend real money until someone notices.
+
+import { byName, toolSchemas, ToolError, readImageForModel } from './tools.js';
+import { PermissionDenied } from './permissions.js';
+import path from 'node:path';
+import { loadContext, CONTEXT_FILE } from '../project.js';
+import { c, out, write, spinner, glyph } from '../ui.js';
+import { discoverMcpTools } from '../mcp.js';
+import { unifiedDiff } from '../diff.js';
+import { fromResponse, fromGatewayBody } from '../errors.js';
+
+const MAX_ITERATIONS = 40;
+
+/** opencode tool icon per tool, muted when done. ASCII twins included. */
+const TOOL_MARKS = {
+  run_command: ['$', '$'], read_file: ['→', '>'], read_image: ['→', '>'],
+  list_files: ['→', '>'], write_file: ['←', '<'], edit_file: ['←', '<'],
+  search: ['✱', '*'], web_fetch: ['%', '%'], web_search: ['◈', 'o'],
+  background_run: ['◉', 'o'], todo_write: ['⚙', '*'],
+};
+const toolMark = (name) => {
+  const [uni, ascii] = TOOL_MARKS[name] || ['⚙', '*'];
+  return c.dim(glyph(uni, ascii));
+};
+
+export const SYSTEM_PROMPT = `You are Jaitus, a coding agent running in a developer's terminal, inside their project directory.
+
+How to work:
+- Investigate before you change anything. Read the files you are about to edit; do not guess at their contents.
+- Prefer edit_file over write_file for existing files. Keep changes minimal and in the style of the surrounding code.
+- Run the project's own tests or build after a change when one exists, and report the real result — including when it fails.
+- Use run_command for anything the shell does better: git, tests, package managers, linters.
+- Never invent a file path, a function name, or a test result. If you are unsure, look.
+- For current news or other web facts, report only details grounded in web_search or
+  web_fetch output. Include the supplied source URLs; never fill a missing headline or
+  date from memory.
+
+How to talk:
+- Be concise. This is a terminal, not a document.
+- Say what you did and what happened, not what you are about to do.
+- If something is blocked or you are missing information, say so plainly and ask.
+- No preamble, no restating the question back.`;
+
+/**
+ * The project's own briefing, appended to the system prompt.
+ *
+ * Fenced and labelled rather than concatenated, so instructions written by whoever owns
+ * the repo are visibly the repo's and cannot be mistaken for part of Jaitus's own rules.
+ */
+export function systemPrompt(cwd) {
+  const project = cwd ? loadContext(cwd) : null;
+  if (!project) return SYSTEM_PROMPT;
+  return `${SYSTEM_PROMPT}
+
+The project you are working in ships a ${CONTEXT_FILE} with notes for you. Follow it where
+it applies, and prefer what it says over your own assumptions about this codebase.
+
+<${CONTEXT_FILE}>
+${project}
+</${CONTEXT_FILE}>`;
+}
+
+/** One streamed request. Returns { content, stopReason, usage }. */
+async function streamTurn({ client, messages, model, system, tools, onText, onToolStart, signal }) {
+  const res = await client.messages({
+    model,
+    max_tokens: 8192,
+    system: system || SYSTEM_PROMPT,
+    tools,
+    messages,
+    stream: true,
+  }, { signal });
+
+  if (!res.ok) throw await fromResponse(res);
+  const requestId = res.headers?.get?.('x-request-id') || '';
+
+  // Blocks are keyed by the index the stream gives them, because they interleave.
+  const blocks = new Map();
+  let stopReason = null;
+  const usage = { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 };
+  // Usage can arrive at the START of a stream (Anthropic-format providers) or only at
+  // the END, in message_delta (OpenAI-format providers, translated by the gateway —
+  // their usage exists only once generation finishes). Reading input from message_start
+  // alone recorded every OpenAI-format turn as 0 input tokens.
+  const takeUsage = (u) => {
+    if (!u) return;
+    for (const k of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
+      if (u[k] != null && Number.isFinite(Number(u[k]))) usage[k] = Number(u[k]);
+    }
+  };
+  let buffer = '';
+  // A failure reported INSIDE the stream, after a 200. Recorded here and thrown after
+  // the parse below: handle() runs inside a try whose catch exists to skip keepalives,
+  // so throwing from it would be swallowed — which is how a mid-stream error used to
+  // end an answer halfway with no explanation at all.
+  let streamError = null;
+
+  const handle = (event) => {
+    switch (event.type) {
+      case 'error':
+        streamError = fromGatewayBody(200, event, { requestId });
+        break;
+      case 'message_start':
+        takeUsage(event.message?.usage);
+        break;
+      case 'content_block_start': {
+        const b = event.content_block || {};
+        blocks.set(event.index, b.type === 'tool_use'
+          ? { type: 'tool_use', id: b.id, name: b.name, json: '' }
+          : { type: 'text', text: '' });
+        if (b.type === 'tool_use') onToolStart?.(b.name);
+        break;
+      }
+      case 'content_block_delta': {
+        const b = blocks.get(event.index);
+        if (!b) break;
+        const d = event.delta || {};
+        if (d.type === 'text_delta' && typeof d.text === 'string') {
+          b.text += d.text;
+          onText?.(d.text);
+        } else if (d.type === 'input_json_delta' && typeof d.partial_json === 'string') {
+          b.json += d.partial_json;
+        }
+        break;
+      }
+      case 'message_delta':
+        if (event.delta?.stop_reason) stopReason = event.delta.stop_reason;
+        takeUsage(event.usage);
+        break;
+      default:
+        break;
+    }
+  };
+
+  // fetch() yields Uint8Array, NOT a Node Buffer. `uint8.toString('utf8')` ignores the
+  // argument and returns "101,118,101,…" — comma-joined byte values — so the whole
+  // stream parses to nothing and the agent appears to answer with silence.
+  //
+  // TextDecoder with stream:true is also the only correct choice for a different reason:
+  // a multi-byte character can be split across two chunks, and decoding each chunk
+  // independently would corrupt it. The decoder holds the partial bytes until complete.
+  const decoder = new TextDecoder();
+
+  for await (const chunk of res.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const frames = buffer.split('\n\n');
+    buffer = frames.pop() || '';
+    for (const frame of frames) {
+      for (const line of frame.split('\n')) {
+        if (!line.startsWith('data:')) continue;
+        const raw = line.slice(5).trim();
+        if (!raw || raw === '[DONE]') continue;
+        try { handle(JSON.parse(raw)); } catch { /* keepalive or partial */ }
+      }
+    }
+    if (streamError) break;
+  }
+  if (streamError) throw streamError;
+
+  const content = [...blocks.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([, b]) => {
+      if (b.type !== 'tool_use') return { type: 'text', text: b.text };
+      let input = {};
+      // The fragments only form valid JSON once joined. An empty string is a
+      // no-argument call, which is legitimate.
+      try { input = b.json.trim() ? JSON.parse(b.json) : {}; } catch { input = { __parse_error: b.json }; }
+      return { type: 'tool_use', id: b.id, name: b.name, input };
+    })
+    .filter((b) => b.type !== 'text' || b.text.length);
+
+  return { content, stopReason, usage };
+}
+
+/**
+ * Run one user request to completion.
+ * `messages` is mutated so the caller keeps the conversation across turns.
+ */
+export async function runAgent({
+  client, messages, model, cwd, permissions, signal, tui = null,
+  extraSystem = '', maxIterations = MAX_ITERATIONS, silent = false,
+  onText = null, onEvent = null, systemOverride = null, journal = null,
+  subagents = true,
+}) {
+  // input = fresh input, cached = prompt-cache reads (billed far cheaper), and
+  // context = the real size of the last prompt sent, as the provider counted it.
+  const totals = { input: 0, cached: 0, output: 0, tools: 0, context: 0 };
+  // Read once per request, not per turn: an agent that rewrites JAITUS.md mid-task
+  // should not change the rules it is being judged by halfway through.
+  const system = `${systemOverride || systemPrompt(cwd)}${extraSystem}`;
+  const mcp = await discoverMcpTools(cwd).catch(() => []);
+  // Subagents are offered only to the top-level agent. A subagent that can spawn
+  // subagents is an unbounded fan-out on a metered gateway, and the depth that would
+  // actually help — one — is the depth that is safe.
+  const subagent = subagents ? makeSubagentTool({ client, model, cwd, signal, tui }) : null;
+  const availableTools = [
+    ...toolSchemas(),
+    ...(subagent ? [{ name: subagent.name, description: subagent.description, input_schema: subagent.input_schema }] : []),
+    ...mcp.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema })),
+  ];
+  const toolMap = {
+    ...byName,
+    ...(subagent ? { [subagent.name]: subagent } : {}),
+    ...Object.fromEntries(mcp.map((tool) => [tool.name, tool])),
+  };
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    let streamed = false;
+    const spin = tui ? { stop: () => {}, update: () => {} } : (silent ? { stop: () => {}, update: () => {} } : spinner(glyph('Working…', 'Working...')));
+    if (tui) tui.setStatus(`${c.brand(glyph('•', '*'))} ${c.brand(glyph('Working…', 'Working...'))}`);
+    // Codex-style assistant cell: the • leads the turn the way › leads the
+    // user's. In scrollback the marker lands before the first streamed chunk.
+    let turnVoiced = false;
+
+    let turn;
+    try {
+      turn = await streamTurn({
+        client,
+        messages,
+        model,
+        system,
+        tools: availableTools,
+        signal,
+        onText: (text) => {
+          onText?.(text);
+          if (!streamed) {
+            spin.stop(); streamed = true;
+            if (tui) tui.clearStatus();
+            else if (!silent && !onText) { out(''); write(`${c.dim(glyph('•', '*'))} `); }
+          }
+          if (tui) {
+            // The transcript entry draws its own speaker mark now, so the loop no
+            // longer prepends one — two marks on the same line was the tell that the
+            // renderer and the loop each thought they owned the lead glyph.
+            turnVoiced = true;
+            tui.printStream(text);
+          } else if (!silent && !onText) write(text);
+        },
+        onToolStart: () => spin.update(glyph('Working…', 'Working...')),
+      });
+    } catch (e) {
+      spin.stop();
+      // Esc during streaming: stop mid-sentence, keep what landed, don't treat it
+      // as an error. The partial text is already on screen.
+      if (signal?.aborted || e?.name === 'AbortError') {
+        if (tui) tui.flushStream();
+        if (streamed && !silent) out('');
+        if (tui?.notice) tui.notice('Interrupted.', 'warn');
+        else if (tui) tui.print(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+        else if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+        return { ...totals, stopReason: 'interrupted' };
+      }
+      throw e;
+    }
+    spin.stop();
+    if (tui) tui.flushStream();
+    if (streamed) { if (tui) tui.printStream('\n'); else if (!silent && !onText) out(''); }
+
+    totals.input += turn.usage.input_tokens || 0;
+    totals.cached += (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
+    totals.output += turn.usage.output_tokens || 0;
+    const promptSize = (turn.usage.input_tokens || 0) + (turn.usage.cache_read_input_tokens || 0) + (turn.usage.cache_creation_input_tokens || 0);
+    if (promptSize) totals.context = promptSize + (turn.usage.output_tokens || 0);
+    // The work bar's live count. It was declared and drawn but never fed, so it never
+    // appeared; now it moves after every step of the turn.
+    tui?.setTurnTokens?.(totals.input + totals.cached + totals.output);
+
+    // Append the assistant turn verbatim — tool_use blocks and all.
+    messages.push({ role: 'assistant', content: turn.content });
+    onEvent?.({ type: 'assistant_turn', content: turn.content, usage: turn.usage, iteration });
+
+    const calls = turn.content.filter((b) => b.type === 'tool_use');
+
+    // Plan mode: read-only by decree. The turn's text still lands (the model can think
+    // out loud), but nothing on disk or in a shell is allowed to happen.
+    const blockedInPlan = permissions.mode === 'plan' && calls.some((call) => toolMap[call.name]?.needsPermission);
+    if (blockedInPlan) {
+      messages.pop();
+      const note = c.yellow(`  ${glyph('⏸', '[II]')}  plan mode — writes and commands are blocked; read-only inspection can continue. Shift+Tab to a doing mode to act.`);
+      if (tui?.notice) tui.notice('plan mode — writes and commands are blocked; read-only inspection can continue. Shift+Tab to a doing mode to act.', 'warn');
+      else if (tui) tui.print(note);
+      else if (!silent) out(note);
+      return { ...totals, stopReason: 'plan_blocked' };
+    }
+
+    // Esc pressed while the model was mid-turn: stop before any more tools run.
+    if (signal?.aborted) {
+      if (!silent) out(c.yellow(`  ${glyph('⏹', '[x]')}  Interrupted.`));
+      return { ...totals, stopReason: 'interrupted' };
+    }
+
+    if (!calls.length) { tui?.bellIfAway?.(); return { ...totals, stopReason: turn.stopReason }; }
+
+    // Every call gets a result, whatever happened.
+    const results = [];
+    for (const call of calls) {
+      const tool = toolMap[call.name];
+      totals.tools += 1;
+
+      if (!tool) {
+        results.push(result(call.id, `No such tool: ${call.name}`, true));
+        continue;
+      }
+      if (call.input?.__parse_error !== undefined) {
+        results.push(result(call.id, 'Your tool arguments were not valid JSON. Send them again.', true));
+        continue;
+      }
+
+      const label = tool.summarise ? tool.summarise(call.input) : call.name;
+      const activityId = tui?.recordActivity?.({ name: call.name, label, status: 'waiting' });
+      // One row per call, mutated in place through waiting → running → ok/failed. The
+      // previous surface printed a fresh line per state change, so a session with
+      // twenty tool calls scrolled sixty lines of near-duplicates past the answer.
+      const row = tui?.tool?.({ name: call.name, label, status: 'waiting', file: call.input?.path });
+
+      try {
+        await permissions.request(tool, call.input, { cwd, tui });
+      } catch (e) {
+        if (e instanceof PermissionDenied) {
+          const declined = `  ${c.red(glyph('✗', 'x'))} ${c.dim('declined')}`;
+          if (row) row.update({ status: 'denied', error: e.comment ? `declined — "${e.comment}"` : 'declined' });
+          else if (tui) tui.print(declined);
+          else if (!silent) out(declined);
+          tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: 'Permission declined by user.' });
+          // Told to the model, not just the user: it needs to know to stop trying and
+          // propose something else instead. A decision comment rides along verbatim.
+          const note = e.comment
+            ? `The user declined this action with this instruction, which overrides your plan: "${e.comment}". Do not retry the declined action; follow the instruction instead.`
+            : `The user declined this action. Do not retry it; ask what they would prefer.`;
+          results.push(result(call.id, note, true));
+          continue;
+        }
+        throw e;
+      }
+
+      tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'running' });
+      row?.update({ status: 'running' });
+      const spin2 = tui ? { stop: () => {} } : (silent ? { stop: () => {} } : spinner(`${call.name}: ${label}`.slice(0, 100)));
+      const toolStarted = Date.now();
+      // Live elapsed ticker on the status row while a tool runs (1s cadence,
+      // silent when animations are off — progress you can watch, not noise).
+      let elapsedTimer = null;
+      const stopElapsed = () => { if (elapsedTimer) { clearInterval(elapsedTimer); elapsedTimer = null; } };
+      if (tui && tui.animationsOn?.()) {
+        const toolStatus = () => `${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 60))} ${c.dim(`· ${((Date.now() - toolStarted) / 1000).toFixed(0)}s`)}`;
+        tui.setStatus(toolStatus());
+        elapsedTimer = setInterval(() => tui.setStatus(toolStatus()), 1000);
+        if (elapsedTimer.unref) elapsedTimer.unref();
+      } else if (tui) {
+        tui.setStatus(`${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 70))}`);
+      }
+      try {
+        // Rewind safety net: before the agent overwrites or creates a file, remember
+        // what was there. write_file/edit_file take their targets from the input;
+        // run_command's target is unknowable, so its calls snapshot the whole
+        // tracked set instead (cheap: only files already touched this session).
+        if (journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
+          try { journal.snapshotFile(path.resolve(cwd, String(call.input.path))); } catch { /* path never existed */ }
+        } else if (journal && call.name === 'run_command') {
+          journal.snapshotTracked(cwd);
+        }
+        const output = await tool.run(call.input, { cwd });
+        spin2.stop(); stopElapsed();
+        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
+        // opencode tool icons: $ shell, ← edits, → reads, ✱ search,
+        // % fetch, ◈ websearch, ◉ subagents, ⚙ everything else. Done
+        // rows rest muted; failures stay red.
+        const done = `  ${toolMark(call.name)} ${c.dim(String(label).slice(0, 100))} ${c.dim(`· ${took}s`)}`;
+        if (row) {
+          tui.clearStatus();
+          row.update({ status: 'ok', took, preview: previewFor(call.name, output) });
+        } else if (tui) { tui.clearStatus(); tui.print(done, 'tool'); } else if (!silent) out(done);
+        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'ok', detail: String(output).slice(0, 2000) });
+        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: true, output });
+        results.push(result(call.id, output, false));
+        // read_image: the pixels ride along as an image block in the tool-result
+        // message, so the model actually sees the picture instead of a caption of it.
+        if (call.name === 'read_image' && !silent) {
+          const block = await readImageForModel(cwd, call.input?.path).catch(() => null);
+          if (block) results[results.length - 1] = { ...result(call.id, output, false), __images: [block] };
+        }
+        // todo_write: the checklist is for the human — checkbox cells with progress.
+        if (call.name === 'todo_write' && Array.isArray(call.input?.todos)) {
+          if (tui?.todo) tui.todo(call.input.todos);
+          else if (!silent) {
+            const icon = { pending: c.dim(glyph('☐', '[ ]')), in_progress: c.accent(glyph('◐', '[>]')), completed: c.accent(glyph('☑', '[x]')) };
+            for (const t of call.input.todos.slice(0, 12)) {
+              out(`  ${(icon[t?.status] || icon.pending)} ${t?.status === 'completed' ? c.dim(String(t?.task || '').slice(0, 90)) : String(t?.task || '').slice(0, 90)}`);
+            }
+          }
+        }
+
+        // A write or an edit shows what it actually did. The journal snapshotted the
+        // file a few lines above, so the "before" side is already in memory — and a
+        // claim like "Edited src/index.js" is exactly the kind of thing that turns out
+        // to have changed the wrong line.
+        if (tui?.diff && journal && ['write_file', 'edit_file'].includes(call.name) && call.input?.path) {
+          try {
+            const absolute = path.resolve(cwd, String(call.input.path));
+            const before = journal.latestSnapshot(absolute);
+            if (before !== null) {
+              const { readFileSync } = await import('node:fs');
+              const patch = unifiedDiff(before, readFileSync(absolute, 'utf8'), { file: call.input.path });
+              if (patch) tui.diff(String(call.input.path), patch);
+            }
+          } catch { /* a missing diff never blocks the turn */ }
+        }
+      } catch (e) {
+        spin2.stop(); stopElapsed();
+        const msg = e instanceof ToolError ? e.message : `${e.message}`;
+        const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
+        const bad = `  ${c.red(glyph('✗', 'x'))} ${c.dim(String(label).slice(0, 80))} ${c.dim(`· ${took}s`)} — ${msg.slice(0, 120)}`;
+        if (row) {
+          tui.clearStatus();
+          row.update({ status: 'failed', took, error: msg.split('\n')[0].slice(0, 200), preview: msg.includes('\n') ? msg : '' });
+        } else if (tui) { tui.clearStatus(); tui.print(bad, 'tool'); } else if (!silent) out(bad);
+        tui?.recordActivity?.({ id: activityId, name: call.name, label, status: 'failed', detail: msg.slice(0, 2000) });
+        onEvent?.({ type: 'tool_result', name: call.name, input: call.input, ok: false, error: msg });
+        results.push(result(call.id, msg, true));
+      }
+    }
+
+    // Image blocks ride in the same user message as their tool_result, each following
+    // the result it belongs to — that is the shape the vision API expects.
+    const withImages = [];
+    for (const r of results) {
+      withImages.push(r);
+      for (const img of r.__images || []) withImages.push(img);
+      delete r.__images;
+    }
+    messages.push({ role: 'user', content: withImages });
+  }
+
+  if (!silent) out(c.yellow(`\nStopped after ${maxIterations} steps without finishing. Say "continue" to keep going.`));
+  tui?.bellIfAway?.();
+  return { ...totals, stopReason: 'max_iterations' };
+}
+
+/**
+ * A read-only subagent, as a tool the model can call.
+ *
+ * The point is context, not concurrency. "Find every place that reads the session file"
+ * costs forty tool results, and forty tool results spent in the main conversation are
+ * forty tool results the main conversation is still carrying three turns later. A
+ * subagent spends them in its own window and returns the paragraph that mattered.
+ *
+ * Read-only by construction: it is handed a permissions object in plan mode, so every
+ * write and every shell command is refused no matter what the parent's mode is. A
+ * subagent the user never sees must not be able to change the disk.
+ */
+function makeSubagentTool({ client, model, cwd, signal, tui }) {
+  return {
+    name: 'task',
+    needsPermission: false,
+    description: 'Delegate a read-only investigation to a separate agent with its own context window. '
+      + 'Use it when answering needs a lot of searching and reading whose intermediate output you do not need to keep — '
+      + '"find every caller of X", "work out how Y is wired", "check whether Z is covered by tests". '
+      + 'The subagent can read, list, search and fetch, but cannot write files or run commands. '
+      + 'Give it a self-contained brief: it cannot see this conversation. It returns its findings as text.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        description: { type: 'string', description: 'Three to five words naming the task, for the activity row.' },
+        prompt: { type: 'string', description: 'The full self-contained brief, including what to report back.' },
+      },
+      required: ['description', 'prompt'],
+    },
+    summarise: (input) => String(input.description || 'subagent'),
+    async run(input, { cwd: runCwd }) {
+      const { createPermissions } = await import('./permissions.js');
+      const messages = [{ role: 'user', content: String(input.prompt || '') }];
+      let answer = '';
+      const result = await runAgent({
+        client,
+        messages,
+        model,
+        cwd: runCwd || cwd,
+        permissions: createPermissions({ mode: 'plan' }),
+        signal,
+        tui: null,
+        silent: true,
+        subagents: false,
+        maxIterations: 20,
+        extraSystem: '\n\nYou are a subagent. You cannot ask questions and nobody will read your intermediate '
+          + 'steps — only your final message. End with the findings themselves, with exact file paths and line '
+          + 'numbers where they apply, not a description of how you looked.',
+        onText: (text) => { answer += text; },
+      });
+      const trimmed = answer.trim();
+      if (!trimmed) return `The subagent finished (${result.stopReason}) without reporting anything.`;
+      return `${trimmed}\n\n[subagent: ${result.tools} tool calls, ${result.input + result.output} tokens]`;
+    },
+  };
+}
+
+/**
+ * What of a tool's output is worth putting on screen.
+ *
+ * Not everything: a `read_file` the agent asked for is the agent's business, and
+ * echoing 400 lines of it buries the reasoning that follows. A command's output, a
+ * search's hits and a fetch's first lines are the ones a human reads over the agent's
+ * shoulder — so those get a preview and the rest get a row.
+ */
+function previewFor(name, output) {
+  const text = String(output ?? '');
+  if (!text.trim()) return '';
+  switch (name) {
+    case 'run_command':
+    case 'background_read':
+      return text;
+    case 'search':
+    case 'list_files':
+    case 'web_search':
+      return text;
+    case 'web_fetch':
+      return text.split('\n').slice(0, 8).join('\n');
+    case 'read_file':
+    case 'read_image':
+    case 'write_file':
+    case 'edit_file':
+    case 'todo_write':
+      return '';
+    default:
+      return text.length > 400 ? '' : text;
+  }
+}
+
+function result(id, content, isError) {
+  return { type: 'tool_result', tool_use_id: id, content: String(content), is_error: isError };
+}