ai-agentmanager 1.11.1 → 1.13.0

package/src/agentkit/approvals.js

@@ -0,0 +1,97 @@
+// Approvals: a tool on the agent's `approve` list runs only after a person says yes. Claude asks
+// the approver (an MCP tool, --permission-prompt-tool) before any tool it isn't allowed outright;
+// the approver asks this object over a private local address; this asks the people reachable
+// (the chat page, AI Agent Manager) and answers with the first decision, or no after a while.
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import http from 'node:http';
+
+/** Does a tool name match a pattern ("mcp__jira__*", "Bash", "Bash(git push:*)" → Bash)? */
+export function toolMatches(pattern, tool) {
+  const base = String(pattern).replace(/\(.*\)$/, '');
+  const re = new RegExp(`^${base.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`);
+  return re.test(String(tool));
+}
+
+/** Allow patterns Claude may apply on its own: not ones that also cover a tool that needs approval. */
+export function allowedOutright(spec) {
+  return spec.allow.filter((p) => !spec.approve.some((q) => toolMatches(p, q.replace(/\(.*\)$/, ''))));
+}
+
+export class Approvals extends EventEmitter {
+  constructor(spec, { timeoutMs = 30 * 60_000 } = {}) {
+    super();
+    this.spec = spec;
+    this.timeoutMs = timeoutMs;
+    this.open = new Map(); // id -> { id, tool, input, run, at, finish }
+    this.decided = []; // the latest decisions, for the views
+    this.channels = new Set(); // who can answer: 'chat', 'manager'
+    this.server = null;
+    this.token = crypto.randomBytes(24).toString('hex');
+  }
+
+  /** The private address the approver calls (started on first use). */
+  async address() {
+    if (this.server) return this.url;
+    this.server = http.createServer((req, res) => {
+      let body = '';
+      req.on('data', (d) => (body += d));
+      req.on('end', async () => {
+        const ok = req.method === 'POST' && req.headers.authorization === `Bearer ${this.token}`;
+        if (!ok) return res.writeHead(401).end();
+        let ask = {};
+        try {
+          ask = JSON.parse(body);
+        } catch {}
+        const d = await this.request({ tool: String(ask.tool ?? ''), input: ask.input ?? {} });
+        res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(d));
+      });
+    });
+    await new Promise((r) => this.server.listen(0, '127.0.0.1', r));
+    this.server.unref();
+    this.url = `http://127.0.0.1:${this.server.address().port}/`;
+    return this.url;
+  }
+
+  /** A tool wants to run: yes now if allowed, no if not on the approve list, else ask and wait. */
+  request({ tool, input = {} }) {
+    const ask = this.spec.approve.some((p) => toolMatches(p, tool));
+    if (!ask && this.spec.allow.some((p) => toolMatches(p, tool))) return Promise.resolve({ allow: true });
+    if (!ask) return Promise.resolve({ allow: false, message: `${tool} is not in this agent's allow list` });
+    if (!this.channels.size) return Promise.resolve({ allow: false, message: `${tool} needs a person's approval and no one can be asked (no chat page, not connected to AI Agent Manager)` });
+    const id = `ap-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => this.decide(id, false, { by: 'timeout', note: `No answer in ${Math.round(this.timeoutMs / 60_000)} min` }), this.timeoutMs);
+      const a = { id, tool, input, run: this.run ?? null, at: new Date().toISOString(), finish: (d) => (clearTimeout(timer), resolve(d)) };
+      this.open.set(id, a);
+      this.emit('request', this.view(a));
+      this.emit('change');
+    });
+  }
+
+  /** A person's (or the timeout's) answer. Returns false if it was already decided. */
+  decide(id, allow, { by = 'someone', note = '' } = {}) {
+    const a = this.open.get(id);
+    if (!a) return false;
+    this.open.delete(id);
+    const d = { ...this.view(a), allow: Boolean(allow), by, note, decidedAt: new Date().toISOString() };
+    this.decided = [d, ...this.decided].slice(0, 20);
+    a.finish({ allow: Boolean(allow), message: allow ? '' : `Declined by ${by}${note ? `: ${note}` : ''}` });
+    this.emit('decided', d);
+    this.emit('change');
+    return true;
+  }
+
+  view(a) {
+    return { id: a.id, tool: a.tool, input: a.input, run: a.run, at: a.at };
+  }
+
+  pending() {
+    return [...this.open.values()].map((a) => this.view(a));
+  }
+
+  close() {
+    for (const id of [...this.open.keys()]) this.decide(id, false, { by: 'shutdown' });
+    this.server?.close();
+  }
+}

package/src/agentkit/cli.js

@@ -0,0 +1,153 @@
+// The agentkit command line (bin/agentkit.js), also inside a packaged agent (sea-main.js), where
+// the agent's own folder is the default and `run` is the default command.
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command } from 'commander';
+import { Agent } from './agent.js';
+import { startHttp } from './http.js';
+import { loadAgent } from './spec.js';
+import { install as serviceInstall, serviceSpec, status as serviceStatus, uninstall as serviceUninstall } from './service.js';
+import { startReporting } from './report.js';
+import { serveAcp, serveApprover, serveMcp } from './stdio.js';
+import { startTriggers } from './triggers.js';
+
+// Status goes to stderr: stdout belongs to the protocol (acp, mcp) or the result (--once).
+const say = (m) => process.stderr.write(`[agentkit] ${m}\n`);
+const load = (ref) => {
+  const spec = loadAgent(ref);
+  if (spec.missingEnv.length) say(`warning: not set in the environment: ${spec.missingEnv.join(', ')}`);
+  return spec;
+};
+
+/** Run the command line; `defaultRef` is the agent folder when none is given. */
+export async function main(argv, { name = 'agentkit', defaultRef = '.', packaged = false } = {}) {
+  const program = new Command().name(name).description(packaged ? `${name}: an agent built with agentkit` : 'Run agents described by agent.yaml');
+
+  program
+    .command('run')
+    .argument('[agent]', 'the agent folder (or its agent.yaml)', defaultRef)
+    .option('--once <input>', 'do one run with this input, print the result and exit')
+    .option('-p, --port <port>', 'HTTP port (default: agent.yaml interfaces.http.port, or 7700)')
+    .action(async (ref, opts) => {
+      const spec = load(ref);
+      const agent = new Agent(spec);
+      agent.on('step', (s) => s.type !== 'start' && s.type !== 'end' && say(`${s.run} ${s.type}${s.text ? `: ${String(s.text).split('\n')[0].slice(0, 120)}` : ''}`));
+      agent.approvals.on('request', (a) => say(`approval needed: ${a.tool} (${a.id}); approve it ${[agent.approvals.channels.has('chat') && 'on the chat page', agent.approvals.channels.has('manager') && 'in AI Agent Manager'].filter(Boolean).join(' or ')}`));
+      agent.approvals.on('decided', (d) => say(`${d.tool}: ${d.allow ? 'approved' : 'declined'} by ${d.by}`));
+      let web = null;
+      const reporting = spec.report ? startReporting(agent, { url: spec.report.url, token: spec.report.token, cert: spec.report.cert, chat: () => web?.url ?? null, log: say }) : null;
+      if (opts.once !== undefined) {
+        const r = await agent.run(opts.once, { source: 'cli' });
+        await reporting?.flush();
+        process.stdout.write(`${r.result}\n`);
+        process.exit(r.status === 'failed' ? 1 : 0);
+      }
+      say(`${spec.title} (${spec.engine}) · working in ${spec.workdir}`);
+      const stop = startTriggers(agent, { log: say });
+      web = spec.interfaces.http ? await startHttp(agent, { port: opts.port ? Number(opts.port) : spec.interfaces.http.port, host: spec.interfaces.http.host, log: say }) : null;
+      reporting?.push(); // with its chat address now
+      agent.on('run', (r) => say(`run ${r.id} ${r.status} (${r.source}, ${Math.round(r.ms / 1000)}s${r.costUsd ? `, $${r.costUsd.toFixed(3)}` : ''})`));
+      const quit = async () => {
+        stop();
+        reporting?.stop();
+        agent.close();
+        await web?.close();
+        process.exit(0);
+      };
+      process.on('SIGINT', quit);
+      process.on('SIGTERM', quit);
+    });
+
+  program
+    .command('acp')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action((ref) => serveAcp(new Agent(load(ref))));
+
+  program
+    .command('mcp')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action((ref) => serveMcp(new Agent(load(ref))));
+
+  // Started by Claude as an MCP server (see approvals.js), not by people.
+  program
+    .command('approver', { hidden: true })
+    .action(() => serveApprover({ url: process.env.AGENTKIT_APPROVAL_URL, token: process.env.AGENTKIT_APPROVAL_TOKEN }));
+
+  program
+    .command('check')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action((ref) => {
+      const s = load(ref);
+      console.log(`${s.title} (${s.name}): engine ${s.engine}${s.model ? ` (${s.model})` : ''}, ${Object.keys(s.tools).length} MCP server(s), triggers: ${s.triggers.map((t) => t.label).join(', ') || 'none'}; interfaces: ${['http', 'a2a', 'acp', 'mcp'].filter((k) => s.interfaces[k]).join(', ')}`);
+    });
+
+  if (!packaged)
+    program
+      .command('package')
+      .description('Make the agent one executable to run anywhere (macOS or Linux; macOS ones are built on a Mac)')
+      .argument('[agent]', 'the agent folder', defaultRef)
+      .option('--platform <platform>', 'macos-arm64, macos-x64, linux-x64 or linux-arm64 (default: this computer)')
+      .option('-o, --out <folder>', 'where to write it (default: <agent>/dist)')
+      .action(async (ref, opts) => {
+        const { packageAgent, HOST } = await import('./package.js');
+        const spec = load(ref);
+        const r = await packageAgent(spec.dir, { outDir: path.resolve(opts.out ?? path.join(spec.dir, 'dist')), platform: opts.platform ?? HOST, log: say });
+        console.log(`${r.file} (${(r.size / 1048576).toFixed(0)} MB, ${r.platform}). Run it: ${r.file}   (needs ${spec.engine === 'claude' ? 'Claude Code' : spec.engine} installed and signed in)`);
+      });
+  if (!packaged)
+    program
+    .command('init')
+    .argument('<folder>', 'where to create the agent')
+    .option('-n, --name <name>', 'its name (default: the folder name)')
+    .action((folder, opts) => {
+      const dir = path.resolve(folder);
+      if (fs.existsSync(path.join(dir, 'agent.yaml'))) throw new Error(`${dir} already has an agent.yaml`);
+      const name = (opts.name ?? path.basename(dir)).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'my-agent';
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'agent.yaml'),
+        `name: ${name}\ntitle: ${name}\ndescription: What this agent does, in one line.\ngoal: |\n  What is true when the agent has done its job.\ninstructions: instructions.md\nengine: claude\n\ntools: {}            # MCP servers, e.g.  jira: { command: npx, args: [-y, "@acme/jira-mcp"] }\nallow: [Read, Grep, Glob]\n\ntriggers: []         # e.g.  - every: 30m   - cron: "0 9 * * 1-5"   - webhook: /hooks/new   - watch: ./inbox\n\nloop: { plan: true, check: true, maxSteps: 4 }\nmemory: true\ninterfaces: { http: { port: 7700 }, a2a: true, acp: true, mcp: true }\n`,
+      );
+      fs.writeFileSync(path.join(dir, 'instructions.md'), '# How to do the job\n\n1. …\n2. …\n\nWhen something is unclear, say what you need rather than guessing.\n');
+      console.log(`Created ${path.join(dir, 'agent.yaml')}. Edit it, then: agentkit run ${folder}`);
+    });
+
+  // In the background: started at login, restarted after a crash, output in <agent>/agent.log.
+  const service = program.command('service').description('Keep it running in the background (launchd on macOS, systemd on Linux)');
+  const serviceOf = (ref) => {
+    const spec = load(ref);
+    // A packaged agent runs itself; otherwise this agentkit runs the folder.
+    const argv = packaged ? [process.execPath, 'run'] : [process.execPath, path.resolve(process.argv[1]), 'run', spec.dir];
+    return { spec, s: serviceSpec({ name: spec.name, dir: spec.dir, argv }) };
+  };
+  service
+    .command('install')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action(async (ref) => {
+      const { spec, s } = serviceOf(ref);
+      const r = await serviceInstall(s);
+      console.log(`${spec.title} now runs in the background (${r.manager}: ${r.file}); output in ${s.log}.${packaged ? ` Keep ${process.execPath} where it is.` : ''}${r.note ? `\n${r.note}` : ''}`);
+    });
+  service
+    .command('uninstall')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action(async (ref) => {
+      const r = await serviceUninstall(load(ref).name);
+      console.log(`Stopped and removed ${r.file}`);
+    });
+  service
+    .command('status')
+    .argument('[agent]', 'the agent folder', defaultRef)
+    .action(async (ref) => {
+      const r = await serviceStatus(load(ref).name);
+      console.log(r.installed ? `installed (${r.file}); ${r.running ? 'running' : 'not running'}` : 'not installed');
+    });
+
+    // A packaged agent: `<agent>` runs it, `<agent> --once …` does one run, `<agent> acp|mcp|check` the rest.
+    if (packaged && !['run', 'acp', 'mcp', 'check', 'service', 'approver', 'help', '--help', '-h', '--version'].includes(argv[0])) argv = ['run', ...argv];
+    return program.parseAsync(argv, { from: 'user' }).catch((err) => {
+      console.error(`${name}: ${err.message}`);
+      process.exit(1);
+    });
+  }
+

