agent-office-studio 0.8.0 → 0.9.2

package/server/links.js

@@ -26,6 +26,9 @@ const MAX_AGENTS = 16;
 const STATES = new Set(['working', 'idle', 'break', 'meeting', 'away']);
 const CODE_RE = /^[0-9A-HJKMNP-TV-Z]{8}$/;
 const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+// Ids key plain objects (saved guests, tokens used), so none may name their prototype.
+const NOT_IDS = new Set(['__proto__', 'constructor', 'prototype']);
+const isId = (v) => ID_RE.test(String(v ?? '')) && !NOT_IDS.has(String(v));
 const HEX_RE = /^#[0-9a-f]{6}$/i;
 const CLEARANCES = new Set(['plan', 'edit', 'auto']); // MODES in index.js: auto is Full autonomy
 
@@ -40,13 +43,13 @@ export function normaliseCode(code) {
 }
 
 function cleanLink(l) {
-  if (!l || !ID_RE.test(String(l.id))) return null;
+  if (!l || !isId(l.id)) return null;
   return {
     id: String(l.id),
     peer: text(l.peer, 20),
     kind: l.kind === 'guest' ? 'guest' : 'link',
     role: ['host', 'guest'].includes(l.role) ? l.role : 'peer',
-    invite: ID_RE.test(String(l.invite ?? '')) ? String(l.invite) : null,
+    invite: isId(l.invite) ? String(l.invite) : null,
     createdAt: Number.isFinite(l.createdAt) ? l.createdAt : null,
   };
 }
