ai-agentmanager 1.11.0 → 1.12.0

package/src/builder.js

@@ -0,0 +1,332 @@
+// The agent builder: a task or workflow in words → an analysis and an agentkit agent
+// (docs/agentkit.md) with test cases, which the person reviews, tests, runs and downloads. Built
+// agents live in ~/.agentmanager/built/<name>/ as ordinary agentkit folders.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import { Agent } from './agentkit/agent.js';
+import { turn as engineTurn } from './agentkit/engines.js';
+import { HOST, PLATFORMS, packageAgent } from './agentkit/package.js';
+import { checkAgent, loadAgent } from './agentkit/spec.js';
+import { parseJsonReply } from './brief.js';
+import { paths } from './config.js';
+
+const AGENTKIT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'agentkit.js');
+const root = () => path.join(paths.home, 'built');
+const err = (status, message) => Object.assign(new Error(message), { status });
+const now = () => new Date().toISOString();
+const slug = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'agent';
+
+export function designPrompt({ task, engine, attachments = [] }) {
+  return [
+    'You design an autonomous agent that will run continuously on its own and do one job well. It runs through',
+    `${engine === 'claude' ? 'Claude Code' : engine} as its engine, uses tools through MCP servers, and is reached by people (chat) and other agents (A2A, MCP).`,
+    'From the task below, write the analysis and the agent. Be concrete; do not invent systems the task does not mention.',
+    '',
+    'Reply with one JSON object only:',
+    '{',
+    '  "analysis": {"problem": "<what the job is and why>", "inputs": ["<what it receives>"], "outputs": ["<what it produces>"], "risks": ["<what could go wrong, and what needs a person>"]},',
+    '  "name": "<lowercase-with-dashes, 2-40 chars>", "title": "<short>", "description": "<one line>",',
+    '  "goal": "<what is true when it has done its job, for each input; one or two sentences>",',
+    '  "instructions": "<Markdown: how to do the job, step by step; what to never do; when to ask>",',
+    '  "tools": [{"name": "<short id>", "why": "<what it needs it for>", "command": "<MCP server command, e.g. npx>", "args": ["…"], "env": {"VAR": "${VAR}"}}],',
+    '  "allow": ["<engine tool names it may use without asking, e.g. Read, Grep, mcp__<tool>__*>"],',
+    '  "approve": ["<tools that change things in the outside world and need a person\'s yes>"],',
+    '  "triggers": [{"every": "30m"} | {"cron": "0 9 * * 1-5"} | {"webhook": "/hooks/<name>"} | {"watch": "./inbox"}],',
+    '  "tests": [{"input": "<a realistic input>", "expect": "<what a good result does or contains>"}]',
+    '}',
+    '',
+    'Rules: 3 to 5 tests that cover the normal case, an edge case and a case it should refuse or escalate.',
+    'Only MCP servers that really exist and fit (leave "tools" empty when none is needed). Secrets only as "${VAR}".',
+    'Triggers only when the task implies running on its own (a schedule, events); chat-only agents have none.',
+    '',
+    '<task>',
+    task,
+    '</task>',
+    ...(attachments.length ? ['<attached_files>', ...attachments.map((a) => `--- ${a.name}\n${a.text}`), '</attached_files>'] : []),
+  ].join('\n');
+}
+
+export function judgePrompt({ goal, input, expect, result }) {
+  return [
+    "You check one test of an autonomous agent. Decide if the agent's result meets the expectation for the input.",
+    'Be strict about substance, lenient about wording. Reply with JSON only: {"pass": true|false, "why": "<one sentence>"}.',
+    `<goal>\n${goal}\n</goal>`,
+    `<input>\n${input}\n</input>`,
+    `<expectation>\n${expect}\n</expectation>`,
+    `<result>\n${result}\n</result>`,
+  ].join('\n');
+}
+
+/** agent.yaml text from a design. */
+export function yamlOf(d, engine) {
+  const tools = Object.fromEntries((d.tools ?? []).filter((t) => t?.name && t.command).map((t) => [slug(t.name), { command: t.command, ...(t.args?.length ? { args: t.args } : {}), ...(t.env && Object.keys(t.env).length ? { env: t.env } : {}) }]));
+  const doc = {
+    name: slug(d.name),
+    title: d.title || d.name,
+    description: d.description ?? '',
+    goal: d.goal,
+    instructions: 'instructions.md',
+    engine,
+    tools,
+    allow: d.allow ?? [],
+    approve: d.approve ?? [],
+    triggers: d.triggers ?? [],
+    loop: { plan: true, check: true, maxSteps: 4 },
+    memory: true,
+    interfaces: { http: { port: 0 }, a2a: true, acp: true, mcp: true },
+  };
+  return YAML.stringify(doc, { lineWidth: 0 });
+}
+
+export class Builder {
+  /** `oneShot(prompt)` answers a design or judge prompt (the daemon's writer engine). */
+  /** `reportEnv()`: settings that make an agent started here report to this daemon. */
+  constructor({ oneShot, env = process.env, runTurn = engineTurn, pack = packageAgent, reportEnv = () => ({}) }) {
+    this.reportEnv = reportEnv;
+    this.oneShot = oneShot;
+    this.env = env;
+    this.runTurn = runTurn;
+    this.pack = pack;
+    this.procs = new Map(); // name -> child process of `agentkit run`
+    this.pending = new Map(); // name -> what's in progress (designing, testing)
+  }
+
+  dir(name) {
+    if (!/^[a-z][a-z0-9-]{1,40}$/.test(String(name))) throw err(400, 'Unknown agent');
+    return path.join(root(), name);
+  }
+
+  meta(name) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(this.dir(name), 'build.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  saveMeta(name, patch) {
+    const next = { ...this.meta(name), ...patch, updatedAt: now() };
+    fs.writeFileSync(path.join(this.dir(name), 'build.json'), JSON.stringify(next, null, 2));
+    return next;
+  }
+
+  list() {
+    let names = [];
+    try {
+      names = fs.readdirSync(root()).filter((n) => fs.existsSync(path.join(root(), n, 'build.json')));
+    } catch {}
+    return names.map((n) => this.view(n)).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  }
+
+  view(name) {
+    const m = this.meta(name);
+    if (!m) throw err(404, `No built agent "${name}"`);
+    const dir = this.dir(name);
+    const read = (f) => (fs.existsSync(path.join(dir, f)) ? fs.readFileSync(path.join(dir, f), 'utf8') : '');
+    let spec = null;
+    let specError = null;
+    try {
+      spec = loadAgent(dir, { env: this.env });
+    } catch (e) {
+      specError = e.message;
+    }
+    const p = this.procs.get(name);
+    let runs = [];
+    if (spec) runs = new Agent(spec, { env: this.env }).runs(20);
+    return {
+      ...m,
+      name,
+      title: spec?.title ?? name,
+      description: spec?.description ?? '',
+      dir,
+      yaml: read('agent.yaml'),
+      instructionsText: read('instructions.md'),
+      specError,
+      engine: spec?.engine ?? null,
+      triggers: spec?.triggers.map((t) => t.label) ?? [],
+      missingEnv: spec?.missingEnv ?? [],
+      pending: this.pending.get(name) ?? null,
+      running: p ? { pid: p.child.pid, url: p.url, since: p.since } : null,
+      runs,
+      platforms: PLATFORMS.filter((x) => process.platform === 'darwin' || !x.startsWith('macos-')),
+      host: HOST,
+      // Executables built since the last edit that are still there.
+      executables: Object.fromEntries(Object.entries(m.executables ?? {}).filter(([, x]) => fs.existsSync(path.join(dir, 'dist', x.file)))),
+    };
+  }
+
+  /** Design an agent from a task (one model call); writes the folder and returns it. */
+  async design({ task, engine = 'claude', attachments = [] }) {
+    task = String(task ?? '').trim();
+    if (!task) throw err(400, 'Describe the task or workflow');
+    if (!['claude', 'codex', 'muse'].includes(engine) && !/^acp:[a-z0-9-]+$/.test(engine)) throw err(400, 'engine: claude, codex, muse or acp:<name>');
+    const d = parseJsonReply(await this.oneShot(designPrompt({ task, engine, attachments })));
+    if (!d.goal || !d.name) throw err(502, 'The design was missing a name or goal; try again');
+    let name = slug(d.name);
+    for (let i = 2; fs.existsSync(path.join(root(), name)); i++) name = `${slug(d.name).slice(0, 36)}-${i}`;
+    const dir = path.join(root(), name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'agent.yaml'), yamlOf({ ...d, name }, engine));
+    fs.writeFileSync(path.join(dir, 'instructions.md'), String(d.instructions ?? '').trim() + '\n');
+    const tests = (d.tests ?? []).filter((t) => t?.input).slice(0, 8).map((t) => ({ input: String(t.input), expect: String(t.expect ?? '') }));
+    fs.writeFileSync(path.join(dir, 'tests.yaml'), YAML.stringify(tests));
+    // Check it loads; a broken design is kept so the person can fix it.
+    let specError = null;
+    try {
+      checkAgent(YAML.parse(fs.readFileSync(path.join(dir, 'agent.yaml'), 'utf8')), { dir, env: this.env });
+    } catch (e) {
+      specError = e.message;
+    }
+    this.saveMeta(name, { task, analysis: d.analysis ?? null, tools: (d.tools ?? []).map((t) => ({ name: t.name, why: t.why ?? '' })), tests, results: null, status: specError ? 'needs-fixing' : 'designed', createdAt: now() });
+    return this.view(name);
+  }
+
+  /** Save edits to agent.yaml, the instructions or the tests (each checked before it's written). */
+  update(name, { yaml, instructions, tests } = {}) {
+    const dir = this.dir(name);
+    if (!this.meta(name)) throw err(404, `No built agent "${name}"`);
+    if (yaml != null) {
+      let raw;
+      try {
+        raw = YAML.parse(String(yaml));
+      } catch (e) {
+        throw err(400, `agent.yaml: ${e.message.split('\n')[0]}`);
+      }
+      if (raw?.name !== name) throw err(400, `agent.yaml: keep the name "${name}" (it is the agent's folder)`);
+      fs.writeFileSync(path.join(dir, 'instructions.md'), instructions != null ? String(instructions) : fs.readFileSync(path.join(dir, 'instructions.md'), 'utf8'));
+      try {
+        checkAgent(raw, { dir, env: this.env });
+      } catch (e) {
+        throw err(400, e.message);
+      }
+      fs.writeFileSync(path.join(dir, 'agent.yaml'), String(yaml));
+    } else if (instructions != null) fs.writeFileSync(path.join(dir, 'instructions.md'), String(instructions));
+    if (tests != null) {
+      const list = (Array.isArray(tests) ? tests : []).filter((t) => t?.input).slice(0, 8).map((t) => ({ input: String(t.input), expect: String(t.expect ?? '') }));
+      fs.writeFileSync(path.join(dir, 'tests.yaml'), YAML.stringify(list));
+      this.saveMeta(name, { tests: list });
+    }
+    // Executables built before carry the old files; build them again after an edit.
+    if (yaml != null || instructions != null || tests != null) {
+      fs.rmSync(path.join(dir, 'dist'), { recursive: true, force: true });
+      this.saveMeta(name, { executables: {} });
+    }
+    return this.view(name);
+  }
+
+  /** Run every test through the real runtime, and judge each result against its expectation. */
+  async test(name) {
+    const dir = this.dir(name);
+    if (this.pending.get(name)) throw err(409, `Already ${this.pending.get(name)}`);
+    const spec = loadAgent(dir, { env: this.env });
+    const tests = YAML.parse(fs.readFileSync(path.join(dir, 'tests.yaml'), 'utf8') || '[]') ?? [];
+    if (!tests.length) throw err(400, 'No test cases; add some first');
+    this.pending.set(name, 'testing');
+    this.saveMeta(name, { status: 'testing' });
+    try {
+      // Tests don't wait for people: approval tools are simply not available in them.
+      const agent = new Agent({ ...spec, triggers: [], report: null }, { env: this.env, engineTurn: this.runTurn, approvals: 'deny' });
+      const results = [];
+      for (const t of tests) {
+        const r = await agent.run(t.input, { source: 'test' });
+        let verdict = { pass: false, why: 'The run failed' };
+        if (r.status !== 'failed') {
+          try {
+            const v = parseJsonReply(await this.oneShot(judgePrompt({ goal: spec.goal, input: t.input, expect: t.expect, result: r.result })));
+            verdict = { pass: v.pass === true, why: String(v.why ?? '') };
+          } catch (e) {
+            verdict = { pass: false, why: `Could not judge: ${e.message}` };
+          }
+        }
+        results.push({ input: t.input, expect: t.expect, result: r.result, status: r.status, costUsd: r.costUsd, ...verdict });
+      }
+      const passed = results.filter((r) => r.pass).length;
+      this.saveMeta(name, { results: { at: now(), passed, total: results.length, list: results }, status: passed === results.length ? 'tested' : 'failing' });
+    } catch (e) {
+      this.saveMeta(name, { status: 'failing', results: { at: now(), passed: 0, total: 0, list: [], error: e.message } });
+    } finally {
+      this.pending.delete(name);
+    }
+    return this.view(name);
+  }
+
+  /** Build its single executable for a platform into dist/ (in the background; the view says when). */
+  package(name, platform = HOST) {
+    const dir = this.dir(name);
+    if (!this.meta(name)) throw err(404, `No built agent "${name}"`);
+    if (this.pending.get(name)) throw err(409, `Already ${this.pending.get(name)}`);
+    if (!PLATFORMS.includes(platform)) throw err(400, `platform: one of ${PLATFORMS.join(', ')}`);
+    if (platform.startsWith('macos-') && process.platform !== 'darwin') throw err(400, 'macOS executables are built on a Mac');
+    loadAgent(dir, { env: this.env });
+    this.pending.set(name, `packaging for ${platform}`);
+    this.saveMeta(name, { packageError: null });
+    return this.#pack(name, dir, platform);
+  }
+
+  async #pack(name, dir, platform) {
+    try {
+      const r = await this.pack(dir, { outDir: path.join(dir, 'dist'), platform });
+      const executables = { ...this.meta(name).executables, [platform]: { file: path.basename(r.file), size: r.size, at: now() } };
+      this.saveMeta(name, { executables });
+    } catch (e) {
+      this.saveMeta(name, { packageError: `${platform}: ${e.message}` });
+    } finally {
+      this.pending.delete(name);
+    }
+    return this.view(name);
+  }
+
+  /** The path of a built executable, for download. */
+  executable(name, platform) {
+    const x = this.view(name).executables[platform];
+    if (!x) throw err(404, `No ${platform} executable built yet`);
+    return path.join(this.dir(name), 'dist', x.file);
+  }
+
+  /** Run it continuously on this computer (`agentkit run`); its output goes to agent.log. */
+  start(name) {
+    const dir = this.dir(name);
+    if (this.procs.has(name)) return this.view(name);
+    loadAgent(dir, { env: this.env });
+    const log = fs.openSync(path.join(dir, 'agent.log'), 'a');
+    const child = spawn(process.execPath, [AGENTKIT, 'run', dir], { env: { ...this.env, ...this.reportEnv() }, stdio: ['ignore', log, log], detached: false });
+    const entry = { child, url: null, since: now() };
+    this.procs.set(name, entry);
+    // Its chat address, from the log line it prints when listening.
+    const watch = setInterval(() => {
+      const m = /chat and API: (http:\/\/\S+)/.exec(fs.readFileSync(path.join(dir, 'agent.log'), 'utf8').split('\n').slice(-40).join('\n'));
+      if (m) {
+        entry.url = m[1];
+        clearInterval(watch);
+      }
+    }, 300);
+    setTimeout(() => clearInterval(watch), 20_000);
+    child.on('exit', () => {
+      clearInterval(watch);
+      if (this.procs.get(name) === entry) this.procs.delete(name);
+      this.saveMeta(name, { lastStoppedAt: now() });
+    });
+    this.saveMeta(name, { status: this.meta(name).status === 'tested' ? 'running' : this.meta(name).status, lastStartedAt: now() });
+    return this.view(name);
+  }
+
+  stop(name) {
+    const p = this.procs.get(name);
+    if (p) p.child.kill('SIGTERM');
+    this.procs.delete(name);
+    return this.view(name);
+  }
+
+  stopAll() {
+    for (const name of [...this.procs.keys()]) this.stop(name);
+  }
+
+  remove(name) {
+    this.stop(name);
+    fs.rmSync(this.dir(name), { recursive: true, force: true });
+    return { ok: true };
+  }
+}

