agent-office-studio 0.0.0-stage → 0.3.0

package/docs/security.md

@@ -0,0 +1,80 @@
+# Security
+
+The office starts Claude in your projects, can give it full autonomy, and can
+hand out a shell. It is built to be used by one person, on their own machine.
+
+## Who can reach it
+
+- The server listens on `127.0.0.1` only.
+- Every request's `Host` and `Origin` must be local (or a name in
+  `OFFICE_ALLOWED_HOSTS`), which keeps other websites and DNS-rebinding
+  attacks out of it. A page on another localhost port counts as another
+  website.
+- The office has a key, made on first start and kept in `data/office-key` with
+  mode `0600`. Other accounts on the machine can reach `127.0.0.1` too, so the
+  page, the API and the socket all need the key. The address the office prints
+  when it starts carries the key once; your browser keeps it in a cookie
+  (HttpOnly, SameSite=Strict). `agentoffice --link` prints that address again.
+  Delete `data/office-key` and restart to sign every browser out.
+- Agents call back into the office (the roster, messages, hand-offs) with a
+  per-job token that dies with the job.
+
+Don't put it behind a public URL. If you reach it from your phone, do it over
+a private network that is only you — see [On your phone](phone.md).
+
+## What jobs may do
+
+Each job runs with the clearance you picked — *Plan only*, *Edit files* or
+*Full autonomy* — enforced by Claude Code's own permission modes, and leaves a
+full log in its drawer. Full autonomy means what it says: the agent can run any
+command you could.
+
+## Claude credentials
+
+- With the **Claude Code login**, the office never sees your credentials; the
+  `claude` it starts reads them. The plan meters read the login's access token
+  to ask for usage, and nothing else.
+- With an **API key**, the key is checked with Anthropic, stored in
+  `data/auth.json` with mode `0600`, passed only to the `claude` processes the
+  office starts, and never sent to the browser, which sees the last four
+  characters.
+- `data/` is git-ignored.
+
+## The leaderboard
+
+Off until you join, and then the only thing besides Claude that the office
+talks to. It sends a handle and three counters per day (jobs, tokens, agent
+time) to the hosted leaderboard service (or the one named by
+`OFFICE_LEADERBOARD_URL`), signed with a random
+secret kept in `data/leaderboard.json` (mode `0600`). Never prompts, projects,
+files, chat or cost. Details in [The leaderboard](leaderboard.md).
+
+## Linked offices and guests
+
+Off until you make or enter a code. The office only ever connects out to the
+service, so nothing listens for other offices. A link shares your agents' names,
+roles, looks and states (working, on a break and so on), and nothing else. Job
+titles stay home, since a title is the first line of a prompt;
+`OFFICE_SHARE_JOB_TITLES=1` shares them. Everything a linked office
+sends is checked and trimmed before your browser sees it.
+
+A **guest** runs jobs on your machine, on your Claude account. Everything is
+enforced on your side and the guest's office is never trusted:
+
+- only the projects you picked;
+- at or below the clearance cap you set;
+- within the tokens per day you set;
+- no terminal, settings, chat, or other people's jobs;
+- their agents can't reach your other agents;
+- their jobs don't get your MCP servers or claude.ai connectors, your
+  user-level Claude Code settings and hooks, or your Claude Code memory.
+
+Even *Edit files* can change scripts or hooks that run later, so invite only
+people you would trust with those projects. Details in
+[Linked offices](linked-offices.md).
+
+## The terminal
+
+Off unless `OFFICE_TERMINAL=1`. A session needs a single-use ticket from the
+origin-checked API, no agent can open one, and keystrokes are never logged. It
+is not a sandbox. Details in [The terminal](terminal.md).

package/docs/terminal.md

@@ -0,0 +1,46 @@
+# The terminal
+
+There is a real shell in the drawer under the office: `⌃``, or the terminal
+button in the top right. Tabs across the top, `+` opens another, and the picker
+beside it chooses which project folder the next one starts in. Drag the top
+edge to resize — the office makes room rather than hiding behind it. It is a
+proper pty, so `vim`, `top`, `git add -p`, colours and your own prompt all work
+the way they do in a terminal app.
+
+It is off until you ask for it:
+
+```bash
+OFFICE_TERMINAL=1 npm start
+```
+
+That switch exists because shell access is the one door in the building that
+doesn't care about clearance. A job runs with the mode you picked and leaves a
+log; a shell is you, with everything you can do, and no record of what it did.
+So:
+
+- **Off by default.** No flag, no terminal — the socket won't even open.
+- **This machine's browser only.** The server already refuses any request whose
+  host or origin isn't local. On top of that, a session needs a single-use
+  ticket that expires in ten seconds, and tickets are only handed out on that
+  origin-checked route — the socket accepts nothing else.
+- **Not for the staff.** No agent can open one. There's no office tool and no
+  `/api/agent` route that reaches it, and a shell never inherits the job
+  credentials the office gives its own children.
+- **Nothing is kept.** Not in `data/state.json`, not in the chat, not on the
+  main socket. Scrollback lives in the tab and dies with it. `data/terminal.log`
+  records when sessions opened and closed and in which folder — never
+  keystrokes, because a log of what you typed into a shell is a file full of
+  passwords.
+- **It tidies up.** Closing a tab hangs up the shell, a session with nothing
+  happening closes itself after 30 minutes, and there's a cap on how many can
+  be open at once.
+
+What it is *not* is a sandbox. The shell runs as you and `cd ..` walks out of
+whichever folder it started in; picking the folder is a convenience, not a
+boundary. Leave it off on any machine where "whoever has the browser" isn't
+just you.
+
+The terminal needs [`node-pty`](https://github.com/microsoft/node-pty), which
+builds natively — it's an optional dependency, so `npm install` on a machine
+without build tools still gets you the whole office, just without this. On
+macOS: `xcode-select --install`, then `npm install`.

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,67 @@
 {
   "name": "agent-office-studio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A 3D office where the staff are Claude Code agents.",
+  "license": "MIT",
+  "files": [
+    "bin",
+    "dist",
+    "server",
+    "shared",
+    "docs",
+    "!docs/proposals",
+    "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 && node scripts/guests.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,74 @@
+// "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) => {
+  // A project's own config can name commands git runs (fsmonitor, diff
+  // drivers); none of them should run just because a job ended.
+  execFile('git', ['-c', 'core.fsmonitor=false', ...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', '--no-ext-diff', '--no-textconv', changes.base, changes.end, '--', file]);
+  return out.length > MAX_DIFF ? `${out.slice(0, MAX_DIFF)}\n… diff cut at ${MAX_DIFF / 1024} KB` : out;
+}