agent-office-studio 0.0.0-stage → 0.2.0

package/server/leaderboard.js

@@ -0,0 +1,190 @@
+// The leaderboard, from this machine's side.
+//
+// Two things live here. The ledger always runs: per UTC day, how many jobs
+// finished, how many tokens were used and how long the agents spent working, kept in data/activity.json so it
+// survives clearing the job list. Sharing is separate and off until the boss
+// joins: then the last two weeks of those counters, under a claimed handle,
+// go to the leaderboard service. Nothing else is ever sent, no prompts, repos,
+// file names, chat or cost. See docs/leaderboard.md.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Where the hosted service lives. OFFICE_LEADERBOARD_URL overrides it.
+const DEFAULT_URL = '';
+const WINDOW_DAYS = 14;
+const DEBOUNCE_MS = 45 * 1000;
+const RETRY_MS = 10 * 60 * 1000;
+const HANDLE_RE = /^[a-z0-9][a-z0-9_-]{2,19}$/i;
+
+const utcDay = (ms = Date.now()) => new Date(ms).toISOString().slice(0, 10);
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+function writeAtomic(file, data, mode) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(data), { mode });
+  fs.renameSync(tmp, file);
+}
+
+export class Leaderboard {
+  constructor(dataDir, { onChange = () => {} } = {}) {
+    this.ledgerFile = path.join(dataDir, 'activity.json');
+    this.idFile = path.join(dataDir, 'leaderboard.json');
+    this.onChange = onChange;
+    this.days = {};
+    try { this.days = JSON.parse(fs.readFileSync(this.ledgerFile, 'utf8')).days || {}; } catch {}
+    this.me = {};
+    try { this.me = JSON.parse(fs.readFileSync(this.idFile, 'utf8')); } catch {}
+    this.error = null;
+    this.lastSync = this.me.lastSync || 0;
+    this.dirty = !!this.me.secret;
+    this.timer = null;
+    this.saveTimer = null;
+    this.busy = false;
+    if (this.dirty) this.later(15 * 1000);
+  }
+
+  get url() { return (process.env.OFFICE_LEADERBOARD_URL || DEFAULT_URL).replace(/\/+$/, ''); }
+  get joined() { return !!(this.me.secret && this.me.handle); }
+
+  status() {
+    return {
+      configured: !!this.url,
+      joined: this.joined,
+      handle: this.me.handle || null,
+      lastSync: this.lastSync || null,
+      error: this.error,
+      today: this.total(1),
+      week: this.total(7),
+    };
+  }
+
+  // Counters over the last `n` UTC days, today included.
+  total(n) {
+    const out = { jobs: 0, tokens: 0, seconds: 0, activeDays: 0 };
+    for (let i = 0; i < n; i++) {
+      const d = this.days[utcDay(Date.now() - i * 86_400_000)];
+      if (!d) continue;
+      out.jobs += d.jobs;
+      out.tokens += d.tokens;
+      out.seconds += Math.round(d.seconds || 0);
+      if (d.jobs > 0) out.activeDays++;
+    }
+    return out;
+  }
+
+  // ---------- the ledger ----------
+
+  bump(field, n) {
+    if (!(n > 0)) return;
+    const key = utcDay();
+    const d = (this.days[key] ||= { jobs: 0, tokens: 0, seconds: 0 });
+    d[field] ||= 0;
+    d[field] += n; // seconds stay fractional so short turns add up; they are rounded on the way out
+    clearTimeout(this.saveTimer);
+    this.saveTimer = setTimeout(() => this.flush(), 2000);
+    if (this.joined) { this.dirty = true; this.later(DEBOUNCE_MS); }
+  }
+  // Input plus output tokens. Cached context is left out: it is the same
+  // tokens read again, and counting it would only reward long sessions.
+  addTokens(n) { this.bump('tokens', n); }
+  addJob() { this.bump('jobs', 1); }
+  // Agent time: the time agents spent on turns, summed. Two agents working
+  // side by side for an hour is two hours; waiting on someone isn't counted.
+  addTime(ms) { this.bump('seconds', ms / 1000); }
+
+  flush() {
+    clearTimeout(this.saveTimer);
+    writeAtomic(this.ledgerFile, { days: this.days });
+  }
+
+  // ---------- sharing ----------
+
+  later(ms) {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.sync().catch(() => {}), ms);
+    this.timer.unref?.();
+  }
+
+  async call(method, route, { body, secret = this.me.secret } = {}) {
+    if (!this.url) throw fail(400, 'No leaderboard is set up for this office yet. Set OFFICE_LEADERBOARD_URL.');
+    if (!/^https:\/\//.test(this.url) && !/^http:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(this.url)) throw fail(400, 'The leaderboard address must be https.');
+    let res;
+    try {
+      res = await fetch(this.url + route, {
+        method,
+        headers: { 'content-type': 'application/json', ...(secret ? { authorization: `Bearer ${secret}` } : {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(10000),
+      });
+    } catch {
+      throw fail(502, 'Couldn’t reach the leaderboard.');
+    }
+    const out = await res.json().catch(() => ({}));
+    if (!res.ok) throw fail(res.status, out.error || `The leaderboard answered ${res.status}.`);
+    return out;
+  }
+
+  async join(handle) {
+    handle = String(handle ?? '').trim();
+    if (!HANDLE_RE.test(handle)) throw fail(400, 'A handle is 3 to 20 letters, numbers, - or _.');
+    // A secret made once and kept: if the answer to a claim is lost, asking
+    // again with the same secret is safe.
+    const secret = this.me.secret || crypto.randomBytes(32).toString('hex');
+    const out = await this.call('POST', '/v1/claim', { body: { handle }, secret });
+    this.me = { ...this.me, secret, handle: out.handle, lastSync: 0 };
+    writeAtomic(this.idFile, this.me, 0o600);
+    this.error = null;
+    this.dirty = true;
+    this.later(500);
+    return this.status();
+  }
+
+  async sync() {
+    if (!this.joined || !this.dirty || this.busy) return;
+    this.busy = true;
+    try {
+      const since = utcDay(Date.now() - WINDOW_DAYS * 86_400_000);
+      const days = Object.entries(this.days)
+        .filter(([day]) => day >= since)
+        .map(([day, d]) => ({ day, jobs: d.jobs, tokens: d.tokens, seconds: Math.round(d.seconds || 0) }));
+      if (days.length) await this.call('PUT', '/v1/days', { body: { days } });
+      this.dirty = false;
+      this.error = null;
+      this.lastSync = Date.now();
+      this.me.lastSync = this.lastSync;
+      writeAtomic(this.idFile, this.me, 0o600);
+    } catch (err) {
+      this.error = err.message;
+      // Too fast or the network is down: try again in a while. A refusal that
+      // won't change (401) is left for the boss to see rather than hammered.
+      if (err.code !== 401 && err.code !== 400) this.later(err.code === 429 ? DEBOUNCE_MS : RETRY_MS);
+    } finally {
+      this.busy = false;
+      this.onChange();
+    }
+  }
+
+  // Stops sharing and asks the service to forget this office. If it can't be
+  // reached nothing local changes, so the boss can try again rather than be
+  // left believing it is gone.
+  async leave() {
+    if (this.joined) {
+      try { await this.call('DELETE', '/v1/me'); }
+      catch (err) { if (err.code !== 401) throw err; } // 401: the service has already forgotten it
+    }
+    clearTimeout(this.timer);
+    this.me = {};
+    try { fs.rmSync(this.idFile, { force: true }); } catch {}
+    this.dirty = false;
+    this.error = null;
+    this.lastSync = 0;
+    return this.status();
+  }
+
+  async board(period) {
+    return this.call('GET', `/v1/board?period=${period === 'all' ? 'all' : 'week'}`, { secret: null });
+  }
+}

package/server/office-mcp.js

@@ -0,0 +1,101 @@
+// A tiny MCP server (stdio, JSON-RPC) that gives an agent the office: who's
+// around, messaging colleagues, handing work off, and the chat channels. It
+// just relays to the office server, which knows which job is calling from
+// OFFICE_JOB/OFFICE_TOKEN.
+
+import readline from 'node:readline';
+
+const URL_BASE = process.env.OFFICE_URL || 'http://127.0.0.1:4317';
+const JOB = process.env.OFFICE_JOB;
+const TOKEN = process.env.OFFICE_TOKEN;
+
+const NONE = { type: 'object', properties: {}, additionalProperties: false };
+const obj = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const names = { type: 'array', items: { type: 'string' } };
+
+const TOOLS = [
+  { name: 'office_roster', description: 'Who is in the office and what each is working on, or free.', inputSchema: NONE },
+  {
+    name: 'message_colleague',
+    description: 'Short message to a colleague. Reaches them mid-task, or reopens their last job if finished within hours. wait_for_reply pauses you until they answer (10 min max); use only when blocked.',
+    inputSchema: obj({ to: { type: 'string' }, message: { type: 'string' }, wait_for_reply: { type: 'boolean' } }, ['to', 'message']),
+  },
+  {
+    name: 'hand_off',
+    description: 'Give work to a free colleague, in this or another project. Their answer returns as a message. wait=false to carry on meanwhile. Fails if nobody is free.',
+    inputSchema: obj({
+      project: { type: 'string', description: 'Folder name, per office_roster' },
+      brief: { type: 'string', description: 'Everything they need, self-contained' },
+      to: { type: 'string', description: 'Omit for whoever is free' },
+      wait: { type: 'boolean' },
+    }, ['project', 'brief']),
+  },
+  {
+    name: 'flag_for_boss',
+    description: 'Surface something in the main chat for the boss: a question, decision, blocker, or work ready to review. Not for routine progress. One or two self-contained sentences.',
+    inputSchema: obj({ kind: { type: 'string', enum: ['question', 'decision', 'blocker', 'review'] }, summary: { type: 'string' } }, ['kind', 'summary']),
+  },
+  {
+    name: 'restart_office',
+    description: 'Restart the office server so changes to its own code (agent-office/server) take effect. Waits until nobody is mid-turn, so end your turn right after; you are messaged when it is back. Not needed for web changes: a build is enough.',
+    inputSchema: obj({ now: { type: 'boolean', description: 'Skip the wait and interrupt anyone mid-turn. Only if asked to.' } }, []),
+  },
+  { name: 'list_channels', description: 'List chat channels: purpose, members, and which one your work is in.', inputSchema: NONE },
+  {
+    name: 'create_channel',
+    description: 'Open a channel for a distinct strand of work (release, incident, long project) and invite colleagues. Everyday talk stays in #general.',
+    inputSchema: obj({ name: { type: 'string' }, purpose: { type: 'string' }, invite: names }, ['name']),
+  },
+  {
+    name: 'invite_to_channel',
+    description: 'Add colleagues to a channel; they see it from now on, not earlier history.',
+    inputSchema: obj({ channel: { type: 'string' }, who: names }, ['channel', 'who']),
+  },
+  {
+    name: 'post_to_channel',
+    description: 'Say something to everyone in a channel (you join it). Working members get it at once. For one person use message_colleague.',
+    inputSchema: obj({ channel: { type: 'string' }, message: { type: 'string' } }, ['channel', 'message']),
+  },
+];
+
+const out = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
+
+async function call(name, args) {
+  const res = await fetch(`${URL_BASE}/api/agent/${name}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-office-job': JOB, 'x-office-token': TOKEN },
+    body: JSON.stringify(args || {}),
+  });
+  const data = await res.json().catch(() => ({}));
+  return { text: data.text || data.error || `Office error ${res.status}`, isError: !res.ok };
+}
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  const { id, method, params } = msg;
+  if (id === undefined) return; // notifications need no answer
+  try {
+    if (method === 'initialize') {
+      out({ jsonrpc: '2.0', id, result: {
+        protocolVersion: params?.protocolVersion || '2025-06-18',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'office', version: '1.0.0' },
+      } });
+    } else if (method === 'tools/list') {
+      out({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
+    } else if (method === 'tools/call') {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) throw new Error(`Unknown tool ${params?.name}`);
+      const r = await call(tool.name, params.arguments);
+      out({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: r.text }], isError: r.isError } });
+    } else if (method === 'ping') {
+      out({ jsonrpc: '2.0', id, result: {} });
+    } else {
+      out({ jsonrpc: '2.0', id, error: { code: -32601, message: `No method ${method}` } });
+    }
+  } catch (err) {
+    out({ jsonrpc: '2.0', id, error: { code: -32000, message: err.message } });
+  }
+});

package/server/procstat.js

@@ -0,0 +1,85 @@
+// What each agent is costing this machine: CPU and memory for the whole
+// process tree under its `claude` process — the agent itself, its MCP
+// servers, and anything a tool it ran is still doing.
+
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+
+// The user's PATH may shadow ps with something else; ask for the real one.
+const PS = '/bin/ps';
+
+// "45:01.95", "1:02:03.45" and "2-01:02:03" all mean seconds here.
+function cpuSeconds(s) {
+  const [days, rest] = s.includes('-') ? s.split('-') : [0, s];
+  return Number(days) * 86400 + rest.split(':').reduce((a, p) => a * 60 + parseFloat(p), 0);
+}
+
+function ps() {
+  return new Promise((resolve) => {
+    execFile(PS, ['-axo', 'pid=,ppid=,rss=,cputime='], { timeout: 4000, maxBuffer: 8 << 20 }, (err, out) => {
+      if (err) return resolve(null);
+      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+)$/);
+        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]) });
+        if (!kids.has(ppid)) kids.set(ppid, []);
+        kids.get(ppid).push(pid);
+      }
+      resolve({ procs, kids, at: Date.now() });
+    });
+  });
+}
+
+function tree(snap, root) {
+  const out = [];
+  const queue = [root];
+  const seen = new Set();
+  while (queue.length) {
+    const pid = queue.pop();
+    if (seen.has(pid) || !snap.procs.has(pid)) continue;
+    seen.add(pid);
+    out.push(snap.procs.get(pid));
+    for (const kid of snap.kids.get(pid) || []) queue.push(kid);
+  }
+  return out;
+}
+
+// ps reports CPU time since the process started, so a percentage only exists
+// between two samples: busy seconds over wall-clock seconds, per core.
+let prev = null;
+
+export const machine = { cores: os.cpus().length, mem: os.totalmem() };
+
+export async function sampleProcs(roots) {
+  const snap = await ps();
+  if (!snap) { prev = null; return null; }
+  const span = prev ? (snap.at - prev.at) / 1000 : 0;
+  const by = {};
+  for (const [key, pid] of roots) {
+    const procs = tree(snap, pid);
+    if (!procs.length) continue;
+    const busy = procs.reduce((a, p) => {
+      const was = prev?.procs.get(p.pid);
+      // A process that started since the last sample counts all of its time.
+      return a + (was && was.cpu <= p.cpu ? p.cpu - was.cpu : p.cpu);
+    }, 0);
+    by[key] = {
+      // Null until a span exists to measure over, so the UI can wait rather
+      // than flash a zero.
+      cpu: span >= 0.5 ? Math.round((busy / span) * 1000) / 10 : null,
+      mem: procs.reduce((a, p) => a + p.rss, 0),
+      procs: procs.length,
+    };
+  }
+  prev = snap;
+  return by;
+}
+
+// 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() {
+  prev = null;
+}

package/server/standup.js

@@ -0,0 +1,78 @@
+// The daily standup: everyone on the floor says what they got done, what's
+// next and what's in their way, and the chief wraps up. One model call
+// writes every update from the job history, so it costs about one chat
+// message. If that call fails, the updates are built from the facts alone.
+
+import { spawn } from 'node:child_process';
+
+const SCHEMA = {
+  type: 'object',
+  properties: {
+    updates: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          agentId: { type: 'string' },
+          done: { type: 'string' },
+          today: { type: 'string' },
+          blockers: { type: 'string' },
+        },
+        required: ['agentId', 'done', 'today', 'blockers'],
+        additionalProperties: false,
+      },
+    },
+    wrap: { type: 'string' },
+  },
+  required: ['updates', 'wrap'],
+  additionalProperties: false,
+};
+
+const SYSTEM = `You run the daily standup in an office of coding agents. You get each agent's facts: jobs they finished since the last standup, what they're on now, what's queued for them, and anything that went wrong.
+
+Write one update per agent, in that agent's own voice (first person, casual, like a real startup standup):
+- "done": what they finished, in a sentence or two. Name the project. Say plainly if something failed or was stopped. "Nothing shipped since last standup." if there's nothing.
+- "today": what they're on now or picking up next. If nothing, they're free and say so.
+- "blockers": what's in their way (failed jobs, missing clearance, waiting on someone), or "" if nothing.
+
+Then "wrap": the chief of staff closing the standup in one to three short sentences: what the office is focused on, anything at risk, and who's free to take work. If two agents are in the same project, point it out so they can sync.
+
+Use only the facts given; never invent work, results or blockers. Refer to agents by name or as "they"; never "he", "she", "him" or "her". Plain words, no markdown, no emoji.`;
+
+export function writeStandup(context, { bin = 'claude', model = 'sonnet', timeoutMs = 90000, 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 notes = r.structured_output || JSON.parse(r.result);
+        resolve({ ...notes, cost: r.total_cost_usd || 0 });
+      } catch {
+        reject(new Error(err.trim().split('\n').pop() || 'Could not write the standup.'));
+      }
+    });
+    child.stdin.end(context);
+  });
+}
+
+// When today's standup is due, as a timestamp, or null if there's none today.
+// `at` is "HH:MM" local time; standups are weekdays only unless `weekends`.
+export function dueToday(at, weekends, now = new Date()) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(at || '').trim());
+  if (!m) return null;
+  if (!weekends && (now.getDay() === 0 || now.getDay() === 6)) return null;
+  const due = new Date(now);
+  due.setHours(Number(m[1]), Number(m[2]), 0, 0);
+  return due.getTime();
+}

package/server/supervise.js

@@ -0,0 +1,51 @@
+// Keeps the office running across restarts it asks for. The server can't
+// start its own successor (its shutdown ends every agent, and the shell that
+// launched it is gone), so this sits above it: when the server exits with
+// RESTART, start it again. A clean exit or a signal is the boss closing up,
+// so go too; a crash gets another go.
+
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const RESTART = 75;
+const SERVER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.js');
+// A server that falls over this soon after a restart won't fare better on
+// the next go, so a few of those in a row ends it rather than spinning.
+const BOOT_MS = 10 * 1000;
+const MAX_QUICK_FAILS = 3;
+
+let child = null;
+let quickFails = 0;
+
+function run() {
+  const startedAt = Date.now();
+  child = spawn(process.execPath, [SERVER, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env, OFFICE_SUPERVISED: '1' },
+  });
+  child.on('exit', (code, signal) => {
+    child = null;
+    if (code === RESTART) {
+      quickFails = 0;
+      console.log('Restarting the office…');
+      return run();
+    }
+    // Ctrl-C reaches the server too, and it exits 0: that's closing time.
+    if (code === 0 || signal) return process.exit(code ?? 0);
+    if (Date.now() - startedAt < BOOT_MS && ++quickFails >= MAX_QUICK_FAILS) {
+      console.error(`The office failed to start ${quickFails} times in a row. Giving up.`);
+      return process.exit(code);
+    }
+    console.error(`The office stopped unexpectedly (exit ${code}). Starting it again…`);
+    setTimeout(run, 1000);
+  });
+}
+
+// The server handles these itself and saves on the way out; this only waits
+// for it. A signal sent to this process alone is passed on.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(sig, () => { if (child) child.kill(sig); else process.exit(0); });
+}
+
+run();