package/src/manager.js

@@ -1797,6 +1797,11 @@ export class AgentManager extends EventEmitter {
     return [String(intent ?? '').trim(), attachmentNote(files)].filter(Boolean).join('\n\n');
   }
 
+  /** Staged uploads as text, for a model to read (the builder's attachments): name and up to 100 KB each. */
+  stagedText(attachments) {
+    return stagedFiles(attachments).map((f) => ({ name: path.basename(f).replace(/^\d{4}-\d\d-\d\dT[\d-]+Z-[0-9a-f]{6}-/, ''), text: fs.readFileSync(f, 'utf8').slice(0, 100_000) }));
+  }
+
   /** A file attached before its agent exists (New agents, Ask); create() copies it to the agent. */
   stageUpload(name, data) {
     fs.mkdirSync(stagedDir(), { recursive: true });

package/src/server.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
 import express from 'express';
 import { WebSocketServer } from 'ws';
 import { ensureHome, HOST, loadConfig, paths, PORT, saveConfig } from './config.js';
@@ -35,6 +36,8 @@ import * as remote from './remote.js';
 import * as service from './service.js';
 import { jiraView, saveJira } from './jira.js';
 import { CONTAINER_ENGINES, buildImage, claudeToken, dockerStatus, isBuilding, saveSecrets } from './container.js';
+import { AgentkitReports } from './agentkit-reports.js';
+import { Builder } from './builder.js';
 import { Store } from './store.js';
 import { about, latestRelease } from './about.js';
 
@@ -64,8 +67,9 @@ function isAllowedOrigin(origin, port) {
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
 // Updates are not here: a signed-in device (a phone) can install the newest release too. It only
 // ever installs an official release from where this copy came from (git tag or npm) and restarts.
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|service$|jira$|isolation\/|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|service$|jira$|isolation\/|editors$|agentkit\/connect$|agents\/[\w-]+\/open-in$|shutdown$)/;
 const HOOK_PATH = '/api/hooks/agents';
+const REPORT_PATH = '/api/agentkit/report';
 const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
 export async function startServer({ port = PORT, host = HOST } = {}) {
@@ -162,6 +166,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     return req.device ? null : 'Sign in required';
   }
 
+  const reports = new AgentkitReports();
   const app = express();
   app.disable('x-powered-by');
   app.use((req, res, next) => {
@@ -171,10 +176,14 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     // The webhook signs in with its token instead of a device session or the client header.
     const bearer = /^Bearer (.+)$/i.exec(req.headers.authorization ?? '')?.[1];
     const hook = req.method === 'POST' && req.url.split('?')[0] === HOOK_PATH && tokenMatches(req.headers['x-agentmgr-token'] ?? bearer, config.triggers?.webhook?.enabled ? config.triggers.webhook.token : null);
+    // So do agents built with agentkit reporting in (from this computer or another one).
+    const reportPath = req.method === 'POST' && req.url.split('?')[0] === REPORT_PATH;
+    const reporting = reportPath && tokenMatches(bearer, reports.token);
     const why = denied(req);
-    if (why && !(hook && why === 'Sign in required')) return res.status(why === 'Sign in required' ? 401 : 403).json({ error: why });
+    if (why && !((hook || reporting) && why === 'Sign in required')) return res.status(why === 'Sign in required' ? 401 : 403).json({ error: why });
     if (req.url.split('?')[0] === HOOK_PATH && !hook) return res.status(401).json({ error: 'Bad or missing token' });
-    if (!hook && !['GET', 'HEAD'].includes(req.method) && req.headers[CLIENT_HEADER] !== '1') {
+    if (reportPath && !reporting) return res.status(401).json({ error: 'Bad or missing report token' });
+    if (!hook && !reporting && !['GET', 'HEAD'].includes(req.method) && req.headers[CLIENT_HEADER] !== '1') {
       return res.status(403).json({ error: `Missing ${CLIENT_HEADER} header` });
     }
     next();
@@ -516,6 +525,53 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.get('/agents/:id/memory', wrap((req) => memory.read(req.params.id)));
   api.put('/agents/:id/memory', wrap((req) => memory.write(req.params.id, req.body?.text)));
   api.post('/agents/:id/learn', wrap((req) => memory.learn(req.params.id, req.body?.text, { by: req.headers['x-agentmgr-agent'] ? undefined : 'you' })));
+  // The agent builder (agentkit agents designed from a task): design, edit, test, run, download.
+  // Agents started here report to this daemon (runs, cost, approvals).
+  const builder = new Builder({ oneShot: (prompt) => manager.oneShot(null, prompt, { ...manager.writerFor({}), timeoutMs: 300_000 }), reportEnv: () => ({ AGENTKIT_REPORT_URL: `http://127.0.0.1:${port}`, AGENTKIT_REPORT_TOKEN: reports.reportToken() }) });
+  api.post('/agentkit/report', wrap((req) => reports.report(req.body ?? {})));
+  api.get('/agentkit/agents', wrap(() => reports.list()));
+  api.post('/agentkit/agents/:key/approvals/:id', wrap((req) => reports.decide(req.params.key, req.params.id, req.body?.allow === true, req.device ? `${req.device.name ?? 'a signed-in device'}` : 'you')));
+  api.delete('/agentkit/agents/:key', wrap((req) => reports.forget(req.params.key)));
+  // What an agent elsewhere needs to report here (this computer only: it shows the token).
+  api.get('/agentkit/connect', wrap(() => ({ token: reports.reportToken(), local: `http://127.0.0.1:${port}`, remote: remoteServer ? remote.remoteUrls(remotePort).map((u) => u.url) : [], cert: remoteServer ? remote.certificateFingerprint() : null })));
+  api.get('/builder', wrap(() => builder.list()));
+  api.post('/builder', wrap((req) => builder.design({ task: req.body?.task, engine: req.body?.engine || 'claude', attachments: req.body?.attachments?.length ? manager.stagedText(req.body.attachments) : [] })));
+  api.get('/builder/:name', wrap((req) => builder.view(req.params.name)));
+  api.put('/builder/:name', wrap((req) => builder.update(req.params.name, req.body ?? {})));
+  api.post('/builder/:name/test', wrap((req) => {
+    builder.test(req.params.name).catch(() => {}); // in the background; the view says when it's done
+    return new Promise((r) => setTimeout(() => r(builder.view(req.params.name)), 50));
+  }));
+  api.post('/builder/:name/package', wrap((req) => {
+    builder.package(req.params.name, req.body?.platform || undefined).catch(() => {}); // checks first, then builds in the background
+    return new Promise((r) => setTimeout(() => r(builder.view(req.params.name)), 50));
+  }));
+  api.get('/builder/:name/executable/:platform', (req, res) => {
+    let file;
+    try {
+      file = builder.executable(req.params.name, req.params.platform);
+    } catch (e) {
+      return res.status(e.status ?? 500).json({ error: e.message });
+    }
+    res.download(file, path.basename(file));
+  });
+  api.post('/builder/:name/start', wrap((req) => builder.start(req.params.name)));
+  api.post('/builder/:name/stop', wrap((req) => builder.stop(req.params.name)));
+  api.delete('/builder/:name', wrap((req) => builder.remove(req.params.name)));
+  // The agent's folder as a .tar.gz (its own files; not its runs, memory or log).
+  api.get('/builder/:name/download', (req, res) => {
+    let dir;
+    try {
+      dir = builder.view(req.params.name).dir;
+    } catch (e) {
+      return res.status(e.status ?? 500).json({ error: e.message });
+    }
+    res.setHeader('content-type', 'application/gzip');
+    res.setHeader('content-disposition', `attachment; filename="${req.params.name}.tar.gz"`);
+    const tar = spawn('tar', ['-czf', '-', '--exclude', '.agentkit', '--exclude', 'agent.log', '--exclude', 'build.json', '--exclude', 'work', '--exclude', 'dist', '-C', path.dirname(dir), path.basename(dir)]);
+    tar.stdout.pipe(res);
+    tar.on('error', () => res.end());
+  });
   // Isolation: Docker, the agent image, the Claude token for containers, and the default for new agents.
   let buildError = null;
   const isolationView = async () => ({ ...(await dockerStatus(config)), building: isBuilding(), buildError, hasClaudeToken: Boolean(claudeToken()), engines: [...CONTAINER_ENGINES], default: config.isolation?.default ?? null });
@@ -751,7 +807,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const eventSinks = new Set();
   api.get('/events/stream', (req, res) => {
     const send = sse(req, res);
-    send({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list(), teams: teams.list() });
+    send({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list(), teams: teams.list(), built: reports.list() });
     eventSinks.add(send);
     req.on('close', () => eventSinks.delete(send));
   });
@@ -844,6 +900,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     for (const send of eventSinks) send(msg);
   };
   manager.on('change', (agent) => broadcast({ t: 'agent', agent }));
+  reports.on('change', () => broadcast({ t: 'built', reports: reports.list() }));
   manager.on('removed', (id) => {
     broadcast({ t: 'removed', id });
     live.closeAgent(id).catch(() => {});
@@ -880,7 +937,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     const url = new URL(req.url, 'http://x');
     if (url.pathname === '/ws/events') {
       eventClients.add(ws);
-      ws.send(JSON.stringify({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list(), teams: teams.list() }));
+      ws.send(JSON.stringify({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list(), teams: teams.list(), built: reports.list() }));
       ws.on('close', () => eventClients.delete(ws));
       return;
     }
@@ -967,6 +1024,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     updates.close();
     assistant.close();
     console.log(`[agentmgr] shutting down (${reason}); closing agents so their sessions are saved`);
+    builder.stopAll();
     await manager.stopAll({ final: true });
     await manager.flush().catch((err) => console.error(`[agentmgr] final flush failed: ${err.message}`));
     try {