package/src/agentkit/engines.js

@@ -0,0 +1,128 @@
+// One headless turn of an engine's CLI: a prompt in, the answer (and session, cost) out. The agent
+// keeps one engine session per conversation, so a follow-up continues it. Tools come from the
+// agent's MCP servers; the allow list says what runs without asking. "approve" tools ask a person
+// through the approver (Claude), or are kept out of reach (engines with no way to ask).
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+import { allowedOutright } from './approvals.js';
+
+// Inside a packaged agent? (node:sea only exists from Node 20.12; the daemon supports older 20s.)
+const isSea = () => {
+  try {
+    return createRequire(import.meta.url)('node:sea').isSea();
+  } catch {
+    return false;
+  }
+};
+const AGENTKIT_BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'agentkit.js');
+const ACP_CLIENT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'acp-client.js');
+// Overrides for tests and odd installs: AGENTKIT_CLAUDE_BIN, AGENTKIT_CODEX_BIN, AGENTKIT_MUSE_BIN
+// (a command, optionally with arguments: "node /path/fake.js").
+const binOf = (name, env) => (env[`AGENTKIT_${name.toUpperCase()}_BIN`] ?? name).split(' ');
+
+function run(cmd, args, { input, cwd, env, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', (e) => (clearTimeout(timer), reject(Object.assign(e, { message: `Could not start ${cmd}: ${e.message}` }))));
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(out);
+      else reject(new Error(`${path.basename(cmd)} exited with ${code}: ${(err || out).trim().slice(-400)}`));
+    });
+    child.stdin.end(input ?? '');
+  });
+}
+
+/** The MCP config file the engine loads (Claude's format: { mcpServers: {...} }), plus `extra` servers. */
+export function writeMcpConfig(agent, file, extra = {}) {
+  const servers = { ...agent.tools, ...extra };
+  if (!Object.keys(servers).length) return null;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ mcpServers: servers }, null, 2), { mode: 0o600 });
+  return file;
+}
+
+/** The approver as an MCP server: this program (`<agent> approver` when packaged) asking `url`. */
+export const APPROVER = 'agentkit_approval';
+export function approverServer({ url, token }) {
+  return { command: process.execPath, args: isSea() ? ['approver'] : [AGENTKIT_BIN, 'approver'], env: { AGENTKIT_APPROVAL_URL: url, AGENTKIT_APPROVAL_TOKEN: token } };
+}
+
+/**
+ * Claude Code scopes file writes with Edit(<path>) rules (they cover Write too); a Write(<path>)
+ * rule is ignored. Each Write(<path>) also gets its Edit(<path>), so writing there is allowed.
+ */
+export function claudeRules(allow) {
+  const out = [...allow];
+  for (const p of allow) {
+    const m = /^Write\((.+)\)$/.exec(p);
+    if (m && !out.includes(`Edit(${m[1]})`)) out.push(`Edit(${m[1]})`);
+  }
+  return out;
+}
+
+/**
+ * One turn. `session`: the engine session to continue (null starts one); returns
+ * { text, session, costUsd }. `system` goes in as an extra system prompt where the engine has one,
+ * else ahead of the prompt.
+ */
+export async function turn(agent, { prompt, system = '', session = null, mcpFile = null, approver = false, env = process.env, timeoutMs = 15 * 60_000 }) {
+  fs.mkdirSync(agent.workdir, { recursive: true });
+  const cwd = agent.workdir;
+  if (agent.engine === 'claude') {
+    const [cmd, ...pre] = binOf('claude', env);
+    const sid = session ?? crypto.randomUUID();
+    const args = [...pre, '-p', '--output-format', 'json', session ? '--resume' : '--session-id', sid];
+    if (agent.model) args.push('--model', agent.model);
+    if (system) args.push('--append-system-prompt', system);
+    // Self-contained: the agent's own MCP servers only (none when it has none), and none of the
+    // person's own Claude settings (their MCP servers, hooks, permissions) leak in.
+    args.push('--setting-sources', 'project', '--strict-mcp-config');
+    if (mcpFile) args.push('--mcp-config', mcpFile);
+    // The approve list wins: an allow pattern that also covers an approval tool goes to the approver.
+    const allow = claudeRules(approver ? allowedOutright(agent) : agent.allow);
+    if (allow.length) args.push('--allowedTools', ...allow);
+    // With an approver, Claude asks it before anything not allowed outright (it says no to tools
+    // off the approve list); without one, approval tools are simply not available.
+    if (approver) args.push('--permission-prompt-tool', `mcp__${APPROVER}__decide`);
+    else if (agent.approve.length) args.push('--disallowedTools', ...agent.approve);
+    const out = await run(cmd, args, { input: prompt, cwd, env, timeoutMs });
+    try {
+      const j = JSON.parse(out);
+      if (j.is_error) throw new Error(String(j.result ?? 'the engine reported an error'));
+      return { text: String(j.result ?? ''), session: j.session_id ?? sid, costUsd: j.total_cost_usd ?? null };
+    } catch (e) {
+      if (e instanceof SyntaxError) return { text: out.trim(), session: sid, costUsd: null };
+      throw e;
+    }
+  }
+  if (agent.engine === 'codex') {
+    const [cmd, ...pre] = binOf('codex', env);
+    const base = ['exec', '--skip-git-repo-check', '--sandbox', 'workspace-write', ...(agent.model ? ['--model', agent.model] : [])];
+    const args = [...pre, ...(session ? [...base, 'resume', session] : base), '-'];
+    const out = await run(cmd, args, { input: system ? `${system}\n\n---\n\n${prompt}` : prompt, cwd, env, timeoutMs });
+    // Codex prints its session id in a header line ("session id: …").
+    const sid = session ?? /session id:\s*([0-9a-f-]{36})/i.exec(out)?.[1] ?? null;
+    return { text: out.trim().split(/\n-{3,}\n|\ntokens used/i)[0].trim(), session: sid, costUsd: null };
+  }
+  if (agent.engine === 'muse') {
+    const [cmd, ...pre] = binOf('muse', env);
+    const args = [...pre, 'exec', ...(session ? ['--session-id', session] : []), ...(agent.model ? ['--model', agent.model] : []), '--', system ? `${system}\n\n---\n\n${prompt}` : prompt];
+    return { text: (await run(cmd, args, { cwd, env, timeoutMs })).trim(), session, costUsd: null };
+  }
+  // acp:<name>: our ACP client in one-shot mode, with the agent's command from AGENTKIT_ACP_<NAME>.
+  const name = agent.engine.slice(4);
+  const command = (env[`AGENTKIT_ACP_${name.toUpperCase().replace(/-/g, '_')}`] ?? name).split(' ');
+  const out = await run(process.execPath, [ACP_CLIENT, '--once', '--', ...command], { input: system ? `${system}\n\n---\n\n${prompt}` : prompt, cwd, env, timeoutMs });
+  return { text: out.trim(), session: null, costUsd: null };
+}

