@elbow-dev/acp 0.0.0-stage → 0.1.0

package/agent.mjs

@@ -0,0 +1,875 @@
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MAX_TOKENS = 32_768;
+const MAX_CALLS = 128;
+// What one call returns, as Claude Code's Read (2,000 lines, long lines cut) and Bash (30k characters) do: a whole
+// large file or build log in every later turn's context buries the task and slows each turn.
+const READ_LINES = 2000;
+const LINE_CHARS = 2000;
+const OUTPUT_CHARS = 30_000;
+const TREE_FILES = 200;
+const SEARCH_RESULTS = 100;
+const SEARCH_SECONDS = 30;
+// Lines of context around an edit's new text in its result, as Claude Code shows them, so the model needn't read the
+// file again to see the edit landed.
+const AROUND = 3;
+const SNIPPET_LINES = 40;
+// Calls that change nothing run together, as Claude Code runs its reads and searches.
+const READ_ONLY = new Set(['read_file', 'search']);
+const BASH_SECONDS = 120;
+const CHECK_SECONDS = 120;
+// A turn that ends with failing checks is told so and goes on, this many times, before the run fails.
+const CHECK_ROUNDS = 3;
+// GLM and DeepSeek on the ultra modes read on and on to be certain: two threads in production spent all their calls
+// exploring and changed nothing. Every this many calls without a write, and near the limit, the next turn is told so.
+const NUDGE_EVERY = 20;
+const LAST_CALLS = 16;
+// Past this many tokens of context the run's history is summarized and the run goes on from the summary, as Claude
+// Code and Codex compact. Below every routed model's window and OpenAI's 272k long-context price, and early enough
+// that the ultra modes' models, which lose the thread in long contexts, still work from a short one.
+export const COMPACT_TOKENS = 100_000;
+// Elbow tells a compaction request by the start of Claude Code's prompt (server/messages.js), and then keeps it on the
+// thread's model with tools off, and reads the next conversation from its summary (server/content.js).
+export const COMPACTION = `Your task is to create a detailed summary of the conversation so far, because the context is nearly full and the run will go on from your summary alone, with the original task. Call no tools; reply only with the summary, in plain text, covering:
+1. The task and what it asks for, including details the person gave that are easy to lose.
+2. Files read and what matters in them: paths, the functions, types and names involved, conventions to match.
+3. Every change made so far, file by file, and whether it is finished.
+4. Commands run that matter: tests, lint, builds, and what they showed last, with the exact errors still open.
+5. What was tried and didn't work, and why.
+6. What is left, and the very next step.`;
+const CONTINUED =
+  'This session is being continued from a previous conversation that ran out of context.';
+
+const object = (properties, required) => ({
+  type: 'object',
+  properties,
+  required,
+  additionalProperties: false,
+});
+const text = { type: 'string' };
+
+export const TOOLS = [
+  {
+    name: 'read_file',
+    description: `Read a file in the checkout, by its path relative to the repository root. Lines come numbered ("12\t…"); the number and tab aren't part of the file, so leave them out of edit_file's old_string. Returns up to ${READ_LINES} lines from offset (the first line is 1); read the part you need of a long file.`,
+    input_schema: object(
+      { path: text, offset: { type: 'integer' }, limit: { type: 'integer' } },
+      ['path'],
+    ),
+  },
+  {
+    name: 'write_file',
+    description:
+      'Write a whole file, creating it and its folders if needed. Use it for new files and rewrites.',
+    input_schema: object({ path: text, content: text }, ['path', 'content']),
+  },
+  {
+    name: 'edit_file',
+    description:
+      "Replace old_string with new_string in a file. old_string must appear exactly once, unless replace_all. For several changes, in one file or many, give them as edits instead (each with its own path, old_string and new_string): they apply in order, and if one doesn't match none is made. Returns the changed lines, numbered, so there's no need to read the file again; when old_string isn't found, the lines closest to it.",
+    input_schema: object(
+      {
+        path: text,
+        old_string: text,
+        new_string: text,
+        replace_all: { type: 'boolean' },
+        edits: {
+          type: 'array',
+          items: object(
+            { path: text, old_string: text, new_string: text, replace_all: { type: 'boolean' } },
+            ['path', 'old_string', 'new_string'],
+          ),
+        },
+      },
+      [],
+    ),
+  },
+  {
+    name: 'search',
+    description: `Search the checkout with ripgrep (a regular expression; .gitignore'd files are skipped). Returns path:line:text, or with files_only the matching files, or with no pattern every file under path; at most limit results (default ${SEARCH_RESULTS}). Narrow it with path (a folder or file) and glob (such as "*.mjs").`,
+    input_schema: object(
+      {
+        pattern: text,
+        path: text,
+        glob: text,
+        files_only: { type: 'boolean' },
+        ignore_case: { type: 'boolean' },
+        limit: { type: 'integer' },
+      },
+      [],
+    ),
+  },
+  {
+    name: 'bash',
+    description: `Run a shell command in the repository root (bash -c) and return its exit code and output. Use it to install dependencies, run tests and use git; search, read and change files with the other tools. A non-zero exit is reported, not an error: rg finding nothing exits 1. Output past ${OUTPUT_CHARS} characters keeps its start and end. Stops after timeout_seconds (default ${BASH_SECONDS}, at most 600).`,
+    input_schema: object({ command: text, timeout_seconds: { type: 'integer' } }, ['command']),
+  },
+];
+
+const BATCH =
+  'Make independent tool calls together in one reply: read the three files you need, or search for two names, in one turn rather than three; reads and searches in one reply run at once. Make related changes in one edit_file call with edits. Each reply costs a round trip; only calls that depend on an earlier result need a turn of their own.';
+const COMMIT_EARLY = `Commit to a change early. Look only at the files the task names or a search turns up, then make your best edit within your first ${NUDGE_EVERY} tool calls and let the tests tell you what's wrong. You don't need to be sure before you edit: a first attempt you then fix costs less than more reading. You have ${MAX_CALLS} tool calls in all.`;
+
+// What Claude Code and Codex tell their agents and our first runs lacked: a semver.mjs that passed its tests came back
+// with function declarations in a repository of const arrows, JSDoc and a section divider, and range bugs no test
+// covered.
+export const system = ({ workspace, checks, guide, memory = [], context = '', base = null }) =>
+  [
+    `You are a coding agent working on one task in a git checkout at ${workspace}, on a machine of its own.`,
+    'Use the tools to read the code, make the change the task asks for and run the tests. Paths are relative to the repository root.',
+    BATCH,
+    COMMIT_EARLY,
+    "Write code that reads like the code around it: match how the files you've read declare functions, name things and comment. For a new file with nothing of its own to match, read one neighbouring source file first. Comment only what the code can't say: no file headers, section dividers or comments that restate the next line.",
+    'Do what the task asks, and handle the cases its own spec or documentation describes even where no test covers them; nothing more. Don\'t go looking for further cases, refactors or improvements.',
+    'If the repository has a lint or format command (a package.json script, or a Biome, ESLint or Prettier config), run it once on what you changed before you finish.',
+    // Threads in production spent up to 95 calls hunting for a GitHub credential to push with, and rebased onto a stale
+    // base when fetch failed: the runner does all of that, and the agent has no network git.
+    `Elbow commits what you leave in the checkout, pushes it and opens or updates the pull request once you finish; you have no GitHub access, and git can't reach the network. Don't commit, push, fetch, stash, reset or switch branches, and don't look for credentials.${base ? ` origin/${base} is the base as the run began: git diff origin/${base} shows the branch's changes. When the task asks to rebase on or merge ${base}, run git merge origin/${base} and resolve any conflicts; Elbow keeps the merge.` : ''}`,
+    checks.length
+      ? `The task is done when these tests pass with node --test: ${checks.join(', ')}. Don't edit them: they are put back as they were before they run.`
+      : 'Run the tests that cover your change before you finish.',
+    'When the work is done, reply with one or two plain sentences on what you changed and why, and call no more tools. It becomes the pull request description: no headings, lists, file-by-file notes or test results.',
+    ...(context ? [`The checkout as the run began:\n${context}`] : []),
+    ...(memory.length
+      ? [`What the team has saved about this repository:\n${memory.map((fact) => `- ${fact}`).join('\n')}`]
+      : []),
+    ...(guide ? [`The repository's own instructions for agents (${guide.file}) follow; they win over anything above.\n\n${guide.text}`] : []),
+  ].join('\n');
+
+// The same agent on a benchmark task (eval/agentic/thread.mjs): no pull request, no repository of the team's, and a
+// task that may be about the whole machine rather than one checkout.
+export const benchSystem = ({ workspace, guide, context = '' }) =>
+  [
+    `You are a coding agent working on one task on a machine of its own, in ${workspace}. Nobody will answer questions: decide for yourself and keep going until the task is done.`,
+    `read_file, write_file, edit_file and search take paths relative to ${workspace} and stay inside it; for anything elsewhere on the machine, use bash.`,
+    BATCH,
+    COMMIT_EARLY,
+    'Do what the task asks, and check the result against each of its requirements before you finish; nothing more.',
+    'When the work is done, reply with one or two plain sentences on what you did, and call no more tools.',
+    ...(context ? [`${workspace} as the run began:\n${context}`] : []),
+    ...(guide ? [`The repository's own instructions for agents (${guide.file}) follow; they win over anything above.\n\n${guide.text}`] : []),
+  ].join('\n');
+
+// The same agent in a person's own checkout, through an app such as T3 Code (cli/acp.mjs): they read each reply and
+// answer, and a turn may be a question rather than a change.
+export const chatSystem = ({ workspace, guide, context = '' }) =>
+  [
+    `You are Elbow, a coding agent working with a person in their git checkout at ${workspace}, on their own machine. They read your replies and answer them.`,
+    'Do what their message asks: answer a question from the code without changing files, and make a change when they ask for one. If a request is unclear in a way that matters, ask before you change anything.',
+    BATCH,
+    "Write code that reads like the code around it: match how the files you've read declare functions, name things and comment. Comment only what the code can't say.",
+    'Do what was asked and nothing more: no further cases, refactors or improvements they didn\'t ask for.',
+    'Run the tests that cover a change, and the repository\'s lint or format command if it has one, before you finish.',
+    "Don't commit, push, reset, stash or switch branches unless they ask you to.",
+    'When you are done, reply briefly with the answer or what you changed and why. Markdown is fine.',
+    ...(context ? [`The checkout as the conversation began:\n${context}`] : []),
+    ...(guide ? [`The repository's own instructions for agents (${guide.file}) follow; they win over anything above.\n\n${guide.text}`] : []),
+  ].join('\n');
+
+const GUIDE_CHARS = 32 * 1024;
+
+// The repository's instructions for coding agents, as Claude Code and Codex read them: AGENTS.md, else CLAUDE.md.
+export const guideOf = async (workspace, box = local) => {
+  for (const file of ['AGENTS.md', 'CLAUDE.md']) {
+    const text = await box.read(path.join(workspace, file)).then(String, () => null);
+    if (text?.trim()) return { file, text: text.slice(0, GUIDE_CHARS) };
+  }
+  return null;
+};
+
+// What Claude Code and Codex put in the prompt so the agent needn't spend its first calls on ls, git status and
+// node --version: the tracked files, what's changed, and the tools at hand. Read once, so every turn's prefix stays cached.
+export const contextOf = async (workspace, box = local) => {
+  const run = (command) =>
+    box
+      .run(['bash', '-c', command], { cwd: workspace, seconds: 10 })
+      .then(({ code, output }) => (code ? '' : output.trim()), () => '');
+  const [files, status, tools] = await Promise.all([
+    run('git ls-files'),
+    run('git status --short'),
+    run('echo "node $(node --version 2>/dev/null)"; for t in rg npm pnpm yarn python3; do command -v $t >/dev/null && printf "%s " $t; done'),
+  ]);
+  const list = files ? files.split('\n') : [];
+  const shown = list.slice(0, TREE_FILES).join('\n');
+  return [
+    list.length ? `Tracked files (${list.length}):\n${shown}${list.length > TREE_FILES ? `\n[… ${list.length - TREE_FILES} more; rg --files lists them]` : ''}` : '',
+    list.length ? (status ? `git status --short:\n${status}` : 'git status: clean') : '',
+    tools ? `On the machine: ${tools.replace('\n', '; ')}` : '',
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+};
+
+// The start of a command's output says what ran and the end how it finished, so both stay.
+const clip = (value, limit = OUTPUT_CHARS) => {
+  if (value.length <= limit) return value;
+  const head = Math.floor(limit / 4);
+  return `${value.slice(0, head)}\n[… ${value.length - limit} characters cut]\n${value.slice(head - limit)}`;
+};
+
+// The run's key lives only in the runner's memory; nothing the agent runs sees it.
+const BARE_ENV = () => ({ PATH: process.env.PATH, HOME: process.env.HOME, LANG: 'C.UTF-8', CI: '1' });
+
+// Runs a command in its own process group, so a timeout or Stop ends whatever it started too.
+// `onOutput`, when given, gets the output as it comes, for an app that shows a command while it runs.
+export const sh = (command, args, { cwd, seconds, signal, stop, env = BARE_ENV(), onOutput }) =>
+  new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      detached: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env,
+    });
+    let head = '';
+    let tail = '';
+    let dropped = 0;
+    const add = (d) => {
+      const s = String(d);
+      onOutput?.(s);
+      if (head.length < OUTPUT_CHARS) {
+        const room = OUTPUT_CHARS - head.length;
+        head += s.slice(0, room);
+        tail += s.slice(room);
+      } else tail += s;
+      if (tail.length > OUTPUT_CHARS) {
+        dropped += tail.length - OUTPUT_CHARS;
+        tail = tail.slice(-OUTPUT_CHARS);
+      }
+    };
+    const all = () => {
+      const kept = head + tail;
+      if (!dropped) return clip(kept);
+      const start = Math.floor(OUTPUT_CHARS / 4);
+      const cut = dropped + kept.length - OUTPUT_CHARS;
+      return `${kept.slice(0, start)}\n[… ${cut} characters cut]\n${kept.slice(start - OUTPUT_CHARS)}`;
+    };
+    child.stdout.on('data', add);
+    child.stderr.on('data', add);
+    const kill = () => {
+      if (stop) return stop();
+      try {
+        process.kill(-child.pid, 'SIGKILL');
+      } catch {}
+    };
+    const timer = setTimeout(kill, seconds * 1000);
+    signal?.addEventListener('abort', kill, { once: true });
+    child.on('close', (code, killed) => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', kill);
+      resolve({ code: code ?? (killed ? 124 : 1), output: all() });
+    });
+    child.on('error', (e) => resolve({ code: 127, output: e.message }));
+  });
+
+// Where the agent's tools act. `local` is the runner's own user, for tests and the agent's own tests; on a VM it's
+// `asUser`, the run's own Unix user.
+export const local = {
+  run: ([command, ...args], options) => sh(command, args, options),
+  read: (file) => fs.readFile(file),
+  write: async (file, data) => {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, data);
+  },
+};
+
+const piped = (args, input) =>
+  new Promise((resolve, reject) => {
+    const child = execFile(
+      args[0],
+      args.slice(1),
+      { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 },
+      (error, stdout, stderr) =>
+        error ? reject(new Error(String(stderr).trim() || error.message)) : resolve(stdout),
+    );
+    child.stdin.end(input ?? '');
+  });
+
+// The run's user has no sudo and can't read or write the runner's files (~/.elbow), so the files and commands the
+// agent asks for go through it: a symlink in the checkout reaches only what that user could read anyway. The runner
+// can't signal that user's processes, so a timeout or Stop ends all of them, through sudo.
+export const asUser = (user, home) => {
+  const as = (...args) => [
+    'sudo',
+    '-n',
+    '-u',
+    user,
+    '--',
+    '/usr/bin/env',
+    '-i',
+    `PATH=${process.env.PATH}`,
+    `HOME=${home}`,
+    'LANG=C.UTF-8',
+    'CI=1',
+    ...args,
+  ];
+  const stop = () => {
+    execFile('sudo', ['-n', 'pkill', '-KILL', '-u', user], () => {});
+  };
+  return {
+    run: (args, { cwd, seconds, signal }) => {
+      const [command, ...rest] = as('/bin/sh', '-c', 'cd -- "$0" && exec "$@"', cwd, ...args);
+      return sh(command, rest, { seconds, signal, stop });
+    },
+    read: (file) => piped(as('/bin/cat', '--', file)),
+    write: (file, data) =>
+      piped(as('/bin/sh', '-c', 'mkdir -p -- "$(dirname -- "$1")" && cat >"$1"', 'sh', file), data),
+  };
+};
+
+// Paths stay inside the checkout and out of .git: not a sandbox (the VM is that), just where the work belongs.
+const inside = (workspace, file) => {
+  const full = path.resolve(workspace, String(file ?? ''));
+  const rel = path.relative(workspace, full);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || rel.split(path.sep)[0] === '.git')
+    throw new Error(`${file} is not a file in the repository.`);
+  return { full, rel };
+};
+
+// One edit, or the several an edit_file call gives as edits, each with its path.
+const editsOf = (input = {}) =>
+  Array.isArray(input.edits)
+    ? input.edits.map((e) => ({ ...e, path: e?.path ?? input.path }))
+    : input.old_string != null || input.new_string != null
+      ? [{ path: input.path, old_string: input.old_string, new_string: input.new_string, replace_all: input.replace_all }]
+      : [];
+
+const numbered = (lines, from) => lines.map((line, i) => `${from + i}\t${line}`).join('\n');
+
+const snippet = (text, at, inserted) => {
+  const lines = text.split('\n');
+  if (lines.at(-1) === '') lines.pop();
+  const start = text.slice(0, at).split('\n').length;
+  const end = start + inserted.split('\n').length - 1;
+  const from = Math.max(start - AROUND, 1);
+  const to = Math.min(end + AROUND, lines.length);
+  const shown = lines.slice(from - 1, Math.min(to, from - 1 + SNIPPET_LINES));
+  const rest = to - (from - 1 + shown.length);
+  return numbered(shown, from) + (rest > 0 ? `\n[… ${rest} more changed lines]` : '');
+};
+
+// Where old_string most nearly is, by lines that match once indentation is set aside: a missed edit is mostly
+// whitespace or a line that changed, and the model can fix it from these without reading the file again.
+const closest = (text, old) => {
+  const lines = text.split('\n');
+  const want = old.split('\n').slice(0, 50).map((l) => l.trim());
+  let best = 0;
+  let at = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    let score = 0;
+    for (let j = 0; j < want.length && i + j < lines.length; j += 1)
+      if (want[j] && lines[i + j].trim() === want[j]) score += 1;
+    if (score > best) [best, at] = [score, i];
+  }
+  if (!best) return '';
+  const from = Math.max(at - 2, 0);
+  const shown = lines.slice(from, Math.min(at + want.length + 2, from + 30));
+  return `\nThe closest lines (${best} of ${want.length} match, setting indentation aside):\n${numbered(shown, from + 1)}`;
+};
+
+const replace = (before, { old_string, new_string, replace_all }, rel) => {
+  const old = String(old_string ?? '');
+  const count = old ? before.split(old).length - 1 : 0;
+  if (!count) {
+    const numbers = old && old.split('\n').every((l) => /^\s*\d+\t/.test(l));
+    throw new Error(
+      `old_string isn't in ${rel}.${numbers ? " It starts its lines with read_file's line numbers and tabs; leave them out." : ''}${closest(before, old)}`,
+    );
+  }
+  if (count > 1 && !replace_all)
+    throw new Error(`old_string appears ${count} times in ${rel}; give more context or replace_all.`);
+  return { text: before.split(old).join(String(new_string ?? '')), at: before.indexOf(old) };
+};
+
+const tools = {
+  read_file: async ({ path: file, offset, limit }, { workspace, box }) => {
+    const lines = String(await box.read(inside(workspace, file).full)).split('\n');
+    if (lines.at(-1) === '') lines.pop();
+    const from = Math.max(Number(offset) || 1, 1);
+    const count = Math.min(Math.max(Number(limit) || READ_LINES, 1), READ_LINES);
+    const shown = lines.slice(from - 1, from - 1 + count);
+    if (!shown.length) return lines.length ? `${file} has ${lines.length} lines.` : `${file} is empty.`;
+    const out = shown.map((line, i) => {
+      const cut = line.length > LINE_CHARS ? `${line.slice(0, LINE_CHARS)}[… line cut]` : line;
+      return `${from + i}\t${cut}`;
+    });
+    const rest = lines.length - (from - 1 + shown.length);
+    if (rest > 0) out.push(`[${rest} more lines; read on with offset ${from + shown.length}]`);
+    return out.join('\n');
+  },
+  write_file: async ({ path: file, content }, { workspace, box, wrote }) => {
+    const { full, rel } = inside(workspace, file);
+    await box.write(full, String(content ?? ''));
+    wrote(rel);
+    return `Wrote ${rel}.`;
+  },
+  edit_file: async (input, { workspace, box, wrote }) => {
+    const edits = editsOf(input);
+    if (!edits.length) throw new Error('Give path, old_string and new_string, or edits.');
+    const files = new Map();
+    const shown = [];
+    for (const [n, edit] of edits.entries()) {
+      const { full, rel } = inside(workspace, edit.path);
+      if (!files.has(rel)) files.set(rel, { full, text: String(await box.read(full)) });
+      const file = files.get(rel);
+      try {
+        const { text, at } = replace(file.text, edit, rel);
+        file.text = text;
+        shown.push({ rel, lines: snippet(text, at, String(edit.new_string ?? '')) });
+      } catch (e) {
+        if (edits.length === 1) throw e;
+        throw new Error(`Edit ${n + 1} of ${edits.length}: ${e.message}\nNo file was changed.`);
+      }
+    }
+    for (const [rel, { full, text }] of files) {
+      await box.write(full, text);
+      wrote(rel);
+    }
+    if (files.size === 1) return `Edited ${shown[0].rel}:\n${shown.map((e) => e.lines).join('\n…\n')}`;
+    return `Edited ${[...files.keys()].join(', ')}:\n\n${shown.map((e) => `${e.rel}:\n${e.lines}`).join('\n\n')}`;
+  },
+  search: async ({ pattern, path: where, glob, files_only, ignore_case, limit }, { workspace, box, signal }) => {
+    const dir = !where || where === '.' ? '.' : inside(workspace, where).rel;
+    const listing = pattern == null || pattern === '';
+    const args = [
+      'rg',
+      '--no-heading',
+      '--color=never',
+      '--sort=path',
+      '--max-columns=300',
+      '--max-columns-preview',
+      ...(ignore_case ? ['-i'] : []),
+      ...(glob ? ['-g', String(glob)] : []),
+      ...(listing ? ['--files'] : [files_only ? '-l' : '-n', '-e', String(pattern)]),
+      '--',
+      dir,
+    ];
+    const { code, output } = await box.run(args, { cwd: workspace, seconds: SEARCH_SECONDS, signal });
+    if (code === 1) return 'No matches.';
+    if (code !== 0) throw new Error(`rg exited ${code}\n${output}`);
+    const max = Math.min(Math.max(Number(limit) || SEARCH_RESULTS, 1), 1000);
+    // Paths as the other tools take them, without the ./ rg puts before them under '.'.
+    const lines = output.trimEnd().replace(/^\.\//gm, '').split('\n');
+    const more = lines.length - max;
+    return more > 0
+      ? `${lines.slice(0, max).join('\n')}\n[${more} more; narrow the pattern, path or glob]`
+      : lines.join('\n');
+  },
+  bash: async ({ command, timeout_seconds }, { workspace, box, signal }) => {
+    const seconds = Math.min(Math.max(Number(timeout_seconds) || BASH_SECONDS, 1), 600);
+    const { code, output } = await box.run(['bash', '-c', String(command ?? '')], {
+      cwd: workspace,
+      seconds,
+      signal,
+    });
+    return { output: `exit ${code}\n${output}`, failed: code !== 0 };
+  },
+};
+
+// Elbow's Messages stream, put back together as the assistant message it carries, with when the first block that
+// isn't thinking began (the app's "Thought for 14s").
+// `stream`, when given, gets each piece of text and thinking as it arrives.
+const assemble = async (res, stream) => {
+  const content = [];
+  const json = [];
+  // The tool calls a reply ended in the middle of, when it ran out of output tokens: their JSON input stops short.
+  const cut = new Set();
+  let stop;
+  let answered;
+  // Each count as the largest any event gave: a provider can send a field again as 0 in message_delta.
+  const usage = {};
+  const count = (u = {}) => {
+    for (const [k, v] of Object.entries(u)) if (typeof v === 'number') usage[k] = Math.max(usage[k] ?? 0, v);
+  };
+  let buffer = '';
+  const decoder = new TextDecoder();
+  const handle = (event) => {
+    if (event.type === 'error') throw new Error(event.error?.message ?? 'Elbow sent an error.');
+    if (event.type === 'content_block_start') {
+      content[event.index] = { ...event.content_block };
+      if (event.content_block?.type !== 'thinking') answered ??= Date.now();
+      json[event.index] = '';
+    } else if (event.type === 'content_block_delta') {
+      const block = content[event.index];
+      const d = event.delta;
+      if (d.type === 'text_delta') {
+        block.text += d.text;
+        stream?.({ type: 'text', text: d.text });
+      } else if (d.type === 'thinking_delta') {
+        block.thinking += d.thinking;
+        stream?.({ type: 'thinking', text: d.thinking });
+      }
+      else if (d.type === 'signature_delta') block.signature = (block.signature ?? '') + d.signature;
+      else if (d.type === 'input_json_delta') json[event.index] += d.partial_json;
+    } else if (event.type === 'content_block_stop') {
+      const block = content[event.index];
+      if (block.type === 'tool_use')
+        try {
+          block.input = json[event.index] ? JSON.parse(json[event.index]) : {};
+        } catch {
+          block.input = {};
+          cut.add(block.id);
+        }
+    } else if (event.type === 'message_start') count(event.message?.usage);
+    else if (event.type === 'message_delta') {
+      stop = event.delta?.stop_reason ?? stop;
+      count(event.usage);
+    }
+  };
+  for await (const part of res.body) {
+    buffer += decoder.decode(part, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop();
+    for (const line of lines) if (line.startsWith('data:')) handle(JSON.parse(line.slice(5)));
+  }
+  const tokens =
+    (usage.input_tokens ?? 0) +
+    (usage.cache_read_input_tokens ?? 0) +
+    (usage.cache_creation_input_tokens ?? 0) +
+    (usage.output_tokens ?? 0);
+  return { content: content.filter(Boolean), stop, answered: answered ?? Date.now(), cut, tokens };
+};
+
+const ask = async ({
+  url,
+  key,
+  model,
+  run,
+  instructions = system,
+  workspace,
+  checks,
+  guide,
+  memory,
+  context,
+  base,
+  messages,
+  signal,
+  headers = {},
+  stream,
+}) => {
+  const asked = Date.now();
+  const res = await fetch(`${url}/v1/messages`, {
+    method: 'POST',
+    headers: {
+      'x-api-key': key,
+      'anthropic-version': '2023-06-01',
+      'content-type': 'application/json',
+      'user-agent': 'elbow-harness',
+      ...headers,
+    },
+    body: JSON.stringify({
+      model,
+      // One session per run, so Elbow keeps its turns together, as it does a Claude Code session's.
+      metadata: { user_id: JSON.stringify({ session_id: run }) },
+      max_tokens: MAX_TOKENS,
+      stream: true,
+      system: instructions({ workspace, checks, guide, memory, context, base }),
+      tools: TOOLS,
+      messages,
+    }),
+    signal,
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(`Elbow answered ${res.status}: ${body.error?.message ?? ''}`.trim());
+  }
+  const turn = await assemble(res, stream);
+  const thought = turn.content.some((b) => b.type === 'thinking') ? turn.answered - asked : null;
+  return { content: turn.content, stop: turn.stop, thought, cut: turn.cut, tokens: turn.tokens };
+};
+
+// A rough count for what Elbow hasn't reported yet: four characters a token, and an image at its usual cost rather
+// than its base64 length.
+const IMAGE_TOKENS = 1600;
+export const estimate = (messages) =>
+  Math.ceil(
+    JSON.stringify(messages, (k, v) => (k === 'source' && v?.type === 'base64' ? '' : v)).length / 4,
+  ) +
+  IMAGE_TOKENS *
+    messages.flatMap((m) => (Array.isArray(m.content) ? m.content : [])).filter((b) => b.type === 'image')
+      .length;
+
+// The request the summary is asked on is the run's own conversation with the prompt added to its last user message,
+// as Claude Code sends it, so the prompt cache holds and the model summarizes what it has read.
+export const compactionRequest = (messages) => {
+  const last = messages.at(-1);
+  const prompt = { type: 'text', text: COMPACTION };
+  const content = typeof last.content === 'string' ? [{ type: 'text', text: last.content }] : last.content;
+  return [...messages.slice(0, -1), { ...last, content: [...content, prompt] }];
+};
+
+// Screenshots the person attached come before the task, which refers to them.
+const opening = (images, text) => [
+  {
+    role: 'user',
+    content: images.length
+      ? [
+          ...images.map(({ media_type, data }) => ({
+            type: 'image',
+            source: { type: 'base64', media_type, data },
+          })),
+          { type: 'text', text },
+        ]
+      : text,
+  },
+];
+
+// What the run goes on from: the task as it was asked, screenshots included, and the summary.
+export const continued = ({ task, images = [], summary }) =>
+  opening(
+    images,
+    `${CONTINUED} The task, as it was asked:\n\n${task}\n\nSummary:\n${summary}\n\nThe checkout holds every change made so far. Carry on from the next step in the summary without asking anything; read a file again before you edit it.`,
+  );
+
+// The summary, or null when the model gave none: it called a tool instead, ran out of output or Elbow failed.
+const compact = async ({ messages, signal, ...rest }) => {
+  try {
+    const turn = await ask({ ...rest, messages: compactionRequest(messages), signal });
+    if (turn.stop === 'max_tokens') return null;
+    const summary = turn.content
+      .filter((b) => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n')
+      .trim();
+    return summary || null;
+  } catch (e) {
+    if (signal?.aborted) throw e;
+    return null;
+  }
+};
+
+// A conversation summarized on request (an app's /compact): the summary replaces its messages, or null when the model
+// gave none and they stay as they were.
+export const compactConversation = async ({ workspace, box = local, messages, ...rest }) => {
+  if (!messages.length) return null;
+  const [guide, context] = await Promise.all([guideOf(workspace, box), contextOf(workspace, box)]);
+  // Asked as a message of its own: between a person's turns the conversation ends on the agent's reply.
+  const turn = await ask({
+    ...rest,
+    workspace,
+    checks: [],
+    guide,
+    context,
+    messages: [...messages, { role: 'user', content: COMPACTION }],
+  });
+  const summary =
+    turn.stop === 'max_tokens'
+      ? null
+      : turn.content
+          .filter((b) => b.type === 'text')
+          .map((b) => b.text)
+          .join('\n')
+          .trim() || null;
+  if (summary)
+    messages.splice(0, messages.length, {
+      role: 'user',
+      content: `${CONTINUED} Summary:\n${summary}\n\nThe checkout holds every change made so far; read a file again before you edit it.`,
+    });
+  return summary;
+};
+
+// One task, as a loop of model turns and tool calls until the model stops calling tools and the checks pass.
+// `record` gets the receipts Elbow for Mac shows (mac/core/src/Harness.swift).
+// What goes with a turn's tool results when the run is exploring instead of working, or running out of calls.
+export const nudgeOf = ({ calls, idle, idleBefore }) => {
+  const left = MAX_CALLS - calls;
+  if (left <= LAST_CALLS)
+    return `${left} tool calls left. Finish the change you have, run its tests once and stop; don't start anything new.`;
+  if (Math.floor(idle / NUDGE_EVERY) > Math.floor(idleBefore / NUDGE_EVERY))
+    return `${idle} tool calls without changing a file. Stop exploring: you know enough to try. Make your best change now with edit_file or write_file, then run the tests and fix what they show.`;
+  return null;
+};
+
+export const runAgent = async ({
+  url,
+  key,
+  model,
+  run,
+  task,
+  images = [],
+  workspace,
+  checks,
+  memory = [],
+  record,
+  signal,
+  box = local,
+  compactAt = COMPACT_TOKENS,
+  base = null,
+  instructions = system,
+  // A conversation that goes on across tasks (cli/acp.mjs) hands in its messages; the run adds to them in place.
+  conversation = [],
+  // Asked before a call that changes something or runs a command; false declines it. Left out, every call runs.
+  approve = null,
+  nudge = nudgeOf,
+  headers = {},
+  // Each turn's text and thinking as they arrive, for an app that shows them as they're written (cli/acp.mjs).
+  stream,
+  // The context Elbow reports after each turn, in tokens.
+  measured,
+}) => {
+  record({ event: 'run_started', task, model, checks, ...(images.length && { images: images.length }) });
+  const originals = Object.fromEntries(
+    await Promise.all(
+      checks.map(async (c) => [c, await box.read(path.join(workspace, c)).catch(() => null)]),
+    ),
+  );
+  const [guide, context] = await Promise.all([guideOf(workspace, box), contextOf(workspace, box)]);
+  const messages = conversation;
+  messages.push(...opening(images, task));
+  const prompt = { instructions, workspace, checks, guide, memory, context, base, headers };
+  // The prompt and tools are sent on every request; Elbow's usage counts them, the estimate needs them added.
+  const fixed = Math.ceil((instructions(prompt).length + JSON.stringify(TOOLS).length) / 4);
+  // The context Elbow last reported, and how many messages it covered.
+  let known = { tokens: 0, at: 0 };
+  let compactable = true;
+  let calls = 0;
+  let idle = 0;
+  let rounds = 0;
+  const finish = (ok, error, message) => {
+    record({ event: 'run_completed', outcome: ok ? 'ok' : 'error', error: error ?? null });
+    return { ok, error, message };
+  };
+  const missing = checks.filter((c) => !originals[c]);
+  if (missing.length)
+    return finish(false, `These checks aren't files in the repository: ${missing.join(', ')}.`);
+  try {
+    for (;;) {
+      const tokens = known.tokens
+        ? known.tokens + estimate(messages.slice(known.at))
+        : fixed + estimate(messages);
+      if (compactable && tokens > compactAt) {
+        const summary = await compact({ url, key, model, run, ...prompt, messages, signal });
+        if (summary) {
+          messages.splice(0, messages.length, ...continued({ task, images, summary }));
+          known = { tokens: 0, at: 0 };
+          record({ event: 'compacted', tokens, summary });
+        } else {
+          // A run that can't be summarized goes on as it is, until the model's own window ends it.
+          compactable = false;
+          record({ event: 'compaction_failed', tokens });
+        }
+      }
+      const turn = await ask({ url, key, model, run, ...prompt, messages, signal, stream });
+      messages.push({ role: 'assistant', content: turn.content });
+      if (turn.tokens) {
+        known = { tokens: turn.tokens, at: messages.length };
+        measured?.(turn.tokens);
+      }
+      if (turn.thought !== null) record({ event: 'thought', ms: turn.thought });
+      const said = turn.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n')
+        .trim();
+      if (said) record({ event: 'assistant_message', text: said });
+      const uses = turn.content.filter((b) => b.type === 'tool_use');
+      if (!uses.length) {
+        if (turn.stop === 'max_tokens') return finish(false, 'A model turn ran out of output tokens.');
+        const failing = await verify({ workspace, box, checks, originals, record, signal, next: () => (calls += 1) });
+        if (!failing) return finish(true, null, said);
+        rounds += 1;
+        if (rounds >= CHECK_ROUNDS) return finish(false, "The checks didn't all pass.", said);
+        messages.push({
+          role: 'user',
+          content: `These checks fail, so the task isn't done. Fix the code, not the tests:\n\n${failing}`,
+        });
+        continue;
+      }
+      const idleBefore = idle;
+      const results = [];
+      // A call's receipts, one per edit for an edit_file with edits, so Elbow for Mac shows each with its diff.
+      const perform = async (use, parts, first) => {
+        parts.forEach((input, k) => record({ event: 'tool_started', call: first + k, tool: use.name, input }));
+        const callOf = (file) => first + Math.max(parts.findIndex((p) => inside(workspace, p.path).rel === file), 0);
+        let output;
+        let ok = true;
+        // A command that exits non-zero reads as an error in Elbow for Mac, but goes back to the model as a result.
+        let failed = false;
+        try {
+          const tool = tools[use.name];
+          if (turn.cut.has(use.id))
+            throw new Error(
+              "This call was cut off: the reply ran out of output tokens before its input was complete, so it didn't run. Make it again, smaller; write a long file in parts.",
+            );
+          if (!tool) throw new Error(`There's no tool called ${use.name}.`);
+          // true runs the call; anything else declines it, a string saying why.
+          const verdict = approve && !READ_ONLY.has(use.name) ? await approve(use, first) : true;
+          if (verdict !== true)
+            throw new Error(
+              typeof verdict === 'string'
+                ? verdict
+                : signal?.aborted
+                  ? 'The person stopped the turn before this call ran.'
+                  : "The person declined this call. Don't make it again; ask them what they'd like instead.",
+            );
+          const out = await tool(use.input ?? {}, {
+            workspace,
+            box,
+            signal,
+            wrote: (file) => record({ event: 'write_completed', call: callOf(file), path: file }),
+          });
+          output = out?.output ?? out;
+          failed = !!out?.failed;
+        } catch (e) {
+          ok = false;
+          output = e.message;
+        }
+        parts.forEach((_, k) =>
+          record({ event: 'tool_completed', call: first + k, tool: use.name, outcome: ok && !failed ? 'ok' : 'error', output: clip(output, 16_384) }),
+        );
+        return { ok, result: { type: 'tool_result', tool_use_id: use.id, content: output, ...(ok ? {} : { is_error: true }) } };
+      };
+      let reading = [];
+      const settle = async () => {
+        await Promise.all(reading);
+        reading = [];
+      };
+      for (const [i, use] of uses.entries()) {
+        const edits = use.name === 'edit_file' && !turn.cut.has(use.id) ? editsOf(use.input) : [];
+        const parts = edits.length > 1 ? edits : [use.input];
+        const first = calls + 1;
+        calls += parts.length;
+        if (calls > MAX_CALLS) {
+          await settle();
+          record({ event: 'limit', output: `More than ${MAX_CALLS} tool calls.` });
+          return finish(false, `The run made more than ${MAX_CALLS} tool calls.`);
+        }
+        const job = perform(use, parts, first).then((done) => {
+          results[i] = done;
+        });
+        if (READ_ONLY.has(use.name)) reading.push(job);
+        else {
+          await settle();
+          await job;
+        }
+      }
+      await settle();
+      for (const [i, use] of uses.entries())
+        idle = results[i].ok && (use.name === 'write_file' || use.name === 'edit_file') ? 0 : idle + 1;
+      const note = nudge({ calls, idle, idleBefore });
+      const content = results.map((r) => r.result);
+      messages.push({ role: 'user', content: note ? [...content, { type: 'text', text: note }] : content });
+    }
+  } catch (e) {
+    return finish(false, signal?.aborted ? 'Stopped.' : e.message);
+  }
+};
+
+// The checks run on the tests as they were, whatever the agent did to them. Returns what failed, or '' when all pass.
+const verify = async ({ workspace, box, checks, originals, record, signal, next }) => {
+  const failed = [];
+  for (const check of checks) {
+    await box.write(path.join(workspace, check), originals[check]);
+    const call = next();
+    record({ event: 'tool_started', call, tool: 'run_check', input: { path: check } });
+    const { code, output } = await box.run([process.execPath, '--test', '--test-reporter=spec', check], {
+      cwd: workspace,
+      seconds: CHECK_SECONDS,
+      signal,
+    });
+    record({ event: 'tool_completed', call, tool: 'run_check', outcome: code ? 'error' : 'ok', output: clip(output, 16_384) });
+    if (code) failed.push(`${check}:\n${clip(output, 8_000)}`);
+  }
+  return failed.join('\n\n');
+};