ai-agentmanager 1.11.0 → 1.12.0

package/src/agentkit/engines.js

@@ -0,0 +1,115 @@
+// 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 } };
+}
+
+/**
+ * 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 = 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 });
+  }
+}

package/src/agentkit/report.js

@@ -0,0 +1,106 @@
+// Reporting to AI Agent Manager: the agent says who it is, sends each run (status, cost, result)
+// and its open approvals, and picks up the decisions people made there. It checks in every 30
+// seconds (every 2 while an approval waits), and right away after a run or a new approval.
+import https from 'node:https';
+import os from 'node:os';
+
+const EXCERPT = 2000;
+
+/**
+ * POST JSON over https to a server with a self-signed certificate (AI Agent Manager's remote
+ * access), trusting only the certificate whose SHA-256 fingerprint is `pin`. The body is sent only
+ * after the fingerprint matches.
+ */
+export function pinnedPost(url, { headers, body, pin, timeoutMs = 15_000 }) {
+  const want = String(pin).replace(/:/g, '').toLowerCase();
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { method: 'POST', headers: { ...headers, 'content-length': Buffer.byteLength(body) }, rejectUnauthorized: false, agent: false, timeout: timeoutMs }, (res) => {
+      let text = '';
+      res.on('data', (d) => (text += d));
+      res.on('end', () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, json: async () => JSON.parse(text) }));
+    });
+    req.on('socket', (sock) =>
+      sock.once('secureConnect', () => {
+        const got = sock.getPeerX509Certificate?.()?.fingerprint256.replace(/:/g, '').toLowerCase();
+        if (got !== want) return req.destroy(new Error('the certificate does not match AGENTKIT_REPORT_CERT'));
+        req.end(body);
+      }),
+    );
+    req.on('timeout', () => req.destroy(new Error('timed out')));
+    req.on('error', reject);
+  });
+}
+
+export function startReporting(agent, { url, token, cert = null, chat = () => null, version = null, log = () => {}, fetchImpl = fetch, everyMs = 30_000, fastMs = 2_000 }) {
+  const endpoint = `${url.replace(/\/+$/, '')}/api/agentkit/report`;
+  const post = cert && endpoint.startsWith('https:') ? (u, o) => pinnedPost(u, { headers: o.headers, body: o.body, pin: cert }) : fetchImpl;
+  const startedAt = new Date().toISOString();
+  let unsent = []; // runs not yet acknowledged
+  let timer = null;
+  let busy = false;
+  let again = false;
+  let ok = null;
+  let stopped = false;
+
+  const onRun = (r) => {
+    unsent = [...unsent, { id: r.id, status: r.status, source: r.source, costUsd: r.costUsd, ms: r.ms, result: String(r.result ?? '').slice(0, EXCERPT), at: new Date().toISOString() }].slice(-50);
+    push();
+  };
+  const onApprovals = () => push();
+  agent.on('run', onRun);
+  agent.on('approvals', onApprovals);
+
+  async function push() {
+    if (stopped) return;
+    if (busy) return void (again = true);
+    busy = true;
+    clearTimeout(timer);
+    const s = agent.spec;
+    const sending = unsent;
+    const body = {
+      agent: { name: s.name, title: s.title, description: s.description, engine: s.engine, triggers: s.triggers.map((t) => t.label), host: os.hostname(), pid: process.pid, chat: chat(), version, startedAt },
+      current: agent.current,
+      runs: sending,
+      pending: agent.approvals.pending(),
+    };
+    try {
+      const res = await post(endpoint, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify(body), signal: AbortSignal.timeout(15_000) });
+      if (!res.ok) throw new Error(res.status === 401 ? 'the report token was not accepted' : `HTTP ${res.status}`);
+      const reply = await res.json();
+      unsent = unsent.filter((r) => !sending.includes(r));
+      for (const d of reply.decisions ?? []) agent.approvals.decide(d.id, d.allow, { by: d.by ?? 'AI Agent Manager', note: d.note ?? '' });
+      agent.approvals.channels.add('manager');
+      if (ok !== true) log(`reporting to AI Agent Manager at ${url}`);
+      ok = true;
+    } catch (e) {
+      agent.approvals.channels.delete('manager');
+      if (ok !== false) log(`could not report to AI Agent Manager (${e.message}); trying again`);
+      ok = false;
+    } finally {
+      busy = false;
+      if (!stopped) {
+        if (again) (again = false), setImmediate(push);
+        else timer = setTimeout(push, agent.approvals.pending().length ? fastMs : everyMs);
+      }
+    }
+  }
+
+  push();
+  // `push()` checks in now (say, once the chat page is up); `stop()` ends reporting.
+  return {
+    push,
+    /** Wait (a few seconds at most) until every run is sent: before a one-off run exits. */
+    flush: async (ms = 5000) => {
+      for (const end = Date.now() + ms; (unsent.length || busy) && Date.now() < end; ) {
+        if (!busy) push();
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    },
+    stop: () => {
+      stopped = true;
+      clearTimeout(timer);
+      agent.off('run', onRun);
+      agent.off('approvals', onApprovals);
+    },
+  };
+}

package/src/agentkit/sea-main.js