package/src/agentkit/http.js

@@ -0,0 +1,131 @@
+// The agent over HTTP: a chat page for people, a small API for apps, webhooks for triggers, and
+// A2A (the agent-to-agent protocol: an agent card, and tasks over JSON-RPC) for other agents.
+import crypto from 'node:crypto';
+import http from 'node:http';
+import express from 'express';
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+/** The A2A agent card: who the agent is and how to reach it. */
+export function agentCard(agent, base) {
+  const s = agent.spec;
+  return {
+    protocolVersion: '0.3.0',
+    name: s.title,
+    description: s.description || s.goal,
+    url: `${base}/a2a`,
+    preferredTransport: 'JSONRPC',
+    version: '1.0.0',
+    capabilities: { streaming: false, pushNotifications: false },
+    defaultInputModes: ['text/plain'],
+    defaultOutputModes: ['text/plain'],
+    skills: [{ id: s.name, name: s.title, description: s.goal, tags: [s.engine] }],
+  };
+}
+
+const taskOf = (t) => ({
+  kind: 'task',
+  id: t.id,
+  contextId: t.contextId,
+  status: { state: t.state, timestamp: t.at, ...(t.result != null ? { message: { kind: 'message', role: 'agent', messageId: `${t.id}-r`, parts: [{ kind: 'text', text: t.result }] } } : {}) },
+  ...(t.result != null && t.state === 'completed' ? { artifacts: [{ artifactId: `${t.id}-a`, parts: [{ kind: 'text', text: t.result }] }] } : {}),
+});
+
+const PAGE = (agent) => `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(agent.spec.title)}</title><style>
+:root{--bg:#f6f7f9;--panel:#fff;--text:#1c2330;--muted:#667085;--border:#dde1e7;--accent:#3b5bdb}
+@media (prefers-color-scheme:dark){:root{--bg:#0d0f14;--panel:#151821;--text:#e5e8ef;--muted:#8b93a7;--border:#2a2f3c;--accent:#6d8bff}}
+body{margin:0;font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:var(--bg);color:var(--text);display:flex;flex-direction:column;height:100vh}
+header{padding:12px 16px;border-bottom:1px solid var(--border);background:var(--panel)}header b{font-size:16px}header p{margin:2px 0 0;color:var(--muted);font-size:13px}
+#log{flex:1;overflow:auto;padding:16px;display:flex;flex-direction:column;gap:10px}
+.m{max-width:760px;padding:10px 12px;border-radius:10px;white-space:pre-wrap;word-break:break-word}.you{align-self:flex-end;background:var(--accent);color:#fff}.agent{background:var(--panel);border:1px solid var(--border)}
+#ap{display:flex;flex-direction:column;gap:8px;padding:0 16px}#ap:not(:empty){padding:12px 16px;border-bottom:1px solid var(--border)}.ap{padding:10px 12px;border-radius:10px;border:1px solid #e8a33d;background:var(--panel)}.ap pre{margin:6px 0;font-size:12px;white-space:pre-wrap;max-height:160px;overflow:auto}.ap .no{background:transparent;color:var(--text);border:1px solid var(--border)}
+.step{font-size:12px;color:var(--muted)}form{display:flex;gap:8px;padding:12px 16px;border-top:1px solid var(--border);background:var(--panel)}
+textarea{flex:1;resize:none;font:inherit;padding:8px;border-radius:8px;border:1px solid var(--border);background:var(--bg);color:inherit}button{font:inherit;padding:8px 14px;border-radius:8px;border:0;background:var(--accent);color:#fff}
+</style></head><body><header><b>${esc(agent.spec.title)}</b><p>${esc(agent.spec.description || agent.spec.goal)}</p></header>
+<div id="ap"></div><div id="log"></div><form id="f"><textarea id="t" rows="2" placeholder="Ask or tell the agent…"></textarea><button>Send</button></form>
+<script>
+const log=document.getElementById('log');const conv=localStorage.getItem('conv')||crypto.randomUUID();localStorage.setItem('conv',conv);
+const add=(cls,text)=>{const d=document.createElement('div');d.className='m '+cls;d.textContent=text;log.append(d);log.scrollTop=log.scrollHeight;return d};
+document.getElementById('f').onsubmit=async(e)=>{e.preventDefault();const t=document.getElementById('t');const text=t.value.trim();if(!text)return;t.value='';add('you',text);
+const wait=add('agent step','Working on it…');const r=await fetch('api/chat',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({message:text,conversation:conv})}).then(r=>r.json()).catch(e=>({error:e.message}));
+wait.remove();add('agent',r.result??('Error: '+r.error))};
+const ap=document.getElementById('ap');const esc=(s)=>String(s).replace(/[&<>"]/g,(c)=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'})[c]);
+async function approvals(){const l=await fetch('api/approvals').then(r=>r.json()).catch(()=>[]);ap.innerHTML=l.map(a=>'<div class="ap"><b>Approve '+esc(a.tool)+'?</b> <span class="step">asked '+new Date(a.at).toLocaleTimeString()+'</span><pre>'+esc(JSON.stringify(a.input,null,2))+'</pre><button data-id="'+esc(a.id)+'" data-allow="1">Approve</button> <button class="no" data-id="'+esc(a.id)+'">Deny</button></div>').join('')}
+ap.onclick=async(e)=>{const b=e.target.closest('button[data-id]');if(!b)return;b.disabled=true;await fetch('api/approvals/'+b.dataset.id,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({allow:!!b.dataset.allow})});approvals()};
+approvals();setInterval(approvals,2000);
+document.getElementById('t').onkeydown=(e)=>{if(e.key==='Enter'&&!e.shiftKey){e.preventDefault();document.getElementById('f').requestSubmit()}};
+</script></body></html>`;
+
+/** Start the HTTP side; resolves with { server, url, close }. */
+export function startHttp(agent, { port, host = '127.0.0.1', log = () => {} } = {}) {
+  const app = express();
+  app.use(express.json({ limit: '2mb' }));
+  const tasks = new Map(); // A2A task id -> { id, contextId, state, result, at }
+  const wrap = (fn) => (req, res) => Promise.resolve(fn(req, res)).then((v) => v !== undefined && res.json(v)).catch((err) => res.status(err.status ?? 500).json({ error: err.message }));
+
+  app.get('/', (req, res) => res.type('html').send(PAGE(agent)));
+  app.get('/api/health', (req, res) => res.json({ ok: true, agent: agent.spec.name, engine: agent.spec.engine, running: agent.current, triggers: agent.spec.triggers.map((t) => t.label) }));
+  app.post('/api/chat', wrap(async (req) => {
+    const message = String(req.body?.message ?? '').trim();
+    if (!message) throw Object.assign(new Error('message is required'), { status: 400 });
+    return agent.run(message, { source: 'chat', conversation: String(req.body?.conversation ?? '').slice(0, 80) || crypto.randomUUID() });
+  }));
+  // Tools waiting for a person's approval, and their answers (JSON only: a page elsewhere can't post here).
+  app.get('/api/approvals', wrap(() => agent.approvals.pending()));
+  app.post('/api/approvals/:id', wrap((req) => {
+    if (!req.is('application/json') || typeof req.body?.allow !== 'boolean') throw Object.assign(new Error('Send {"allow": true|false}'), { status: 400 });
+    if (!agent.approvals.decide(req.params.id, req.body.allow, { by: 'the chat page', note: String(req.body.note ?? '') })) throw Object.assign(new Error('Already decided'), { status: 409 });
+    return { ok: true };
+  }));
+  agent.approvals.channels.add('chat');
+  app.post('/api/runs', wrap((req) => agent.run(String(req.body?.input ?? ''), { source: 'api' })));
+  app.get('/api/runs', wrap(() => agent.runs()));
+  app.get('/api/runs/:id', wrap((req) => agent.runLog(req.params.id) ?? Promise.reject(Object.assign(new Error('No such run'), { status: 404 }))));
+
+  // Webhook triggers: the body (JSON or text) is the run's input.
+  for (const t of agent.spec.triggers.filter((x) => x.kind === 'webhook')) {
+    app.post(t.path, express.text({ type: () => true, limit: '2mb' }), wrap(async (req) => {
+      const run = agent.run(typeof req.body === 'string' ? req.body : JSON.stringify(req.body ?? {}), { source: t.label });
+      run.catch(() => {});
+      return { accepted: true };
+    }));
+    log(`trigger: ${t.label}`);
+  }
+
+  // A2A.
+  if (agent.spec.interfaces.a2a) {
+    app.get('/.well-known/agent.json', (req, res) => res.json(agentCard(agent, `http://${req.headers.host}`)));
+    app.get('/.well-known/agent-card.json', (req, res) => res.json(agentCard(agent, `http://${req.headers.host}`)));
+    app.post('/a2a', async (req, res) => {
+      const { id, method, params = {} } = req.body ?? {};
+      const reply = (result) => res.json({ jsonrpc: '2.0', id, result });
+      const fail = (code, message) => res.json({ jsonrpc: '2.0', id, error: { code, message } });
+      if (method === 'message/send') {
+        const msg = params.message ?? {};
+        const text = (msg.parts ?? []).filter((p) => p.kind === 'text' || p.type === 'text').map((p) => p.text).join('\n').trim();
+        if (!text) return fail(-32602, 'message.parts needs a text part');
+        const t = { id: crypto.randomUUID(), contextId: msg.contextId ?? crypto.randomUUID(), state: 'working', result: null, at: new Date().toISOString() };
+        tasks.set(t.id, t);
+        const r = await agent.run(text, { source: 'a2a', conversation: `a2a:${t.contextId}` });
+        Object.assign(t, { state: r.status === 'failed' ? 'failed' : 'completed', result: r.result, at: new Date().toISOString() });
+        return reply(taskOf(t));
+      }
+      if (method === 'tasks/get') {
+        const t = tasks.get(params.id);
+        return t ? reply(taskOf(t)) : fail(-32001, 'Task not found');
+      }
+      return fail(-32601, `Method not found: ${method}`);
+    });
+  }
+
+  const server = http.createServer(app);
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      const url = `http://${host}:${server.address().port}`;
+      log(`chat and API: ${url}${agent.spec.interfaces.a2a ? `  ·  A2A card: ${url}/.well-known/agent.json` : ''}`);
+      resolve({ server, url, close: () => (agent.approvals.channels.delete('chat'), new Promise((r) => server.close(r))) });
+    });
+  });
+}

