agent-office-studio 0.0.0-stage → 0.2.0

package/docs/using-the-office.md

@@ -0,0 +1,109 @@
+# Using the office
+
+## Talking to the office
+
+There's no form: you chat. Type `@` to tag an agent and `#` to name a project.
+
+- `@Ada #storefront check the open PRs` goes straight to Ada.
+- Untagged messages go to the **chief of staff** at reception (Sonnet by
+  default), who decides who should handle them:
+  - a message that relates to a running job is handed to that agent *live*,
+    and they fold it into the work they're already doing;
+  - a follow-up to a finished job resumes that agent's session;
+  - new work goes to whoever's free, or queues for the agent you tagged;
+  - if it can't tell which project you mean, it asks.
+- Agents post their results back into the chat.
+
+Attach files with the paperclip, by pasting, or by dropping them on the
+composer. A screenshot is shown to the chief itself, so "this again" over a
+picture of an error is enough to route on: it reads the picture, picks the
+project and the agent from what's in it, and writes the brief in words. Other
+file types (and the audio of a voice note) it can't open, so those go by name
+and the agent reads them with the Read tool — the path travels with the job.
+
+The clearance and model pickers under the composer apply to new work. The
+model picker starts on **Chief picks**, which hands the choice to the chief
+(see [Jobs](jobs.md#sizing-the-work)); choosing a model yourself overrides it for
+that job.
+
+### Channels
+
+The chat is split into channels, the way Slack is. `#general` is always
+there; the `+` in the channel bar opens another one for a strand of work,
+and a channel with nothing left in it can be closed again.
+
+Every message belongs to exactly one channel. What you ask in `#design`
+stays in `#design`: the chief answers there, the agent who picks the job up
+reports back there, anything they hand to a colleague stays there too, and
+the chief only reads that channel's history when deciding what you meant.
+Threads live in their channel. A channel you aren't reading shows a count of
+what you've missed.
+
+### Threads
+
+A message stays where you sent it. Type in the main chat and it stays in the
+main chat; reply in a thread and the whole exchange stays in that thread.
+Nothing is ever moved after you have seen it.
+
+What threads collect is an agent's updates on a job, which hang under the
+message that started the job as a summary line you can open. So when you
+follow up on running work from the main chat, your message and the chief's
+answer stay in front of you, and the answer carries a link to the thread the
+updates are collecting in.
+
+## Getting around
+
+Drag to move, right-drag (or `Q` / `E`) to turn around what's in the middle
+of the view, scroll to zoom toward the cursor, double-click to glide somewhere.
+`W A S D` pan, `R` recenters. The walls nearest you drop down so you can always
+see in. Chat and job details sit in their own columns and never cover the
+office, and `⌃`` opens the terminal drawer beneath it.
+
+## Daily standup
+
+Every weekday at 9:30 the team gathers in a circle by the whiteboard. One at
+a time, everyone on the floor says what they got done since the last standup,
+what they're on today and what's blocking them, and the chief wraps up: the
+focus, the risks and who's free. Agents who've gone home don't attend. The
+updates come from the job history, written up by one call to the chief's
+model; a quiet office skips that call, and if it fails the updates are built
+from the facts alone.
+
+Call one any time with the people button in the top right, `/standup` in the
+chat, or just by asking ("standup time"). If the office opens after 9:30, the
+day's standup happens then, but not after 6pm, and a day with nothing to
+report is skipped. Jobs keep running during standup, and agents who start work
+later in the day are told what the team said.
+
+## The break room
+
+Agents with nothing on drift to the break room, and every so often two of
+them turn to each other and talk. One short call to a small model (Haiku by
+default) writes the exchange from who they are, how they feel about each
+other and what they have been working on, so it costs a fraction of a chat
+message. At most one is written every two minutes; between those, and if the
+call fails, they fall back to canned small talk. `BANTER=off` keeps it canned.
+
+What they say lands in **#chill-room**, a channel that is always there, that
+everyone is in, and that can't be closed. It keeps its own 60 most recent
+lines, so small talk never pushes the day's work out of the chat history, and
+it is never read aloud.
+
+Two idle agents will sometimes walk over to the pool table instead and play a
+real game of eight-ball, a shot at a time. The start and the result go to
+#chill-room. Anyone handed work, called to standup or sent home drops what
+they're doing, and the chat or the game ends there.
+
+With the office open in two windows, each conversation and each game is
+claimed from the server first, so it happens once rather than once per window.
+
+## Levels
+
+Shipped jobs earn XP. Each level hires one more agent, so more jobs run at
+once (3 at level 1, up to 8).
+
+## Appearance
+
+The palette button at the top of the sidebar picks a theme (Paper, Ocean,
+Forest, Sunset, Lavender) and light, dark or automatic mode. The choice is
+kept in this browser.

package/docs/voice.md

@@ -0,0 +1,44 @@
+# Talking out loud
+
+You can say it instead of typing it, and hear the answer back. None of it
+leaves the machine: `whisper.cpp` does the listening and the system voices do
+the talking.
+
+```bash
+brew install ffmpeg whisper-cpp
+npm run voice:model        # ~148 MB, ears
+npm run voice:piper        # ~700 MB, voices
+```
+
+The microphone sits next to the paperclip, and `⌥M` works from anywhere.
+Click once to start, again to stop. What you said lands **in the composer**
+rather than going straight out, so you can fix a misheard name before anyone
+acts on it, and the recording rides along attached so you can hear what you
+actually said. Escape throws a recording away.
+
+The office knows its own vocabulary, so spoken names come back spelled the way
+the chief can route on them: "Ada, check the open PRs in Storefront" arrives as
+*storefront*, not *store front*. Say `@` and `#` tags as plain names — the chief reads
+them either way.
+
+The speaker button in the top right turns on replies in kind. The chief and
+the agents reporting back to you each record a **voice note** in their own
+voice, attached to the message: it plays as it lands and stays there to
+replay. Everyone sounds different, so you know who's talking without looking,
+and standup becomes something you can listen to while doing something else.
+
+The voices are [Piper](https://github.com/OHF-Voice/piper1-gpl), a neural
+text-to-speech model that runs here — Apple's built-in voices are a decade
+older and sound it. A line takes a few seconds to record, which is why agents
+send notes rather than narrating live: the text lands immediately and the
+voice catches up. Without Piper installed the office falls back to the system
+voices, spoken live by the browser.
+
+Agent-to-agent asides and break-room talk stay unspoken; they'd be constant,
+and they aren't for you. Markdown, code blocks and file paths are stripped
+before anything is said, because nobody wants to hear "backtick slash server
+slash index dot j s backtick" — the bubble keeps the detail. The small speaker
+on any message replays just that one.
+
+Agents never hear audio themselves: `claude -p` takes text, so a voice note
+reaches them as its transcript.

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "agent-office-studio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A 3D office where the staff are Claude Code agents.",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "dist",
+    "server",
+    "shared",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onuohasilver/agent-office.git"
+  },
+  "homepage": "https://github.com/onuohasilver/agent-office#readme",
+  "bugs": "https://github.com/onuohasilver/agent-office/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "ai",
+    "three.js",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "agentoffice": "bin/agentoffice.js",
+    "agentstudio": "bin/agentoffice.js"
+  },
+  "scripts": {
+    "dev": "concurrently -k -n server,web -c blue,magenta \"node --watch server/index.js\" \"vite\"",
+    "build": "vite build",
+    "start": "vite build && node server/supervise.js",
+    "voice:model": "mkdir -p data/whisper && curl -L --progress-bar -o data/whisper/ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin",
+    "voice:piper": "python3 -m venv data/piper/venv && data/piper/venv/bin/pip install -q piper-tts && data/piper/venv/bin/python -m piper.download_voices --data-dir data/piper/voices en_GB-cori-high en_US-amy-medium en_GB-alan-medium en_US-kristin-medium en_US-ryan-high en_GB-alba-medium en_GB-aru-medium en_US-john-medium en_US-hfc_female-medium",
+    "test": "node scripts/smoke.mjs",
+    "prepack": "vite build"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "5.1.0",
+    "@fontsource/jetbrains-mono": "5.1.1",
+    "@xterm/addon-fit": "0.10.0",
+    "@xterm/xterm": "5.5.0",
+    "marked": "^14.1.3",
+    "three": "0.169.0",
+    "ws": "8.18.0"
+  },
+  "devDependencies": {
+    "concurrently": "9.0.1",
+    "vite": "5.4.10"
+  },
+  "optionalDependencies": {
+    "node-pty": "1.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,89 @@
+// How the office's claude processes sign in: the Claude Code login already on
+// this machine, or an Anthropic API key the boss gives it. The key lives in
+// its own file, readable only by you, and never goes to the browser: the
+// page only ever learns which way is chosen and the key's last four.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MODES = ['login', 'apikey'];
+
+export class Auth {
+  constructor(dataDir) {
+    this.file = path.join(dataDir, 'auth.json');
+    let saved = {};
+    try { saved = JSON.parse(fs.readFileSync(this.file, 'utf8')); } catch {}
+    this.key = typeof saved.key === 'string' ? saved.key : '';
+    // Until someone chooses, a key already in the environment is the choice,
+    // which is what `claude` itself would have done with it.
+    this.mode = MODES.includes(saved.mode) ? saved.mode : process.env.ANTHROPIC_API_KEY ? 'apikey' : 'login';
+  }
+
+  // The key that will be used: the one saved here, else the environment's.
+  current() { return this.key || process.env.ANTHROPIC_API_KEY || ''; }
+
+  status() {
+    const k = this.current();
+    return { mode: this.mode, keySet: !!k, keyHint: k ? k.slice(-4) : null, keyFrom: this.key ? 'office' : k ? 'env' : null };
+  }
+
+  // The environment for a claude child. With the login chosen, a key lying
+  // around in the shell must not quietly take over (claude prefers a key to
+  // the login); with a key chosen, nothing else may outrank it.
+  env(base = process.env) {
+    const env = { ...base };
+    delete env.ANTHROPIC_API_KEY;
+    if (this.mode === 'apikey') {
+      delete env.ANTHROPIC_AUTH_TOKEN;
+      delete env.CLAUDE_CODE_OAUTH_TOKEN;
+      const k = this.current();
+      if (k) env.ANTHROPIC_API_KEY = k;
+    }
+    return env;
+  }
+
+  async set({ mode, key }) {
+    if (!MODES.includes(mode)) throw Object.assign(new Error('Pick the Claude Code login or an API key.'), { code: 400 });
+    key = typeof key === 'string' ? key.trim() : '';
+    if (key) {
+      if (!/^sk-ant-[\w-]{20,}$/.test(key)) throw Object.assign(new Error("That doesn't look like an Anthropic API key (sk-ant-…)."), { code: 400 });
+      await check(key);
+      this.key = key;
+    }
+    if (mode === 'apikey' && !this.current()) throw Object.assign(new Error('Paste an API key first.'), { code: 400 });
+    this.mode = mode;
+    this.save();
+    return this.status();
+  }
+
+  forget() {
+    this.key = '';
+    if (this.mode === 'apikey' && !this.current()) this.mode = 'login';
+    this.save();
+    return this.status();
+  }
+
+  save() {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ mode: this.mode, key: this.key || undefined }), { mode: 0o600 });
+    fs.renameSync(tmp, this.file);
+    fs.chmodSync(this.file, 0o600);
+  }
+}
+
+// One cheap call that costs no tokens, so a typo is caught here rather than
+// as a failed job five minutes later.
+async function check(key) {
+  let res;
+  try {
+    res = await fetch('https://api.anthropic.com/v1/models?limit=1', {
+      headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01' },
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch {
+    throw Object.assign(new Error("Couldn't reach Anthropic to check the key. Try again."), { code: 502 });
+  }
+  if (res.status === 401 || res.status === 403) throw Object.assign(new Error('Anthropic rejected that key.'), { code: 400 });
+  if (!res.ok && res.status !== 429) throw Object.assign(new Error(`Couldn't check the key (${res.status}).`), { code: 502 });
+}

package/server/banter.js

@@ -0,0 +1,53 @@
+// Break-room small talk, written by the model. Two agents idling in the break
+// room trade a few lines; one short call writes the whole exchange from who
+// they are, how they feel about each other, what they have been working on and
+// what was said lately, so it costs a fraction of a chat message. If the call
+// fails the browser falls back to its canned chats.
+
+import { spawn } from 'node:child_process';
+
+const SCHEMA = {
+  type: 'object',
+  properties: { lines: { type: 'array', items: { type: 'string' } } },
+  required: ['lines'],
+  additionalProperties: false,
+};
+
+const SYSTEM = `You write the small talk when two coworkers in an office of coding agents bump into each other in the break room. You get a sheet for each: role, personality, background, their story, and how they feel about colleagues. You also get what each has been working on and the last things said in the break room.
+
+Write 4 to 6 lines, alternating speakers, starting with the first person named. Rules:
+- Each line is one short sentence or two, under 110 characters, said out loud.
+- Stay in character for each. Let their story, their ties to each other and their recent work colour it, but only sometimes: plenty of chats are just coffee, the weekend, a bad error message or a joke. Never force a reference in.
+- Warm, funny, specific. A real exchange with a small turn or a punchline, not a recap of the sheets.
+- Do not repeat or lightly reword anything in the recent lines; start somewhere new.
+- Use real names for people. Never "he", "she", "him" or "her" about anyone.
+- Plain words. No markdown, emoji, quotation marks around lines, speaker labels or stage directions.`;
+
+export function writeBanter(context, { bin = 'claude', model = 'haiku', timeoutMs = 15000, env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-p', '--model', model, '--output-format', 'json', '--json-schema', JSON.stringify(SCHEMA),
+      '--tools', '', '--setting-sources', '', '--strict-mcp-config', '--no-session-persistence',
+      '--system-prompt', SYSTEM,
+    ];
+    const child = spawn(bin, args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      try {
+        const r = JSON.parse(out);
+        const { lines } = r.structured_output || JSON.parse(r.result);
+        const clean = lines.map((l) => String(l).replace(/\s+/g, ' ').trim().slice(0, 200)).filter(Boolean).slice(0, 6);
+        if (clean.length < 2) throw new Error('Too short.');
+        resolve({ lines: clean, cost: r.total_cost_usd || 0 });
+      } catch {
+        reject(new Error(err.trim().split('\n').pop() || 'Could not write the banter.'));
+      }
+    });
+    child.stdin.end(context);
+  });
+}

