ai-agentmanager 1.11.1 → 1.12.0

package/src/agentkit/stdio.js

@@ -0,0 +1,95 @@
+// The agent on stdio, for clients that start it as a program:
+//   ACP (`<agent> acp`): editors and AI Agent Manager's ACP engine drive it like a coding agent.
+//   MCP (`<agent> mcp`): other agents get one tool, ask_<name>, that hands it a task.
+// Both are newline-delimited JSON-RPC 2.0. Nothing but protocol goes to stdout.
+import crypto from 'node:crypto';
+import readline from 'node:readline';
+
+function serve(handle, { input = process.stdin, output = process.stdout } = {}) {
+  const send = (m) => output.write(JSON.stringify({ jsonrpc: '2.0', ...m }) + '\n');
+  readline.createInterface({ input }).on('line', async (line) => {
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!msg.method) return;
+    try {
+      const result = await handle(msg.method, msg.params ?? {}, send);
+      if (msg.id != null) send({ id: msg.id, result: result ?? {} });
+    } catch (err) {
+      if (msg.id != null) send({ id: msg.id, error: { code: err.code ?? -32603, message: err.message } });
+    }
+  });
+}
+
+/** ACP: sessions are conversations; a prompt is a run whose steps stream as updates. */
+export function serveAcp(agent, io) {
+  serve(async (method, p, send) => {
+    if (method === 'initialize') return { protocolVersion: 1, agentCapabilities: { loadSession: true }, agentInfo: { name: agent.spec.name, title: agent.spec.title, version: '1.0.0' }, authMethods: [] };
+    if (method === 'session/new') return { sessionId: `ak-${crypto.randomUUID()}` };
+    if (method === 'session/load') return {};
+    if (method === 'session/cancel') return {};
+    if (method === 'session/prompt') {
+      const text = (p.prompt ?? []).map((b) => b.text ?? '').join('').trim();
+      const update = (u) => send({ method: 'session/update', params: { sessionId: p.sessionId, update: u } });
+      const onStep = (s) => {
+        if (s.type === 'plan' || s.type === 'check' || s.type === 'reflect') update({ sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: `[${s.type}] ${s.text}\n` } });
+      };
+      agent.on('step', onStep);
+      try {
+        const r = await agent.run(text, { source: 'acp', conversation: `acp:${p.sessionId}` });
+        update({ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: r.result } });
+        return { stopReason: r.status === 'failed' ? 'refusal' : 'end_turn' };
+      } finally {
+        agent.off('step', onStep);
+      }
+    }
+    throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+  }, io);
+}
+
+/** MCP: one tool, ask_<name>, whose answer is the run's result. */
+export function serveMcp(agent, io) {
+  const tool = `ask_${agent.spec.name.replace(/-/g, '_')}`;
+  serve(async (method, p) => {
+    if (method === 'initialize') return { protocolVersion: p.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: agent.spec.name, version: '1.0.0' } };
+    if (method === 'notifications/initialized' || method === 'ping') return {};
+    if (method === 'tools/list') {
+      return { tools: [{ name: tool, description: `${agent.spec.title}: ${agent.spec.description || agent.spec.goal}`, inputSchema: { type: 'object', properties: { task: { type: 'string', description: 'What you want done' } }, required: ['task'] } }] };
+    }
+    if (method === 'tools/call') {
+      if (p.name !== tool) throw Object.assign(new Error(`Unknown tool ${p.name}`), { code: -32602 });
+      const r = await agent.run(String(p.arguments?.task ?? ''), { source: 'mcp' });
+      return { content: [{ type: 'text', text: r.result }], isError: r.status === 'failed' };
+    }
+    throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+  }, io);
+}
+
+/**
+ * The approver (`<agent> approver`): the MCP tool Claude asks (--permission-prompt-tool) before a
+ * tool that isn't allowed outright. It hands the request to the running agent (AGENTKIT_APPROVAL_URL,
+ * with AGENTKIT_APPROVAL_TOKEN), which asks a person, and answers with their decision.
+ */
+export function serveApprover({ url, token, fetchImpl = fetch } = {}, io) {
+  serve(async (method, p) => {
+    if (method === 'initialize') return { protocolVersion: p.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'agentkit-approver', version: '1.0.0' } };
+    if (method === 'notifications/initialized' || method === 'ping') return {};
+    if (method === 'tools/list') {
+      return { tools: [{ name: 'decide', description: 'Asks a person whether a tool may run', inputSchema: { type: 'object', properties: { tool_name: { type: 'string' }, input: { type: 'object' }, tool_use_id: { type: 'string' } }, required: ['tool_name'] } }] };
+    }
+    if (method === 'tools/call') {
+      const a = p.arguments ?? {};
+      let d = { allow: false, message: 'No one could be asked (the agent is not reachable)' };
+      try {
+        const res = await fetchImpl(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify({ tool: a.tool_name, input: a.input ?? {} }) });
+        if (res.ok) d = await res.json();
+      } catch {}
+      const text = d.allow ? JSON.stringify({ behavior: 'allow', updatedInput: a.input ?? {} }) : JSON.stringify({ behavior: 'deny', message: d.message || 'A person declined this' });
+      return { content: [{ type: 'text', text }] };
+    }
+    throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
+  }, io);
+}

