agent-office-studio 0.0.0-stage → 0.3.0

package/server/chief.js

@@ -0,0 +1,146 @@
+// 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));
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; 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(whyNot(out, err, streamed, timedOut, timeoutMs)));
+      }
+    });
+    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.
+// Why a routing call gave no decision, in words the boss can act on. claude
+// reports most failures (not signed in, out of credit, a model the account
+// can't use) inside its JSON on stdout with nothing on stderr, so read that
+// before falling back.
+function whyNot(out, err, streamed, timedOut, timeoutMs) {
+  if (timedOut) return `The chief took longer than ${Math.round(timeoutMs / 1000)} seconds to answer. Check that \`claude -p "hi"\` answers in a terminal.`;
+  let r = null;
+  try { r = streamed ? result(out) : JSON.parse(out); } catch {}
+  const said = String(r?.is_error ? r.result || r.subtype || '' : '').trim();
+  if (said) return `claude said: ${said.split('\n')[0].slice(0, 300)}`;
+  const last = err.trim().split('\n').pop();
+  if (last) return last.slice(0, 300);
+  return out.trim() ? 'The chief could not decide.' : 'claude exited without answering. Check that `claude -p "hi"` answers in a terminal.';
+}
+
+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.');
+}

package/server/guests.js

@@ -0,0 +1,391 @@
+// Guests: another office running jobs with our agents over a guest link, and
+// the other way round, us visiting an office that made us its guest.
+//
+// As host, everything a guest asks for comes in as a `req` frame and is
+// checked here against the limits the boss set on the invite (repos,
+// clearance cap, tokens per day). The guest's office is never trusted: it
+// only ever sees its own jobs, and the feed it gets is cut down to them.
+//
+// As guest, the browser opens /ws/visit/:link. We ask the host for a hello,
+// then pass on its feed; the composer's posts become `req` frames.
+// See docs/proposals/linked-offices.md, "Guests".
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const CLEARANCE = ['plan', 'edit', 'auto'];
+const MAX_OPEN_JOBS = 3; // queued or working, per guest
+const MAX_PROMPT = 20_000;
+const REQ_TIMEOUT_MS = 15_000;
+const CONNECT_WAIT_MS = 5_000;
+const FEED_EVERY_MS = 250;
+const FEED_BYTES = 48 * 1024; // under the relay's 64 KB a frame
+const FEED_TYPES = new Set(['job', 'log', 'staff']);
+const utcDay = (ms = Date.now()) => new Date(ms).toISOString().slice(0, 10);
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+// ---------- what a host may put on our page ----------
+//
+// As guest, everything from the host lands in our own localhost page, which
+// can start jobs on this machine. So nothing it sends is passed on as it is:
+// each message is rebuilt from known fields, text is capped, ids and colours
+// must match their patterns, enums must be ours, and anything that doesn't fit
+// is dropped.
+
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const COLOUR = /^#[0-9a-fA-F]{6}$/;
+const REPO = /^[^/\\\0<>"'`]{1,100}$/;
+const HANDLE = /^@?[a-z0-9][a-z0-9_-]{2,19}$/i;
+const STATUSES = new Set(['queued', 'working', 'done', 'failed', 'stopped']);
+const LOG_KINDS = new Set(['user', 'system', 'thinking', 'tool', 'text', 'error', 'result']);
+const STATIONS = new Set(['library', 'servers', 'window', 'whiteboard', 'desk']);
+const FILE_STATUSES = new Set(['added', 'modified', 'deleted']);
+const ASKING = new Set(['question', 'decision', 'blocker']);
+
+const str = (v, max) => (typeof v === 'string' ? v.slice(0, max) : '');
+const optStr = (v, max) => (typeof v === 'string' ? v.slice(0, max) : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const count = (v) => (Number.isInteger(v) && v >= 0 ? v : 0);
+const id = (v) => (typeof v === 'string' && ID.test(v) ? v : null);
+const bool = (v) => v === true;
+const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+export function cleanStaff(s) {
+  if (!s || typeof s !== 'object' || !id(s.id)) return null;
+  const colour = (v) => (typeof v === 'string' && COLOUR.test(v) ? v : undefined);
+  return drop({
+    id: s.id, name: str(s.name, 40) || s.id, role: str(s.role, 60),
+    shirt: colour(s.shirt), hair: colour(s.hair), skin: colour(s.skin),
+    personality: str(s.personality, 300), background: str(s.background, 300),
+  });
+}
+
+export function cleanEntry(e) {
+  if (!e || typeof e !== 'object' || !LOG_KINDS.has(e.kind)) return null;
+  return drop({
+    kind: e.kind, summary: str(e.summary, 8000), ts: num(e.ts) ?? undefined,
+    ok: e.kind === 'result' ? bool(e.ok) : undefined,
+    ms: num(e.ms) ?? undefined, cost: num(e.cost) ?? undefined,
+    station: STATIONS.has(e.station) ? e.station : undefined,
+    blocked: e.blocked === true ? true : undefined, wait: e.wait === true ? true : undefined,
+  });
+}
+
+function cleanChanges(c) {
+  if (!c || typeof c !== 'object' || !Array.isArray(c.files)) return null;
+  const sha = (v) => (typeof v === 'string' && /^[0-9a-f]{4,64}$/.test(v) ? v : null);
+  return {
+    base: sha(c.base), end: sha(c.end), count: count(c.count), add: count(c.add), del: count(c.del),
+    files: c.files.slice(0, 200).filter((f) => f && typeof f.path === 'string' && f.path && !f.path.includes('\0')).map((f) => ({
+      path: f.path.slice(0, 500), status: FILE_STATUSES.has(f.status) ? f.status : 'modified', add: count(f.add), del: count(f.del), binary: bool(f.binary),
+    })),
+  };
+}
+
+export function cleanJob(j) {
+  if (!j || typeof j !== 'object' || !id(j.id) || !STATUSES.has(j.status)) return null;
+  const from = typeof j.from === 'string' && HANDLE.test(j.from) ? j.from : undefined;
+  return drop({
+    id: j.id, repo: typeof j.repo === 'string' && REPO.test(j.repo) ? j.repo : '', title: str(j.title, 200),
+    mode: CLEARANCE.includes(j.mode) ? j.mode : 'plan', model: typeof j.model === 'string' && /^[\w.:-]{0,60}$/.test(j.model) ? j.model : '',
+    status: j.status, createdAt: num(j.createdAt), queuedAt: num(j.queuedAt), startedAt: num(j.startedAt), endedAt: num(j.endedAt),
+    agentId: id(j.agentId), turns: count(j.turns), tools: count(j.tools), context: count(j.context),
+    error: optStr(j.error, 500), waiting: bool(j.waiting), awaitingBoss: bool(j.awaitingBoss),
+    asking: j.asking && ASKING.has(j.asking.kind) ? { kind: j.asking.kind, summary: str(j.asking.summary, 500) } : null,
+    changes: cleanChanges(j.changes), from, guest: j.guest && id(j.guest.link) ? { link: j.guest.link } : undefined,
+    log: Array.isArray(j.log) ? j.log.slice(-500).map(cleanEntry).filter(Boolean) : [],
+  });
+}
+
+// One feed message, or null.
+export function cleanFeed(m) {
+  if (!m || typeof m !== 'object') return null;
+  if (m.t === 'job') { const job = cleanJob(m.job); return job && { t: 'job', job }; }
+  if (m.t === 'log') { const entry = cleanEntry(m.entry); return entry && id(m.jobId) && { t: 'log', jobId: m.jobId, entry }; }
+  if (m.t === 'staff') return Array.isArray(m.dismissed) ? { t: 'staff', dismissed: m.dismissed.filter((x) => id(x)).slice(0, 50) } : null;
+  return null;
+}
+
+// The host's answer to each request, rebuilt.
+const CLEAN_BODY = {
+  createJob: (b) => { const job = cleanJob(b.job); if (!job) throw fail(502, 'The host sent back a job that doesn’t look right.'); return { job }; },
+  job: (b) => { const job = cleanJob(b.job); if (!job) throw fail(502, 'The host sent back a job that doesn’t look right.'); return { job }; },
+  diff: (b) => ({ diff: str(b.diff, 2_000_000) }),
+  reply: () => ({ ok: true }),
+  stop: () => ({ ok: true }),
+  hello: (b) => b,
+};
+
+// What a guest may see of one of its own jobs.
+export function guestJob(j, tail = 40) {
+  const { id, repo, title, mode, model, status, createdAt, queuedAt, startedAt, endedAt, agentId, turns, tools, error, waiting, asking, awaitingBoss, changes, context, from, guest } = j;
+  return { id, repo, title, mode, model, status, createdAt, queuedAt, startedAt, endedAt, agentId, turns, tools, error, waiting, asking, awaitingBoss, changes, context, from, guest, log: (j.log || []).slice(-tail) };
+}
+
+export class Guests {
+  // office: { jobs(), createJob(body, extra), replyJob(job, body), stopJob(job), diff(job, path), staff(), modes() }
+  constructor(dataDir, { links, office }) {
+    this.links = links;
+    this.office = office;
+    this.file = path.join(dataDir, 'guests.json');
+    this.used = {};
+    try { this.used = JSON.parse(fs.readFileSync(this.file, 'utf8')).used || {}; } catch {}
+    this.queue = new Map(); // link id -> messages waiting for the next feed frame
+    this.flushTimer = null;
+    this.visits = new Map(); // link id -> Set of browser sockets (as guest)
+    this.pending = new Map(); // req id -> { resolve, reject, timer } (as guest)
+  }
+
+  // Every req, res and feed frame on a guest link comes through here.
+  onGuest(link, msg) {
+    if (link.role === 'host' && msg.t === 'req') return this.answer(link, msg);
+    if (link.role === 'guest' && msg.t === 'res') return this.settle(msg);
+    if (link.role === 'guest' && msg.t === 'feed') return this.fromHost(link, msg);
+  }
+
+  // ---------- as host ----------
+
+  policy(link) {
+    const p = this.links.guestPolicy(link.id);
+    if (!p) throw fail(403, 'This office has no guest access set up for you.');
+    return p;
+  }
+
+  tokensToday(linkId) {
+    const u = this.used[linkId];
+    return u?.day === utcDay() ? u.tokens : 0;
+  }
+
+  // The guest's own jobs, open ones only if asked.
+  jobsOf(linkId, open = false) {
+    return this.office.jobs().filter((j) => j.guest?.link === linkId && (!open || j.status === 'queued' || j.status === 'working'));
+  }
+
+  ownJob(link, id) {
+    const job = this.office.jobs().find((j) => j.id === String(id ?? '') && j.guest?.link === link.id);
+    if (!job) throw fail(404, 'No such job of yours.');
+    return job;
+  }
+
+  capMode(p, mode = 'edit') {
+    if (!CLEARANCE.includes(mode)) throw fail(400, 'Unknown mode.');
+    if (CLEARANCE.indexOf(mode) > CLEARANCE.indexOf(p.clearance)) throw fail(403, `Your host allows up to ${p.clearance === 'plan' ? 'Plan only' : 'Edit files'}.`);
+    return mode;
+  }
+
+  checkTokens(link, p) {
+    if (this.tokensToday(link.id) >= p.tokensPerDay) throw fail(429, 'You have used today’s tokens for this office. They reset at midnight UTC.');
+  }
+
+  async answer(link, msg) {
+    const id = String(msg.id ?? '').slice(0, 64);
+    const args = msg.args && typeof msg.args === 'object' ? msg.args : {};
+    let body;
+    try {
+      const p = this.policy(link);
+      body = await this.op(link, p, String(msg.op ?? ''), args);
+    } catch (err) {
+      if (!err.code) console.error('[guests] request failed', link.id, msg.op, err);
+      return this.links.send({ t: 'res', link: link.id, id, ok: false, code: err.code || 400, error: err.message });
+    }
+    this.links.send({ t: 'res', link: link.id, id, ok: true, body });
+  }
+
+  async op(link, p, op, args) {
+    switch (op) {
+      case 'hello':
+        return {
+          staff: this.office.staff(),
+          modes: Object.fromEntries(Object.entries(this.office.modes()).filter(([k]) => CLEARANCE.indexOf(k) <= CLEARANCE.indexOf(p.clearance))),
+          jobs: this.jobsOf(link.id).map((j) => guestJob(j)),
+          policy: { repos: p.repos, clearance: p.clearance, tokensPerDay: p.tokensPerDay, tokensToday: this.tokensToday(link.id) },
+        };
+      case 'createJob': {
+        if (!p.repos.includes(args.repo)) throw fail(403, 'That project isn’t shared with you.');
+        const mode = this.capMode(p, args.mode);
+        this.checkTokens(link, p);
+        if (this.jobsOf(link.id, true).length >= MAX_OPEN_JOBS) throw fail(429, `You can have ${MAX_OPEN_JOBS} jobs going at once here. Wait for one to finish.`);
+        const prompt = String(args.prompt ?? '').slice(0, MAX_PROMPT);
+        const job = this.office.createJob(
+          { repo: args.repo, prompt, mode, model: typeof args.model === 'string' ? args.model : '', agentId: typeof args.agentId === 'string' ? args.agentId : '' },
+          { from: `@${link.peer}`, guest: { link: link.id } },
+        );
+        return { job: guestJob(job) };
+      }
+      case 'reply': {
+        const job = this.ownJob(link, args.job);
+        const mode = args.mode === undefined ? undefined : this.capMode(p, args.mode);
+        this.checkTokens(link, p);
+        this.office.replyJob(job, { message: String(args.text ?? '').slice(0, MAX_PROMPT), mode });
+        return { ok: true };
+      }
+      case 'stop':
+        this.office.stopJob(this.ownJob(link, args.job));
+        return { ok: true };
+      case 'job':
+        return { job: guestJob(this.ownJob(link, args.job), 500) };
+      case 'diff':
+        return { diff: await this.office.diff(this.ownJob(link, args.job), String(args.path ?? '')) };
+      default:
+        throw fail(400, 'Guests can’t do that here.');
+    }
+  }
+
+  // Tokens a guest job used: counted against its guest, and a guest over its
+  // day's allowance has its running jobs stopped.
+  addTokens(job, n) {
+    const linkId = job.guest?.link;
+    if (!linkId || !(n > 0)) return;
+    const day = utcDay();
+    const u = this.used[linkId]?.day === day ? this.used[linkId] : { day, tokens: 0 };
+    u.tokens += n;
+    this.used[linkId] = u;
+    this.save();
+    const p = this.links.guestPolicy(linkId);
+    if (p && u.tokens >= p.tokensPerDay) {
+      for (const j of this.jobsOf(linkId, true)) this.office.stopJob(j, 'Stopped: the guest used today’s tokens.');
+    }
+  }
+
+  save() {
+    // Old days and gone links aren't worth keeping.
+    const day = utcDay();
+    for (const [id, u] of Object.entries(this.used)) if (u.day !== day) delete this.used[id];
+    try {
+      fs.mkdirSync(path.dirname(this.file), { recursive: true });
+      fs.writeFileSync(this.file + '.tmp', JSON.stringify({ used: this.used }));
+      fs.renameSync(this.file + '.tmp', this.file);
+    } catch (err) { console.error('[guests] could not save', err.message); }
+  }
+
+  // Everything the office broadcasts passes here; a guest gets only its own
+  // jobs (and staff changes), batched so a busy log stays under the relay's
+  // frame rate.
+  feed(msg) {
+    if (!FEED_TYPES.has(msg.t)) return;
+    const hosting = this.links.links.filter((l) => l.kind === 'guest' && l.role === 'host');
+    if (!hosting.length) return;
+    let linkId = null;
+    if (msg.t === 'job') linkId = msg.job?.guest?.link;
+    if (msg.t === 'log') linkId = this.office.jobs().find((j) => j.id === msg.jobId)?.guest?.link;
+    for (const l of hosting) {
+      if (msg.t !== 'staff' && l.id !== linkId) continue;
+      const out = msg.t === 'job' ? { t: 'job', job: guestJob(msg.job, 0) } : msg;
+      this.queue.set(l.id, [...(this.queue.get(l.id) || []), out]);
+    }
+    if (this.queue.size && !this.flushTimer) this.flushTimer = setTimeout(() => this.flush(), FEED_EVERY_MS);
+  }
+
+  flush() {
+    this.flushTimer = null;
+    for (const [linkId, msgs] of this.queue) {
+      let batch = [], size = 0;
+      for (const m of msgs) {
+        const n = JSON.stringify(m).length;
+        if (n > FEED_BYTES) continue; // one oversized log entry is not worth a dropped frame
+        if (size + n > FEED_BYTES) { this.links.send({ t: 'feed', link: linkId, msgs: batch }); batch = []; size = 0; }
+        batch.push(m);
+        size += n;
+      }
+      if (batch.length) this.links.send({ t: 'feed', link: linkId, msgs: batch });
+    }
+    this.queue.clear();
+  }
+
+  // The relay's list changed. A guest whose link has gone loses its running
+  // jobs at once, and anyone visiting over a gone link is sent home.
+  linksChanged() {
+    const live = new Set(this.links.links.map((l) => l.id));
+    for (const j of this.office.jobs()) {
+      if (j.guest && !live.has(j.guest.link) && (j.status === 'queued' || j.status === 'working')) this.office.stopJob(j, 'Stopped: the guest was unlinked.');
+    }
+    for (const [linkId, socks] of this.visits) {
+      if (live.has(linkId)) continue;
+      for (const ws of socks) ws.close(4404, 'This office unlinked you.');
+      this.visits.delete(linkId);
+    }
+  }
+
+  // ---------- as guest ----------
+
+  guestLink(linkId) {
+    const link = this.links.links.find((l) => l.id === linkId && l.kind === 'guest' && l.role === 'guest');
+    if (!link) throw fail(404, 'You aren’t a guest of that office.');
+    return link;
+  }
+
+  async request(linkId, op, args = {}) {
+    const link = this.guestLink(linkId);
+    // Just after linking (or a reconnect) the relay socket can still be
+    // opening; a visit started then shouldn't fail for it.
+    for (const end = Date.now() + CONNECT_WAIT_MS; !this.links.status().connected && Date.now() < end;) await new Promise((r) => setTimeout(r, 100));
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(fail(504, `@${link.peer} didn’t answer.`)); }, REQ_TIMEOUT_MS);
+      const clean = CLEAN_BODY[op] || (() => ({}));
+      this.pending.set(id, { resolve: (body) => { try { resolve(clean(body)); } catch (err) { reject(err); } }, reject, timer });
+      if (!this.links.send({ t: 'req', link: link.id, id, op, args })) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(fail(502, 'Not connected to the relay.'));
+      }
+    });
+  }
+
+  settle(msg) {
+    const p = this.pending.get(String(msg.id));
+    if (!p) return;
+    this.pending.delete(String(msg.id));
+    clearTimeout(p.timer);
+    if (msg.ok) p.resolve(msg.body && typeof msg.body === 'object' ? msg.body : {});
+    else p.reject(fail(Number.isInteger(msg.code) && msg.code >= 400 && msg.code < 600 ? msg.code : 400, typeof msg.error === 'string' && msg.error ? msg.error.slice(0, 300) : 'The host refused.'));
+  }
+
+  fromHost(link, msg) {
+    const socks = this.visits.get(link.id);
+    if (!socks?.size || !Array.isArray(msg.msgs)) return;
+    for (const raw of msg.msgs.slice(0, 500)) {
+      const m = cleanFeed(raw);
+      if (!m) continue;
+      const data = JSON.stringify(m);
+      for (const ws of socks) if (ws.readyState === 1) ws.send(data);
+    }
+  }
+
+  // The host's hello, rebuilt. Mode labels are ours, not the host's.
+  cleanHello(link, hello) {
+    const policy = hello?.policy && typeof hello.policy === 'object' ? hello.policy : {};
+    const clearance = CLEARANCE.includes(policy.clearance) ? policy.clearance : 'plan';
+    const offered = hello?.modes && typeof hello.modes === 'object' ? hello.modes : {};
+    const ours = this.office.modes();
+    return {
+      t: 'hello',
+      staff: (Array.isArray(hello?.staff) ? hello.staff : []).slice(0, 50).map(cleanStaff).filter(Boolean),
+      modes: Object.fromEntries(CLEARANCE.filter((k) => Object.hasOwn(offered, k) && CLEARANCE.indexOf(k) <= CLEARANCE.indexOf(clearance)).map((k) => [k, ours[k]])),
+      jobs: (Array.isArray(hello?.jobs) ? hello.jobs : []).slice(0, 200).map(cleanJob).filter(Boolean),
+      chat: [],
+      channels: [],
+      visiting: {
+        link: link.id, host: link.peer,
+        repos: (Array.isArray(policy.repos) ? policy.repos : []).filter((r) => typeof r === 'string' && REPO.test(r)).slice(0, 50),
+        clearance, tokensPerDay: count(policy.tokensPerDay), tokensToday: count(policy.tokensToday),
+      },
+    };
+  }
+
+  // A browser opened /ws/visit/:link. The host's hello, cut down and labelled.
+  async visit(ws, linkId, extra = () => ({})) {
+    let link;
+    try { link = this.guestLink(linkId); } catch { return ws.close(4404, 'You aren’t a guest of that office.'); }
+    const socks = this.visits.get(link.id) || new Set();
+    this.visits.set(link.id, socks);
+    socks.add(ws);
+    ws.on('close', () => { socks.delete(ws); if (!socks.size) this.visits.delete(link.id); });
+    let hello;
+    try { hello = await this.request(link.id, 'hello'); }
+    catch (err) { return ws.close(4502, String(err.message).slice(0, 120)); }
+    if (ws.readyState !== 1) return;
+    ws.send(JSON.stringify({ ...extra(), ...this.cleanHello(link, hello) }));
+  }
+}