package/src/agentkit/package.js

@@ -0,0 +1,114 @@
+// Package an agent as one executable (Node's single executable applications): the runtime bundled
+// with esbuild, the agent's files embedded as assets, injected with postject into the official Node
+// binary (from nodejs.org, same version as this one, checksum-verified, cached) for each platform.
+// The prepared blob depends only on the Node version, so every platform builds from here; macOS
+// ones must be signed, so they build on a Mac. The engine CLIs it drives are installed separately.
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { loadAgent } from './spec.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// Assembled at run time: the literal must not appear in the bundle we inject (this file is part of
+// it), or postject finds the sentinel twice.
+const FUSE = ['NODE', 'SEA', 'FUSE', 'fce680ab2cc467b6e072b8b5df1996b2'].join('_');
+export const HOST = `${process.platform === 'darwin' ? 'macos' : process.platform}-${process.arch}`;
+export const PLATFORMS = ['macos-arm64', 'macos-x64', 'linux-x64', 'linux-arm64'];
+const sh = (cmd, args, opts = {}) =>
+  new Promise((resolve, reject) =>
+    execFile(cmd, args, { timeout: 20 * 60_000, maxBuffer: 64 * 1024 * 1024, ...opts }, (e, out, err) => (e ? reject(new Error(`${path.basename(cmd)} failed: ${`${err}\n${out}`.replace(/\x1b\[[0-9;]*m/g, '').trim().split('\n').slice(-4).join(' ') || e.message}`)) : resolve(String(out)))),
+  );
+
+/** The agent's own files to embed: agent.yaml, its instructions file, tests, and anything it names. */
+function agentFiles(dir) {
+  const keep = ['agent.yaml', 'agent.yml', 'agent.json', 'instructions.md', 'tests.yaml', 'README.md'];
+  return keep.filter((f) => fs.existsSync(path.join(dir, f)));
+}
+
+/** One file: the runtime and its libraries (express, yaml, commander) as CommonJS. */
+async function bundle(outFile) {
+  const esbuild = await import('esbuild');
+  await esbuild.build({
+    entryPoints: [path.join(ROOT, 'src', 'agentkit', 'sea-main.js')],
+    outfile: outFile,
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    target: 'node22',
+    // import.meta.url doesn't exist in CommonJS; give the modules that use it this file's URL.
+    define: { 'import.meta.url': '__agentkitUrl' },
+    banner: { js: "const __agentkitUrl = require('node:url').pathToFileURL(__filename).href;" },
+    logLevel: 'error',
+  });
+}
+
+/** The official Node binary for a platform (this Node's version), downloaded once and checked. */
+export async function nodeBinary(platform, { cacheDir, log = () => {} } = {}) {
+  const v = process.version;
+  const [osName, arch] = platform.split('-');
+  const dist = `node-${v}-${osName === 'macos' ? 'darwin' : 'linux'}-${arch}`;
+  const dir = path.join(cacheDir, dist);
+  const bin = path.join(dir, 'node');
+  if (fs.existsSync(bin)) return bin;
+  fs.mkdirSync(dir, { recursive: true });
+  const base = `https://nodejs.org/dist/${v}`;
+  log(`downloading Node ${v} for ${platform}`);
+  const sums = await (await fetch(`${base}/SHASUMS256.txt`)).text();
+  const want = new RegExp(`^([0-9a-f]{64})\\s+${dist}\\.tar\\.gz$`, 'm').exec(sums)?.[1];
+  if (!want) throw new Error(`nodejs.org has no ${dist}.tar.gz`);
+  const res = await fetch(`${base}/${dist}.tar.gz`);
+  if (!res.ok) throw new Error(`Download of ${dist} failed (HTTP ${res.status})`);
+  const tgz = Buffer.from(await res.arrayBuffer());
+  const got = crypto.createHash('sha256').update(tgz).digest('hex');
+  if (got !== want) throw new Error(`${dist}.tar.gz failed its checksum; not using it`);
+  const tmp = path.join(dir, 'node.tar.gz');
+  fs.writeFileSync(tmp, tgz);
+  await sh('tar', ['-xzf', tmp, '-C', dir, '--strip-components', '2', `${dist}/bin/node`]);
+  fs.rmSync(tmp);
+  return bin;
+}
+
+/** Inject the blob into a copy of `nodeBin` (signature removed and re-applied for macOS). */
+async function inject(nodeBin, blob, out, { mac }) {
+  fs.copyFileSync(nodeBin, out);
+  fs.chmodSync(out, 0o755);
+  if (mac) await sh('codesign', ['--remove-signature', out]);
+  await sh(process.execPath, [createRequire(import.meta.url).resolve('postject/dist/cli.js'), out, 'NODE_SEA_BLOB', blob, '--sentinel-fuse', FUSE, ...(mac ? ['--macho-segment-name', 'NODE_SEA'] : [])]);
+  if (mac) await sh('codesign', ['--sign', '-', out]);
+}
+
+/**
+ * Build `<outDir>/<name>-<platform>` for an agent folder (any platform; macOS ones on a Mac).
+ * Returns { file, platform, size }.
+ */
+export async function packageAgent(agentDir, { outDir, platform = HOST, cacheDir = path.join(os.homedir(), '.agentmanager', 'node-dist'), log = () => {} } = {}) {
+  const spec = loadAgent(agentDir);
+  if (spec.engine.startsWith('acp:')) throw Object.assign(new Error('ACP engines are not supported in a packaged agent yet; run its folder with agentkit'), { status: 400 });
+  if (!PLATFORMS.includes(platform)) throw Object.assign(new Error(`platform: one of ${PLATFORMS.join(', ')}`), { status: 400 });
+  if (platform.startsWith('macos-') && process.platform !== 'darwin') throw Object.assign(new Error('macOS executables are built on a Mac (they must be signed there)'), { status: 400 });
+  fs.mkdirSync(outDir, { recursive: true });
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), `agentkit-pack-${spec.name}-`));
+  try {
+    log('bundling the runtime');
+    await bundle(path.join(work, 'main.cjs'));
+    const files = agentFiles(spec.dir);
+    const assets = { 'manifest.json': path.join(work, 'manifest.json') };
+    for (const f of files) assets[`files/${f}`] = path.join(spec.dir, f);
+    const build = crypto.createHash('sha256').update(files.map((f) => fs.readFileSync(path.join(spec.dir, f))).join('\0')).digest('hex').slice(0, 16);
+    fs.writeFileSync(assets['manifest.json'], JSON.stringify({ name: spec.name, title: spec.title, build, files }));
+    const out = path.join(outDir, `${spec.name}-${platform}`);
+    fs.writeFileSync(path.join(work, 'sea.json'), JSON.stringify({ main: path.join(work, 'main.cjs'), output: path.join(work, 'blob'), disableExperimentalSEAWarning: true, useCodeCache: false, assets }));
+    log('preparing the blob');
+    await sh(process.execPath, ['--experimental-sea-config', path.join(work, 'sea.json')]);
+    const nodeBin = await nodeBinary(platform, { cacheDir, log });
+    log(`making the executable for ${platform}`);
+    await inject(nodeBin, path.join(work, 'blob'), out, { mac: platform.startsWith('macos-') });
+    return { file: out, platform, size: fs.statSync(out).size };
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}