package/src/agentkit/triggers.js

@@ -0,0 +1,60 @@
+// What starts a run by itself: an interval, a cron schedule, a folder watch. (Webhooks arrive over
+// HTTP, see http.js.) Each fires agent.run with a short description of why.
+import fs from 'node:fs';
+
+/** One cron field ("*", "5", "1-5", "*\/15", "1,15") against a value. */
+function fieldMatches(field, value, min, max) {
+  return field.split(',').some((part) => {
+    const [range, stepRaw] = part.split('/');
+    const step = Number(stepRaw ?? 1) || 1;
+    let [lo, hi] = range === '*' ? [min, max] : range.split('-').map(Number);
+    if (hi == null) hi = stepRaw ? max : lo;
+    return value >= lo && value <= hi && (value - lo) % step === 0;
+  });
+}
+
+/** Whether a five-field cron expression (minute hour day month weekday) matches a time. */
+export function cronMatches(expr, d = new Date()) {
+  const [mi, h, dom, mon, dow] = String(expr).trim().split(/\s+/);
+  return fieldMatches(mi, d.getMinutes(), 0, 59) && fieldMatches(h, d.getHours(), 0, 23) && fieldMatches(dom, d.getDate(), 1, 31) && fieldMatches(mon, d.getMonth() + 1, 1, 12) && fieldMatches(dow, d.getDay(), 0, 6);
+}
+
+/** Start the agent's triggers; returns a function that stops them. */
+export function startTriggers(agent, { log = () => {} } = {}) {
+  const stops = [];
+  for (const t of agent.spec.triggers) {
+    if (t.kind === 'every') {
+      const timer = setInterval(() => agent.run('', { source: t.label }).catch(() => {}), t.ms);
+      stops.push(() => clearInterval(timer));
+    } else if (t.kind === 'cron') {
+      let last = '';
+      const timer = setInterval(() => {
+        const d = new Date();
+        const minute = d.toISOString().slice(0, 16);
+        if (minute !== last && cronMatches(t.cron, d)) {
+          last = minute;
+          agent.run('', { source: t.label }).catch(() => {});
+        }
+      }, 15_000);
+      stops.push(() => clearInterval(timer));
+    } else if (t.kind === 'watch') {
+      fs.mkdirSync(t.dir, { recursive: true });
+      // A burst of changes (an editor saving, a copy) is one run.
+      let pending = new Set();
+      let timer = null;
+      const w = fs.watch(t.dir, (event, file) => {
+        if (!file || file.startsWith('.')) return;
+        pending.add(file);
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+          const files = [...pending];
+          pending = new Set();
+          agent.run(`Files changed in ${t.dir}: ${files.join(', ')}`, { source: t.label }).catch(() => {});
+        }, 1500);
+      });
+      stops.push(() => (clearTimeout(timer), w.close()));
+    }
+    if (t.kind !== 'webhook') log(`trigger: ${t.label}`);
+  }
+  return () => stops.forEach((s) => s());
+}

package/src/agentkit-reports.js