@@ -77,7 +80,11 @@ function cleanPolicy(guest) {
   const ourAgents = guest?.ourAgents !== false;
   const theirAgents = ['read', 'edit'].includes(guest?.theirAgents) ? guest.theirAgents : 'off';
   if (!ourAgents && theirAgents === 'off') throw fail(400, 'Let them use your agents, or let their agents work here, or both.');
-  return { repos, clearance, tokensPerDay, ourAgents, theirAgents };
+  // Which of our agents they may use. Absent (a guest made before this existed)
+  // means all of them.
+  const agents = ourAgents && Array.isArray(guest?.agents) ? [...new Set(guest.agents.map(String).filter((a) => ID_RE.test(a)))] : null;
+  if (agents && !agents.length) throw fail(400, 'Pick at least one of your agents to lend.');
+  return { repos, clearance, tokensPerDay, ourAgents, theirAgents, agents };
 }
 
 export class Links {
@@ -145,7 +152,7 @@ export class Links {
   // A guest link's limits, as the host set them. Null if this isn't one we host.
   guestPolicy(linkId) {
     const l = this.links.find((x) => x.id === linkId);
-    return l?.role === 'host' ? this.saved.guests[l.id] || null : null;
+    return l?.role === 'host' && Object.hasOwn(this.saved.guests, l.id) ? this.saved.guests[l.id] : null;
   }
 
   save() {

package/server/machine.js

@@ -0,0 +1,164 @@
+// Keeping the agents from sinking the machine they run on: how hard it is
+// swapping right now, and cleaning up what an agent left running.
+
+import os from 'node:os';
+import fs from 'node:fs';
+import { execFile } from 'node:child_process';
+import { ps, tree } from './procstat.js';
+
+// ---------- pressure ----------
+
+// Swap traffic is the signal that matters: "free memory" on macOS stays near
+// zero by design, and its memory level reads healthy while the disk thrashes.
+// Pages swapped in and out, as running totals.
+function swapPages() {
+  if (process.platform === 'linux') {
+    try {
+      const v = fs.readFileSync('/proc/vmstat', 'utf8');
+      const n = (k) => Number(v.match(new RegExp(`^${k} (\\d+)`, 'm'))?.[1] || 0);
+      return Promise.resolve({ pages: n('pswpin') + n('pswpout'), pageSize: 4096 });
+    } catch { return Promise.resolve(null); }
+  }
+  if (process.platform !== 'darwin') return Promise.resolve(null);
+  return new Promise((resolve) => {
+    execFile('/usr/bin/vm_stat', { timeout: 3000 }, (err, out) => {
+      if (err) return resolve(null);
+      const n = (k) => Number(out.match(new RegExp(`${k}:\\s+(\\d+)`))?.[1] || 0);
+      const pageSize = Number(out.match(/page size of (\d+)/)?.[1] || 16384);
+      resolve({ pages: n('Swapins') + n('Swapouts'), pageSize });
+    });
+  });
+}
+
+// Readings over the last minute or so; the rate is taken across all of them
+// so one burst doesn't hold the queue.
+const WINDOW_MS = 60_000;
+const readings = [];
+
+export async function samplePressure() {
+  const r = await swapPages();
+  if (!r) return;
+  const now = Date.now();
+  readings.push({ at: now, ...r });
+  while (readings.length > 2 && now - readings[1].at > WINDOW_MS) readings.shift();
+}
+
+// MB a second swapped over the window, or null with too little to go on.
+export function swapRate() {
+  if (readings.length < 2) return null;
+  const a = readings[0], b = readings[readings.length - 1];
+  const secs = (b.at - a.at) / 1000;
+  if (secs < 5 || b.pages < a.pages) return null;
+  return ((b.pages - a.pages) * b.pageSize) / secs / (1 << 20);
+}
+
+export function resetPressure() {
+  readings.length = 0;
+}
+
+// Above these the machine is thrashing: swap traffic of a size that stalls
+// everything, or three times more runnable work than there are cores.
+export const LIMITS = { swapMBs: 100, loadPerCore: 3 };
+
+// Why a new agent should not start now, in words for the boss, or null.
+export function overloaded() {
+  if (process.env.OFFICE_PRESSURE_CHECK === 'off') return null;
+  const swap = swapRate();
+  if (swap !== null && swap > LIMITS.swapMBs) return `the machine is swapping memory to disk (about ${Math.round(swap)} MB/s)`;
+  const cores = os.cpus().length;
+  const load = os.loadavg()[0];
+  if (load > cores * LIMITS.loadPerCore) return `the processor is overloaded (load ${load.toFixed(0)} on ${cores} cores)`;
+  return null;
+}
+
+// ---------- leftovers ----------
+
+// What each job's agent has started, from the process samples taken while it
+// works: jobId -> Map(pid -> { cmd, pgid }). Kept across the sessions of one
+// job (a cleared context or a model switch), so a dev server started before
+// the clear is still the job's.
+const started = new Map();
+// And the process groups they ran in: jobId -> Map(pgid -> leader as seen, or
+// null if it wasn't). Each command an
+// agent runs gets a group of its own, and whatever it puts in the background
+// stays in that group after the shell exits, so the group finds those too.
+const groups = new Map();
+
+export function remember(jobId, procs, root) {
+  let mine = started.get(jobId);
+  if (!mine) started.set(jobId, (mine = new Map()));
+  let gs = groups.get(jobId);
+  if (!gs) groups.set(jobId, (gs = new Map()));
+  // The agent's own group is the office's, which is nobody's to clean up.
+  const own = procs.find((p) => p.pid === root)?.pgid;
+  for (const p of procs) {
+    if (p.pid === root) continue;
+    if (!mine.has(p.pid)) mine.set(p.pid, { cmd: p.cmd, pgid: p.pgid, start: p.start });
+    if (p.pgid > 1 && p.pgid !== own && !gs.get(p.pgid)) gs.set(p.pgid, p.pid === p.pgid ? { cmd: p.cmd, start: p.start } : null);
+  }
+}
+
+// Whether a process is the job's: seen under it, or in a group it ran.
+export function startedByJob(jobId, p) {
+  if (started.get(jobId)?.get(p.pid)?.cmd === p.cmd) return true;
+  // A new group leader that merely reuses an old group's number is not.
+  return !!groups.get(jobId)?.has(p.pgid) && p.pid !== p.pgid;
+}
+
+export function forget(jobId) {
+  started.delete(jobId);
+  groups.delete(jobId);
+}
+
+const name = (cmd) => {
+  const words = String(cmd).split(/\s+/);
+  const bin = (words[0] || '').split('/').pop();
+  // "node .../vite" says less than "vite".
+  const script = /^(node|python\d?|ruby|sh|bash|zsh|npm|npx|pnpm|yarn|bun|deno)$/.test(bin) && words.slice(1).find((w) => w && !w.startsWith('-'));
+  return (script ? script.split('/').pop() : bin).slice(0, 40) || 'process';
+};
+
+// Daemons that any build or tool connects to, whoever started them. Stopping
+// one under another agent's running build fails that build, so they are only
+// stopped when nobody else is working.
+const SHARED = /GradleDaemon|KotlinCompileDaemon|GradleWrapperMain.*--daemon|\bwatchman\b|\badb\b.*(fork-server|server)/;
+
+// Stop whatever the job started that is still running, except what the agent
+// asked to keep and anything inside `live` (another agent's process tree).
+// A pid only counts if its command and start are the ones recorded, so a
+// reused pid is left alone. Returns the names of what was stopped.
+const same = (now, was) => !!now && !!was && now.cmd === was.cmd && (now.start == null || was.start == null || Math.abs(now.start - was.start) < 2000);
+export async function reap(jobId, { keep = [], live = [] } = {}) {
+  const mine = started.get(jobId);
+  const gs = groups.get(jobId) || new Map();
+  forget(jobId);
+  if (!mine?.size) return [];
+  const snap = await ps();
+  if (!snap) return [];
+  // Never the office itself or what runs it.
+  const spare = new Set();
+  for (let pid = process.pid; pid > 1 && !spare.has(pid); pid = snap.procs.get(pid)?.ppid) spare.add(pid);
+  for (const root of [...live, ...keep]) for (const p of tree(snap, root)) spare.add(p.pid);
+  const roots = [];
+  for (const [pid, was] of mine) if (same(snap.procs.get(pid), was)) roots.push(pid);
+  // A group's number can't be reused while anything is still in it, so one
+  // with no leader left is the job's. One with a leader is only if that
+  // leader is the one seen while the job worked, not a newcomer with its pid.
+  const ours = (g) => !snap.procs.has(g) || same(snap.procs.get(g), gs.get(g));
+  for (const p of snap.procs.values()) if (gs.has(p.pgid) && p.pid !== p.pgid && ours(p.pgid)) roots.push(p.pid);
+  const doomed = new Map();
+  for (const pid of roots) {
+    if (spare.has(pid)) continue;
+    for (const p of tree(snap, pid)) if (!spare.has(p.pid) && !(live.length && SHARED.test(p.cmd))) doomed.set(p.pid, p);
+  }
+  if (!doomed.size) return [];
+  for (const pid of doomed.keys()) try { process.kill(pid, 'SIGTERM'); } catch {}
+  // Whatever ignores a polite stop gets a firm one, if it is still the same process.
+  setTimeout(async () => {
+    const later = await ps();
+    for (const [pid, p] of doomed) if (same(later?.procs.get(pid), p)) try { process.kill(pid, 'SIGKILL'); } catch {}
+  }, 5000).unref();
+  return [...doomed.values()].map((p) => name(p.cmd));
+}
+
+export { name as procName };

package/server/office-mcp.js

@@ -37,7 +37,7 @@ const TOOLS = [
   },
   {
     name: 'attach_files',
-    description: 'Attach images or files (screenshots, say) to your next message to the boss: your final reply, a flag_for_boss, or a post_to_channel. Absolute paths, up to 6, 25 MB each. Nothing is sent by this call itself.',
+    description: 'Attach images or files (screenshots, say) to your next message to the boss: your final reply, a flag_for_boss, or a post_to_channel. Absolute paths, up to 6, 25 MB each. Nothing is sent by this call itself. They arrive where the boss wrote from (Telegram or the web chat; the brief and each boss message say which).',
     inputSchema: obj({ paths: names }, ['paths']),
   },
   {
@@ -50,6 +50,31 @@ const TOOLS = [
     description: 'Drop this session\'s history to cut token use, at a natural break between steps. Give notes to yourself: what is done, what is left, what you learned (files, decisions, gotchas). End your turn right after; you resume fresh from the brief and your notes. Not for the end of a job.',
     inputSchema: obj({ notes: { type: 'string' } }, ['notes']),
   },
+  {
+    name: 'heavy_work',
+    description: 'One heavy build or test run at a time on this shared laptop (Gradle, Xcode, emulator, jest or vitest across a whole app, docker build). start before it: you either get the slot or are told to end your turn and are messaged when it is yours. done straight after it ends, even if it failed.',
+    inputSchema: obj({ action: { type: 'string', enum: ['start', 'done'] }, what: { type: 'string', description: 'What you are running, like "the Android Gradle build"' } }, ['action']),
+  },
+  {
+    name: 'keep_running',
+    description: 'Keep a process you started (a dev server the boss needs to look at, say) running after this job ends; everything else you leave running is stopped then. The boss is told what was kept.',
+    inputSchema: obj({ pid: { type: 'number' }, why: { type: 'string' } }, ['pid', 'why']),
+  },
+  {
+    name: 'add_app',
+    description: 'Put an app on the boss\'s home screen, or update one (same id). An app is one self-contained HTML file in a project (inline scripts, styles and data; it runs sandboxed with no network). It opens in its own window from the icon.',
+    inputSchema: obj({
+      name: { type: 'string', description: 'What the icon says, up to 40 characters' },
+      project: { type: 'string', description: 'Project folder the file is in, per office_roster' },
+      path: { type: 'string', description: 'The HTML file, relative to the project folder' },
+      icon: { type: 'string', description: 'An emoji for the icon' },
+      color: { type: 'string', description: 'Icon tile colour, hex like #1d4ed8' },
+      description: { type: 'string', description: 'One line on what it does' },
+      id: { type: 'string', description: 'Lowercase slug; defaults from the name. Give an existing id to update that app' },
+      w: { type: 'number', description: 'Starting window width in pixels' },
+      h: { type: 'number', description: 'Starting window height in pixels' },
+    }, ['name', 'project', 'path']),
+  },
   { name: 'office_shop', description: 'Your pay so far, how pay works, and what you can buy for your desk.', inputSchema: NONE },
   {
     name: 'buy_item',

package/server/procstat.js

@@ -14,26 +14,28 @@ function cpuSeconds(s) {
   return Number(days) * 86400 + rest.split(':').reduce((a, p) => a * 60 + parseFloat(p), 0);
 }
 
-function ps() {
+export function ps() {
   return new Promise((resolve) => {
-    execFile(PS, ['-axo', 'pid=,ppid=,rss=,cputime='], { timeout: 4000, maxBuffer: 8 << 20 }, (err, out) => {
+    execFile(PS, ['-axo', 'pid=,ppid=,pgid=,rss=,cputime=,etime=,command='], { timeout: 4000, maxBuffer: 16 << 20 }, (err, out) => {
       if (err) return resolve(null);
+      const at = Date.now();
       const procs = new Map();
       const kids = new Map();
       for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)$/);
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s*(.*)$/);
         if (!m) continue;
         const pid = Number(m[1]), ppid = Number(m[2]);
-        procs.set(pid, { pid, ppid, rss: Number(m[3]) * 1024, cpu: cpuSeconds(m[4]) });
+        // start: when it began, to the second, so a reused pid can be told apart.
+        procs.set(pid, { pid, ppid, pgid: Number(m[3]), rss: Number(m[4]) * 1024, cpu: cpuSeconds(m[5]), start: at - cpuSeconds(m[6]) * 1000, cmd: m[7] });
         if (!kids.has(ppid)) kids.set(ppid, []);
         kids.get(ppid).push(pid);
       }
-      resolve({ procs, kids, at: Date.now() });
+      resolve({ procs, kids, at });
     });
   });
 }
 
-function tree(snap, root) {
+export function tree(snap, root) {
   const out = [];
   const queue = [root];
   const seen = new Set();
@@ -78,6 +80,10 @@ export async function sampleProcs(roots) {
   return by;
 }
 
+// Every process under `root` as of the last sample, for remembering what an
+// agent started so it can be cleaned up once the agent is gone.
+export const lastTree = (root) => (prev ? tree(prev, root) : []);
+
 // Starting fresh after a quiet spell: the next sample has nothing to diff
 // against, so don't report a percentage for it.
 export function resetProcs() {

package/server/settings.js

@@ -14,6 +14,7 @@ export const SETTINGS = [
 
   { key: 'tokenLimit', group: 'Agents', label: 'Token limit', kind: 'number', min: 0, max: 10_000_000, step: 10000, unit: 'tokens', hint: 'Past this much context, an agent is nudged to clear it; if it does not, the office clears it. 0 turns this off.', fallback: () => Math.max(0, parseInt(env('AGENT_CLEAR_TOKENS') ?? '150000', 10) || 0) },
   { key: 'compactPct', group: 'Agents', label: 'Compact at', kind: 'number', min: 10, max: 95, step: 5, unit: '%', hint: 'How full an agent’s context gets before Claude Code compacts it. Applies to jobs that start after you save.', fallback: () => Math.min(95, Math.max(10, parseInt(env('AGENT_COMPACT_PCT') ?? '60', 10) || 60)) },
+  { key: 'maxAgents', group: 'Agents', label: 'Agents working at once', kind: 'number', min: 0, max: 50, step: 1, unit: 'agents', hint: 'More jobs than this wait in the queue, and you are told why. Jobs also wait while the machine is swapping or overloaded. 0 turns the limit off.', fallback: () => Math.max(0, parseInt(env('OFFICE_MAX_AGENTS') ?? '4', 10) || 0) },
   { key: 'chiefModel', group: 'Agents', label: 'Chief of staff model', kind: 'choice', options: ['haiku', 'sonnet', 'opus'], hint: 'Routes your messages and writes the standup.', fallback: () => env('CHIEF_MODEL') || 'sonnet' },
 
   { key: 'payPerMinute', group: 'Pay', label: 'Pay per active minute', kind: 'number', min: 0, max: 1_000_000, step: 100, unit: 'naira', hint: 'What an agent earns for each minute the model was working, on Opus. Haiku pays 3×, Sonnet 1.75×. Applies to work paid from now on.', fallback: () => 1000 },
@@ -22,6 +23,7 @@ export const SETTINGS = [
   { key: 'standupAt', group: 'Standup', label: 'Standup time', kind: 'time', hint: 'Local time, 24-hour. Blank turns the daily standup off.', fallback: () => (env('STANDUP_AT') ?? '09:30') === 'off' ? '' : (env('STANDUP_AT') ?? '09:30') },
   { key: 'standupWeekends', group: 'Standup', label: 'Hold standups on weekends', kind: 'bool', fallback: () => env('STANDUP_WEEKENDS') === '1' },
 
+  { key: 'breakRoom', group: 'Break room', label: 'Break-room chatter and pool', kind: 'bool', hint: 'Off: idle agents just wait, with no small talk or pool games, and nothing is posted to #chill-room.', fallback: () => env('BREAK_ROOM') === 'on' || env('BREAK_ROOM') === '1' },
   { key: 'banter', group: 'Break room', label: 'Written break-room talk', kind: 'bool', hint: 'Off: the break room uses canned lines only.', fallback: () => on(env('BANTER')) },
   { key: 'banterModel', group: 'Break room', label: 'Break-room model', kind: 'choice', options: ['haiku', 'sonnet', 'opus'], fallback: () => env('BANTER_MODEL') || 'haiku' },
   { key: 'banterGap', group: 'Break room', label: 'Time between conversations', kind: 'number', min: 10, max: 86400, step: 10, unit: 'seconds', hint: 'At most one written conversation per this long.', fallback: () => Math.max(10, Number(env('BANTER_GAP_SECONDS') ?? 120) || 120) },

package/server/telegram.js

@@ -0,0 +1,320 @@
+// Telegram: the boss talks to the office from their phone, and hears back.
+//
+// A bot the boss makes with @BotFather. The office long-polls Telegram for
+// the bot's messages (getUpdates), so it only ever dials out: no tunnel, no
+// webhook, nothing listening. Off until the boss turns it on in the office.
+//
+// Exactly one Telegram account may use it. Pairing proves which one: the
+// office shows a one-time code (in the office only, never in Telegram), and
+// whoever sends `/pair <code>` to the bot in a private chat becomes the owner.
+// From then on anything from any other account or chat is dropped unread and
+// logged; nobody else can talk to the bot, see replies, or pair over it.
+//
+// The token and the owner's id live in DATA/telegram.json (0600), never in
+// state.json or the chat, so they don't travel with the office's history.
+// Not read from the environment on purpose: test servers inherit that, and
+// would steal the bot's messages and text the boss their test chatter.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const API = 'https://api.telegram.org';
+const TOKEN_RE = /^\d{5,15}:[A-Za-z0-9_-]{30,60}$/;
+const PAIR_TTL_MS = 15 * 60 * 1000;
+const MAX_PAIR_TRIES = 5;
+const HINT_GAP_MS = 10 * 60 * 1000; // how often an unpaired bot says how to pair
+const MAX_TEXT = 4000; // Telegram allows 4096
+const MAX_MAP = 500; // Telegram message id → office thread, for replies
+const MAX_CAPTION = 1000; // Telegram allows 1024
+const MAX_SEND_BYTES = 50 * 1024 * 1024; // what a bot may upload
+const MAX_PHOTO_BYTES = 10 * 1024 * 1024; // bigger photos go as files
+const MAX_FETCH_BYTES = 20 * 1024 * 1024; // what a bot may download
+
+// How a file goes out, by its extension: Telegram shows photos and videos
+// inline, and anything else as a file to download.
+const KIND = {
+  '.png': 'photo', '.jpg': 'photo', '.jpeg': 'photo', '.webp': 'photo',
+  '.gif': 'animation',
+  '.mp4': 'video', '.mov': 'video', '.m4v': 'video',
+  '.m4a': 'audio', '.mp3': 'audio', '.ogg': 'audio', '.oga': 'audio', '.opus': 'audio', '.wav': 'audio', '.aac': 'audio', '.flac': 'audio',
+};
+const METHOD = { photo: 'sendPhoto', animation: 'sendAnimation', video: 'sendVideo', audio: 'sendAudio', document: 'sendDocument' };
+
+const log = (...a) => console.log('[telegram]', ...a);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// The office writes **bold**; sent as plain text, so drop the markers rather
+// than risk Telegram rejecting a message over unbalanced markup.
+export function plain(text) {
+  return String(text || '').replace(/\*\*(.+?)\*\*/gs, '$1').replace(/`{3}\w*\n?/g, '').trim();
+}
+
+export function clipText(text) {
+  return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 40).trimEnd()}\n\n… (cut short: open the office for the rest)` : text;
+}
+
+export class Telegram {
+  // onMessage({ text, files, replyTo }) hands the boss's words to the office;
+  // files are upload ids, replyTo the office thread their Telegram reply
+  // points at, if any. saveUpload(name, buffer) keeps a file the boss sent
+  // and returns its upload id. onNotice(text) tells the boss something in the
+  // office itself.
+  constructor({ dataDir, onMessage, saveUpload = () => null, onNotice = () => {}, fetchImpl = fetch, api = API }) {
+    Object.assign(this, { onMessage, saveUpload, onNotice, fetch: fetchImpl, api });
+    this.file = path.join(dataDir, 'telegram.json');
+    this.cfg = this.read();
+    this.pairing = null; // { code, until, tries }
+    this.offset = 0;
+    this.map = new Map();
+    this.outbox = Promise.resolve();
+    this.running = false;
+    this.bot = null; // @username, once getMe has answered
+    this.error = null;
+  }
+
+  read() {
+    try { return JSON.parse(fs.readFileSync(this.file, 'utf8')); } catch { return {}; }
+  }
+
+  write() {
+    const tmp = `${this.file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(this.cfg), { mode: 0o600 });
+    fs.renameSync(tmp, this.file);
+  }
+
+  get paired() { return !!(this.cfg.token && this.cfg.owner); }
+
+  status() {
+    return { on: !!this.cfg.token, paired: this.paired, bot: this.bot, error: this.error };
+  }
+
+  start() {
+    if (!this.cfg.token || this.running) return;
+    this.running = true;
+    this.loop().catch((err) => { log('poller stopped:', err.message); this.running = false; });
+  }
+
+  stop() { this.running = false; this.abort?.abort(); }
+
+  // `/telegram <token>` in the office. Checks the token with Telegram before
+  // keeping it, then hands back a pairing code for the boss to send the bot.
+  async connect(token) {
+    token = String(token || '').trim();
+    if (!TOKEN_RE.test(token)) throw new Error('That does not look like a bot token. It comes from @BotFather and looks like 123456789:AAH…');
+    const me = await this.call('getMe', {}, token);
+    this.stop();
+    await sleep(50);
+    this.cfg = { token };
+    this.write();
+    this.bot = me.username;
+    this.error = null;
+    this.offset = 0;
+    this.start();
+    log(`connected as @${me.username}; waiting to be paired`);
+    return { bot: me.username, code: this.newPairing() };
+  }
+
+  newPairing() {
+    const code = String(crypto.randomInt(100000, 1000000));
+    this.pairing = { code, until: Date.now() + PAIR_TTL_MS, tries: 0 };
+    return code;
+  }
+
+  disconnect() {
+    this.stop();
+    this.cfg = {};
+    this.pairing = null;
+    this.bot = null;
+    try { fs.rmSync(this.file, { force: true }); } catch {}
+    log('disconnected; token and owner forgotten');
+  }
+
+  async call(method, body, token = this.cfg.token, signal) {
+    const form = body instanceof FormData;
+    const res = await this.fetch(`${this.api}/bot${token}/${method}`, {
+      method: 'POST', ...(!form && { headers: { 'content-type': 'application/json' } }), body: form ? body : JSON.stringify(body), signal,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!data.ok) {
+      const err = new Error(data.description || `Telegram answered ${res.status}`);
+      err.status = res.status;
+      err.retryAfter = data.parameters?.retry_after;
+      throw err;
+    }
+    return data.result;
+  }
+
+  async loop() {
+    let backoff = 1000;
+    if (!this.bot) try { this.bot = (await this.call('getMe', {})).username; } catch {}
+    while (this.running) {
+      try {
+        this.abort = new AbortController();
+        const updates = await this.call('getUpdates', { offset: this.offset, timeout: 50, allowed_updates: ['message'] }, this.cfg.token, this.abort.signal);
+        backoff = 1000;
+        this.error = null;
+        for (const u of updates) {
+          this.offset = u.update_id + 1;
+          try { await this.handle(u.message); } catch (err) { log('could not handle a message:', err.message); }
+        }
+      } catch (err) {
+        if (!this.running) break;
+        if (err.status === 401 || err.status === 404) {
+          this.error = 'Telegram no longer accepts the bot token. Run /telegram with a new one.';
+          log(this.error);
+          this.running = false;
+          this.onNotice(this.error);
+          break;
+        }
+        // 409: another copy of this bot is polling (a second office). Back off.
+        log(`poll failed (${err.status || err.name}): ${err.message}; retrying in ${backoff / 1000}s`);
+        await sleep(err.retryAfter ? err.retryAfter * 1000 : backoff);
+        backoff = Math.min(backoff * 2, 60_000);
+      }
+    }
+  }
+
+  async handle(m) {
+    if (!m?.from || !m.chat) return;
+    const who = `${m.from.id}${m.from.username ? ` (@${m.from.username})` : ''}`;
+    const text = String(m.text ?? m.caption ?? '').trim();
+    // Only private chats: in a group, others would read the replies.
+    if (m.chat.type !== 'private') { log(`ignored a message from ${who} in a ${m.chat.type} chat`); return; }
+
+    if (!this.cfg.owner) {
+      // Nothing is downloaded or passed to the office before pairing; the
+      // only answer is how to pair, at most once a while per account.
+      const pair = /^\/pair(?:@\w+)?\s+(\d{6})$/.exec(text);
+      const p = this.pairing;
+      if (!pair || !p || Date.now() > p.until || p.tries >= MAX_PAIR_TRIES) {
+        log(`unpaired bot: ignored a message from ${who}`);
+        const last = (this.hinted ||= new Map()).get(m.from.id) || 0;
+        if (Date.now() - last > HINT_GAP_MS) {
+          this.hinted.set(m.from.id, Date.now());
+          await this.call('sendMessage', { chat_id: m.chat.id, text: 'This bot is not paired yet. In the office, type /telegram pair to get a code, then send it here as /pair 123456.' }).catch((err) => log(`hint failed: ${err.message}`));
+        }
+        return;
+      }
+      if (pair[1] !== p.code) {
+        p.tries++;
+        log(`wrong pairing code from ${who} (${p.tries}/${MAX_PAIR_TRIES})`);
+        if (p.tries >= MAX_PAIR_TRIES) this.onNotice('Too many wrong Telegram pairing codes; that code is void. Run /telegram pair for a new one.');
+        return;
+      }
+      this.cfg.owner = m.from.id;
+      this.cfg.chat = m.chat.id;
+      this.pairing = null;
+      this.write();
+      log(`paired with ${who}`);
+      this.onNotice(`Telegram is paired with ${m.from.username ? `@${m.from.username}` : 'your account'}. Only that account can use the bot.`);
+      await this.send('Paired. Message me here and it goes to the office; replies, finished jobs and anything an agent flags for you come back here. Reply to a message to answer in its thread. Reply /grant to a blocked job to give it full autonomy (or send /grant all for every blocked job), or start a request with /auto to run it at full autonomy.');
+      return;
+    }
+
+    if (m.from.id !== this.cfg.owner) { log(`dropped a message from ${who}: not the owner`); return; }
+    this.cfg.chat ??= m.chat.id;
+    const media = m.photo?.at(-1) || m.video || m.animation || m.document || m.voice || m.video_note || m.audio;
+    let files = [];
+    if (media) {
+      try { files = [await this.fetchFile(media, m)]; } catch (err) {
+        log(`could not fetch a file from the boss: ${err.message}`);
+        await this.send(`I couldn't bring that file in: ${err.message}`);
+        if (!text) return;
+      }
+    }
+    if (!text && !files.length) { await this.send('That kind of message doesn\'t get through. Text, photos, videos, voice notes and files do.'); return; }
+    if (/^\/start\b/.test(text)) { await this.send('You are paired. Write here and it goes to the office.'); return; }
+    if (/^\/telegram\b/i.test(text)) { await this.send('Telegram settings change from the office itself, not from here.'); return; }
+    const replyTo = m.reply_to_message && this.map.get(m.reply_to_message.message_id);
+    log(`from the boss${replyTo ? ` (reply in ${replyTo})` : ''}: ${text.length} chars${files.length ? `, ${files.length} file` : ''}`);
+    this.onMessage({ text, files, replyTo });
+  }
+
+  // A file the boss sent, downloaded into the office's uploads.
+  async fetchFile(media, m) {
+    if (media.file_size > MAX_FETCH_BYTES) throw new Error('it is over 20 MB, the most a bot can download. Send it through the office instead.');
+    const info = await this.call('getFile', { file_id: media.file_id });
+    const res = await this.fetch(`${this.api}/file/bot${this.cfg.token}/${info.file_path}`);
+    if (!res.ok) throw new Error(`Telegram answered ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const fromPath = path.basename(info.file_path || '');
+    const name = media.file_name || (m.photo ? `photo-${m.message_id}.jpg` : fromPath || `file-${m.message_id}`);
+    const id = this.saveUpload(name, buf);
+    if (!id) throw new Error('the office could not keep it (over 25 MB?)');
+    return id;
+  }
+
+  // An office attachment, to the owner. Photos and videos show inline; too big
+  // for that, or a type Telegram rejects, and it goes as a plain file.
+  sendFile(file, { name, caption, thread } = {}) {
+    if (!this.paired || !this.cfg.chat) return Promise.resolve();
+    name ||= path.basename(file);
+    const go = async () => {
+      let size;
+      try { size = fs.statSync(file).size; } catch { log(`send file: ${name} is gone`); return; }
+      if (size > MAX_SEND_BYTES) { await this.sendNow(`(${name} is over 50 MB, too big for Telegram: open the office to get it.)`, thread); return; }
+      let kind = KIND[path.extname(name).toLowerCase()] || 'document';
+      if (kind === 'photo' && size > MAX_PHOTO_BYTES) kind = 'document';
+      for (const k of kind === 'document' ? ['document'] : [kind, 'document']) {
+        for (let attempt = 0; attempt < 3; attempt++) {
+          try {
+            const form = new FormData();
+            form.append('chat_id', String(this.cfg.chat));
+            if (caption) form.append('caption', clipText(plain(caption)).slice(0, MAX_CAPTION));
+            if (k === 'video') form.append('supports_streaming', 'true');
+            form.append(k, await fs.openAsBlob(file), name);
+            const sent = await this.call(METHOD[k], form);
+            this.remember(sent, thread);
+            log(`sent ${name} as ${k} (${Math.round(size / 1024)} KB)`);
+            return;
+          } catch (err) {
+            if (err.status === 429 || !err.status || err.status >= 500) {
+              log(`send ${name} failed (${err.status || err.message}); retry ${attempt + 1}`);
+              await sleep(err.retryAfter ? err.retryAfter * 1000 : 2000 * (attempt + 1));
+              continue;
+            }
+            log(`send ${name} as ${k} refused: ${err.message}`);
+            break; // try it as a plain file next
+          }
+        }
+      }
+      log(`send ${name} given up`);
+    };
+    this.outbox = this.outbox.then(go, go);
+    return this.outbox;
+  }
+
+  remember(sent, thread) {
+    if (!thread || !sent?.message_id) return;
+    this.map.set(sent.message_id, thread);
+    if (this.map.size > MAX_MAP) this.map.delete(this.map.keys().next().value);
+  }
+
+  async sendNow(text, thread) {
+    try { this.remember(await this.call('sendMessage', { chat_id: this.cfg.chat, text, disable_web_page_preview: true }), thread); } catch (err) { log(`send failed: ${err.message}`); }
+  }
+
+  // Sends to the owner, one at a time so order holds, waiting out rate limits.
+  // `thread` is the office thread this belongs to, so a reply finds it.
+  send(text, thread) {
+    if (!this.paired || !this.cfg.chat) return Promise.resolve();
+    text = clipText(plain(text));
+    if (!text) return Promise.resolve();
+    const go = async () => {
+      for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+          this.remember(await this.call('sendMessage', { chat_id: this.cfg.chat, text, disable_web_page_preview: true }), thread);
+          return;
+        } catch (err) {
+          if (err.status && err.status < 500 && err.status !== 429) { log(`send failed: ${err.message}`); return; }
+          log(`send failed (${err.status || err.message}); retry ${attempt + 1}`);
+          await sleep(err.retryAfter ? err.retryAfter * 1000 : 2000 * (attempt + 1));
+        }
+      }
+      log('send given up after 4 tries');
+    };
+    this.outbox = this.outbox.then(go, go);
+    return this.outbox;
+  }
+}