@@ -0,0 +1,25 @@
+// The entry point of a packaged agent (a single executable made by package.js). Its own files
+// (agent.yaml, instructions, tests) are embedded; the first run unpacks them to ~/.agentkit/<name>/,
+// where its memory and runs live too. Later runs keep that folder, so edits to its agent.yaml stay
+// (until a newer build of the same agent replaces the files it shipped).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import sea from 'node:sea';
+import { main } from './cli.js';
+
+const manifest = JSON.parse(sea.getAsset('manifest.json', 'utf8'));
+const dir = process.env.AGENTKIT_HOME ? path.resolve(process.env.AGENTKIT_HOME) : path.join(os.homedir(), '.agentkit', manifest.name);
+fs.mkdirSync(dir, { recursive: true });
+const stamp = path.join(dir, '.build');
+const shipped = fs.existsSync(stamp) ? fs.readFileSync(stamp, 'utf8').trim() : '';
+if (shipped !== manifest.build) {
+  for (const f of manifest.files) {
+    const target = path.join(dir, f);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, Buffer.from(sea.getAsset(`files/${f}`)));
+  }
+  fs.writeFileSync(stamp, manifest.build);
+}
+
+main(process.argv.slice(2), { name: manifest.name, defaultRef: dir, packaged: true });

package/src/agentkit/service.js

@@ -0,0 +1,118 @@
+// Keep an agent running in the background: a launchd agent (macOS) or a systemd user service
+// (Linux) that starts it at login and restarts it if it crashes. It runs through your login shell,
+// so it finds the engine CLIs and the tokens your terminal has.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const sh = (cmd, args) => new Promise((resolve, reject) => execFile(cmd, args, (e, out, err) => (e ? reject(new Error(String(err || e.message).trim())) : resolve(String(out)))));
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/** Where the service files go, and what they're called, for an agent. */
+export function servicePaths(name, home = os.homedir()) {
+  const label = `dev.agentkit.${name}`;
+  return {
+    label,
+    plist: path.join(home, 'Library', 'LaunchAgents', `${label}.plist`),
+    unitName: `agentkit-${name}.service`,
+    unit: path.join(home, '.config', 'systemd', 'user', `agentkit-${name}.service`),
+  };
+}
+
+/**
+ * What the service runs: `argv` starts the agent in the foreground (`<exe> run` for a packaged one,
+ * `node agentkit.js run <dir>` otherwise); settings that change where it lives or which engine
+ * binaries it uses carry over.
+ */
+export function serviceSpec({ name, dir, argv, env = process.env, shell = process.env.SHELL || '/bin/sh' }) {
+  const keep = {};
+  for (const [k, v] of Object.entries(env)) if (/^AGENTKIT_/.test(k) && v) keep[k] = v;
+  return { name, dir, log: path.join(dir, 'agent.log'), env: keep, command: [shell, '-l', '-c', `exec ${argv.map(q).join(' ')}`] };
+}
+
+export function plist(s, label = servicePaths(s.name).label) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${s.command.map((a) => `    <string>${xml(a)}</string>`).join('\n')}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>WorkingDirectory</key><string>${xml(s.dir)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(s.env).map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`).join('\n')}
+  </dict>
+  <key>StandardOutPath</key><string>${xml(s.log)}</string>
+  <key>StandardErrorPath</key><string>${xml(s.log)}</string>
+</dict>
+</plist>
+`;
+}
+
+export function unit(s) {
+  const cmd = s.command.map((a) => `"${a.replace(/(["\\])/g, '\\$1')}"`).join(' ');
+  return `[Unit]
+Description=agentkit agent ${s.name}
+
+[Service]
+ExecStart=${cmd}
+WorkingDirectory=${s.dir}
+Restart=on-failure
+${Object.entries(s.env).map(([k, v]) => `Environment=${k}=${v}\n`).join('')}StandardOutput=append:${s.log}
+StandardError=append:${s.log}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+const uid = () => process.getuid();
+
+export async function install(s) {
+  const p = servicePaths(s.name);
+  if (process.platform === 'darwin') {
+    fs.mkdirSync(path.dirname(p.plist), { recursive: true });
+    await sh('launchctl', ['bootout', `gui/${uid()}/${p.label}`]).catch(() => {});
+    fs.writeFileSync(p.plist, plist(s, p.label));
+    await sh('launchctl', ['bootstrap', `gui/${uid()}`, p.plist]);
+    return { file: p.plist, manager: 'launchd' };
+  }
+  if (process.platform === 'linux') {
+    fs.mkdirSync(path.dirname(p.unit), { recursive: true });
+    fs.writeFileSync(p.unit, unit(s));
+    await sh('systemctl', ['--user', 'daemon-reload']);
+    await sh('systemctl', ['--user', 'enable', '--now', p.unitName]);
+    return { file: p.unit, manager: 'systemd', note: 'To keep it running when you are logged out: loginctl enable-linger $USER' };
+  }
+  throw new Error(`Background service is not supported on ${process.platform}`);
+}
+
+export async function uninstall(name) {
+  const p = servicePaths(name);
+  if (process.platform === 'darwin') {
+    await sh('launchctl', ['bootout', `gui/${uid()}/${p.label}`]).catch(() => {});
+    fs.rmSync(p.plist, { force: true });
+    return { file: p.plist };
+  }
+  if (process.platform === 'linux') {
+    await sh('systemctl', ['--user', 'disable', '--now', p.unitName]).catch(() => {});
+    fs.rmSync(p.unit, { force: true });
+    await sh('systemctl', ['--user', 'daemon-reload']).catch(() => {});
+    return { file: p.unit };
+  }
+  throw new Error(`Background service is not supported on ${process.platform}`);
+}
+
+export async function status(name) {
+  const p = servicePaths(name);
+  if (process.platform === 'darwin') return { installed: fs.existsSync(p.plist), running: await sh('launchctl', ['print', `gui/${uid()}/${p.label}`]).then((o) => /state = running/.test(o), () => false), file: p.plist };
+  if (process.platform === 'linux') return { installed: fs.existsSync(p.unit), running: await sh('systemctl', ['--user', 'is-active', p.unitName]).then(() => true, () => false), file: p.unit };
+  return { installed: false, running: false, file: null };
+}