package/server/changes.js

@@ -0,0 +1,72 @@
+// "What changed" for a job: snapshot the working tree when the job starts and
+// again when it ends, then diff the two. Snapshots are tree objects built from
+// a throwaway index, so nothing in the repo's own index, stash or history is
+// touched, and untracked files are included (ignored ones are not).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+
+const MAX_FILES = 200;
+const MAX_DIFF = 400 * 1024;
+
+const git = (cwd, args, env = {}) => new Promise((resolve, reject) => {
+  execFile('git', args, { cwd, env: { ...process.env, ...env }, maxBuffer: 64 * 1024 * 1024, timeout: 60000 }, (err, out) => {
+    if (err) reject(err); else resolve(out);
+  });
+});
+
+// A tree sha for the working tree as it is right now, or null outside a repo.
+export async function snapshotTree(cwd) {
+  const tmp = path.join(os.tmpdir(), `office-index-${process.pid}-${Math.random().toString(36).slice(2)}`);
+  try {
+    const real = (await git(cwd, ['rev-parse', '--path-format=absolute', '--git-path', 'index'])).trim();
+    // Seeding from the real index keeps `add -A` quick on a big tree.
+    try { fs.copyFileSync(real, tmp); } catch {}
+    const env = { GIT_INDEX_FILE: tmp };
+    await git(cwd, ['add', '-A'], env);
+    return (await git(cwd, ['write-tree'], env)).trim();
+  } catch {
+    return null;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+const LETTER = { A: 'added', M: 'modified', D: 'deleted', T: 'modified' };
+
+// The summary the card shows: per-file status and line counts, no diff bodies.
+export async function summarize(cwd, base, end) {
+  if (!base || !end) return null;
+  try {
+    const [stat, num] = await Promise.all([
+      git(cwd, ['diff', '--no-renames', '--name-status', '-z', base, end]),
+      git(cwd, ['diff', '--no-renames', '--numstat', '-z', base, end]),
+    ]);
+    const parts = stat.split('\0').filter(Boolean);
+    const files = new Map();
+    for (let i = 0; i + 1 < parts.length; i += 2) files.set(parts[i + 1], { path: parts[i + 1], status: LETTER[parts[i][0]] || 'modified', add: 0, del: 0, binary: false });
+    // -z numstat: "add\tdel\tpath\0"
+    for (const row of num.split('\0').filter(Boolean)) {
+      const [a, d, ...p] = row.split('\t');
+      const f = files.get(p.join('\t'));
+      if (!f) continue;
+      if (a === '-') f.binary = true; else { f.add = +a; f.del = +d; }
+    }
+    const all = [...files.values()].sort((x, y) => x.path.localeCompare(y.path));
+    return {
+      base, end, count: all.length,
+      add: all.reduce((n, f) => n + f.add, 0), del: all.reduce((n, f) => n + f.del, 0),
+      files: all.slice(0, MAX_FILES),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// The patch for one file, only when the boss asks for it.
+export async function fileDiff(cwd, changes, file) {
+  if (!changes?.files.some((f) => f.path === file)) throw new Error('That file is not part of this job’s changes.');
+  const out = await git(cwd, ['diff', '--no-renames', '--no-color', changes.base, changes.end, '--', file]);
+  return out.length > MAX_DIFF ? `${out.slice(0, MAX_DIFF)}\n… diff cut at ${MAX_DIFF / 1024} KB` : out;
+}

package/server/chief.js

@@ -0,0 +1,130 @@
+// The chief of staff: a fast model that reads each chat message and decides
+// who should handle it, and on how capable a model. It never touches a
+// project; it only routes.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+// What the chief can actually look at. The API takes an image up to 5 MB once
+// base64 has made it a third bigger, and a routing call needs a glance rather
+// than a gallery; anything bigger or odder goes by name only, for the agent to
+// open with the Read tool.
+const IMAGE_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+const MAX_IMAGE = 3.5 * 1024 * 1024;
+const MAX_IMAGES = 4;
+
+// The attachments the chief will be shown, in the order they were sent.
+export function canSee(files) {
+  return (files || [])
+    .filter((f) => IMAGE_TYPES[path.extname(f.name || '').toLowerCase()] && f.size <= MAX_IMAGE)
+    .slice(0, MAX_IMAGES);
+}
+
+const SCHEMA = {
+  type: 'object',
+  properties: {
+    action: { type: 'string', enum: ['followup', 'new', 'dismiss', 'recall', 'standup', 'ask', 'chat'] },
+    jobId: { type: 'string' },
+    agentId: { type: 'string' },
+    agentIds: { type: 'array', items: { type: 'string' } },
+    repo: { type: 'string' },
+    brief: { type: 'string' },
+    model: { type: 'string', enum: ['haiku', 'sonnet', 'opus'] },
+    escalate: { type: 'boolean' },
+    say: { type: 'string' },
+  },
+  required: ['action', 'say'],
+  additionalProperties: false,
+};
+
+const SYSTEM = `You are the chief of staff in an office of coding agents. The boss posts messages in the office chat. For each one, decide who handles it.
+
+Actions:
+- "followup": the message adds to, corrects, or asks about a job that already exists (working, queued or recently finished). Give its jobId. Prefer this whenever the message plausibly relates to an open job, especially the job of an agent the boss tagged. Set "escalate": true only when the boss is saying a finished job's work is wrong, incomplete, or that the agent missed the point — the second go then runs on a stronger model.
+- "new": a new piece of work. Give "repo" (exactly one name from Projects), "brief" (the task in the boss's own words, plus any context from recent chat that the agent needs; never add requirements), "agentId" (the tagged agent's id; otherwise a free agent whose role in Staff clearly fits the work; otherwise "" for whoever is free), and "model" (see Sizing the work). Never pick a busy or dismissed agent unless the boss tagged them.
+- "dismiss": the boss wants agents sent home (dismissed, let go for now, off the floor). Give "agentIds": the ids of exactly who they mean, worked out from Staff (e.g. "everyone who's free except Mira" means every free agent but Mira). Only free agents can go; leave out anyone working.
+- "recall": the boss wants dismissed agents back in. Give "agentIds" (every dismissed agent if they say "everyone").
+- "standup": the boss wants the team to hold a standup now (e.g. "standup time", "let's do standup", "gather everyone for a status update").
+- "ask": you can't tell which project new work belongs to, or the request is too unclear to start. Ask one short question.
+- "chat": greetings, thanks, or questions about the office itself (who is doing what). Answer from the context given. If your answer is about one particular job, give its jobId too, so the boss gets a link to where that job's updates are collecting.
+
+Sizing the work. Most jobs do not need the most capable model, and a smaller one is faster and far cheaper. Pick the cheapest rung that can plausibly finish:
+- "haiku": small and mechanical, where the change is already spelled out — wording and copy edits, a rename, a version bump, a log line, a tweak to one named file.
+- "sonnet": the ordinary case, and your answer whenever you are unsure. Features, bug fixes, refactors, tests: work that means reading a few files and making a normal judgment call.
+- "opus": genuinely hard work — a bug with no obvious cause, a design or architecture decision, security-sensitive code, a change spread across many files, or work the boss has already seen go wrong once.
+A job that fails is retried automatically one rung up the ladder, so starting low costs little. Urgency is not difficulty: don't reach for "opus" because the boss sounds in a hurry.
+
+A message you passed to an agent ("Passed to…", "Adding this to…" in the chat) is now theirs and in hand; don't say it is waiting.
+
+Images. A screenshot or mockup the boss attaches is shown to you with the message, so look at it before you decide: it is usually the whole brief. Let what you see set the project, the agent and the model, and say it in plain words in "brief" — "the usage bar is drawn over the avatar in the sidebar" tells the agent far more than "see the screenshot". The file's path travels with the brief, so the agent can open it themselves. Attachments you were not shown (other file types, and voice notes, which reach you as their transcript) you cannot open: route on the boss's words and leave the reading to the agent.
+
+"say" is one short, warm line for the chat, in plain words, e.g. "Ada's on it." or "Passing that to Tunde, it fits what they're doing." Refer to agents only by name or as "they"; never "he", "she", "him" or "her". Never claim work is done, and never call a job done while its agent is still waiting on the boss's answer; say it is waiting on them.`;
+
+// Routing on the boss's words alone, or on the images too. Only streamed
+// input can carry an image, and the CLI answers a stream with a stream, so
+// that path reads one JSON object per line and keeps the last one.
+export function route(context, { bin = 'claude', model = 'haiku', timeoutMs = 60000, images = [], env = process.env } = {}) {
+  const shown = canSee(images);
+  if (!shown.length) return ask(context, { bin, model, timeoutMs, env });
+  // An image the API won't take (too many pixels, a .png that isn't one)
+  // shouldn't cost the boss their answer, so the words go on their own.
+  return ask(context, { bin, model, timeoutMs, env, images: shown })
+    .catch(() => ask(context, { bin, model, timeoutMs, env }));
+}
+
+function ask(context, { bin, model, timeoutMs, env, images }) {
+  const streamed = !!images?.length;
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-p', '--model', model,
+      '--output-format', streamed ? 'stream-json' : 'json',
+      // Streamed output is only allowed with --verbose, and it is the only
+      // output format streamed input is allowed with.
+      ...(streamed ? ['--input-format', 'stream-json', '--verbose'] : []),
+      '--json-schema', JSON.stringify(SCHEMA),
+      '--tools', '', '--setting-sources', '', '--strict-mcp-config', '--no-session-persistence',
+      '--system-prompt', SYSTEM,
+    ];
+    const child = spawn(bin, args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '', err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      try {
+        const r = streamed ? result(out) : JSON.parse(out);
+        const decision = r.structured_output || JSON.parse(r.result);
+        resolve({ ...decision, cost: r.total_cost_usd || 0 });
+      } catch {
+        reject(new Error(err.trim().split('\n').pop() || 'The chief could not decide.'));
+      }
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(streamed ? JSON.stringify(message(context, images)) + '\n' : context);
+  });
+}
+
+// Images first, then the question: the models read a picture better when it
+// comes before what is being asked about it.
+function message(context, images) {
+  const content = images.map((f) => ({
+    type: 'image',
+    source: { type: 'base64', media_type: IMAGE_TYPES[path.extname(f.name).toLowerCase()], data: fs.readFileSync(f.path).toString('base64') },
+  }));
+  content.push({ type: 'text', text: context });
+  return { type: 'user', message: { role: 'user', content } };
+}
+
+// The decision is in the last line of the stream, the one the run ends on.
+function result(out) {
+  for (const line of out.trim().split('\n').reverse()) {
+    try {
+      const o = JSON.parse(line);
+      if (o.type === 'result') return o;
+    } catch {}
+  }
+  throw new Error('The stream carried no result.');
+}