@@ -0,0 +1,117 @@
+// Agents built with agentkit report here (src/agentkit/report.js): who they are, each run, and the
+// tool approvals they're waiting on. People see them in the Built tab and the Inbox, and their
+// decisions go back with the agent's next check-in. Kept in ~/.agentmanager/agentkit-reports.json.
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { paths } from './config.js';
+
+const ONLINE_MS = 90_000;
+const file = () => path.join(paths.home, 'agentkit-reports.json');
+const err = (status, message) => Object.assign(new Error(message), { status });
+const str = (v, n = 200) => String(v ?? '').slice(0, n);
+
+export class AgentkitReports extends EventEmitter {
+  constructor() {
+    super();
+    let saved = {};
+    try {
+      saved = JSON.parse(fs.readFileSync(file(), 'utf8'));
+    } catch {}
+    this.token = saved.token ?? null;
+    this.agents = new Map(Object.entries(saved.agents ?? {}));
+    this.decisions = new Map(); // key -> [{ id, allow, by, note }] to hand back on its next check-in
+    this.saveTimer = null;
+  }
+
+  /** The token agents report with (made on first use). */
+  reportToken() {
+    if (!this.token) {
+      this.token = crypto.randomBytes(24).toString('base64url');
+      this.save(true);
+    }
+    return this.token;
+  }
+
+  save(now = false) {
+    clearTimeout(this.saveTimer);
+    const write = () => {
+      fs.mkdirSync(paths.home, { recursive: true });
+      fs.writeFileSync(file(), JSON.stringify({ token: this.token, agents: Object.fromEntries(this.agents) }, null, 2), { mode: 0o600 });
+    };
+    if (now) write();
+    else this.saveTimer = setTimeout(write, 1000);
+  }
+
+  /** A check-in from an agent. Returns the decisions waiting for it. */
+  report(body = {}) {
+    const a = body.agent ?? {};
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(String(a.name ?? ''))) throw err(400, 'agent.name: required');
+    const key = `${a.name}@${str(a.host, 120) || 'unknown'}`;
+    const prev = this.agents.get(key) ?? { runs: [], totals: { runs: 0, failed: 0, costUsd: 0 } };
+    const known = new Set(prev.runs.map((r) => r.id));
+    const fresh = (Array.isArray(body.runs) ? body.runs : []).filter((r) => r?.id && !known.has(r.id)).map((r) => ({ id: str(r.id, 80), status: str(r.status, 20), source: str(r.source, 80), costUsd: Number(r.costUsd) || null, ms: Number(r.ms) || null, result: str(r.result, 2000), at: str(r.at, 40) }));
+    const totals = { ...prev.totals };
+    for (const r of fresh) {
+      totals.runs++;
+      if (r.status === 'failed') totals.failed++;
+      totals.costUsd = Math.round((totals.costUsd + (r.costUsd ?? 0)) * 1e6) / 1e6;
+    }
+    const decided = new Set((this.decisions.get(key) ?? []).map((d) => d.id));
+    const next = {
+      key,
+      name: a.name,
+      title: str(a.title) || a.name,
+      description: str(a.description, 400),
+      engine: str(a.engine, 40),
+      triggers: (Array.isArray(a.triggers) ? a.triggers : []).slice(0, 10).map((t) => str(t, 80)),
+      host: str(a.host, 120),
+      pid: Number(a.pid) || null,
+      chat: /^https?:\/\//.test(String(a.chat ?? '')) ? str(a.chat, 300) : null,
+      version: str(a.version, 40) || null,
+      startedAt: str(a.startedAt, 40) || null,
+      lastSeen: new Date().toISOString(),
+      current: body.current?.id ? { id: str(body.current.id, 80), source: str(body.current.source, 80), startedAt: str(body.current.startedAt, 40) } : null,
+      // Approvals already answered here stay hidden until the agent confirms them.
+      pending: (Array.isArray(body.pending) ? body.pending : []).filter((p) => p?.id && !decided.has(p.id)).slice(0, 20).map((p) => ({ id: str(p.id, 80), tool: str(p.tool, 200), input: p.input && typeof p.input === 'object' ? p.input : {}, run: p.run ? str(p.run, 80) : null, at: str(p.at, 40) })),
+      runs: [...fresh.reverse(), ...prev.runs].slice(0, 50),
+      totals,
+    };
+    this.agents.set(key, next);
+    const decisions = this.decisions.get(key) ?? [];
+    this.decisions.delete(key);
+    this.save();
+    this.emit('change');
+    return { ok: true, decisions };
+  }
+
+  /** A person's answer to an approval; it goes back on the agent's next check-in. */
+  decide(key, id, allow, by = 'you') {
+    const a = this.agents.get(key);
+    if (!a) throw err(404, 'No such agent');
+    const p = a.pending.find((x) => x.id === id);
+    if (!p) throw err(409, 'Already decided, or no longer waiting');
+    this.decisions.set(key, [...(this.decisions.get(key) ?? []), { id, allow: Boolean(allow), by }]);
+    a.pending = a.pending.filter((x) => x.id !== id);
+    this.emit('change');
+    return this.view(a);
+  }
+
+  forget(key) {
+    this.agents.delete(key);
+    this.decisions.delete(key);
+    this.save();
+    this.emit('change');
+    return { ok: true };
+  }
+
+  view(a) {
+    const online = Date.now() - Date.parse(a.lastSeen) < ONLINE_MS;
+    return { ...a, online, pending: online ? a.pending : [], runs: a.runs.slice(0, 10) };
+  }
+
+  list() {
+    return [...this.agents.values()].map((a) => this.view(a)).sort((x, y) => String(y.lastSeen).localeCompare(String(x.lastSeen)));
+  }
+}

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 });