ai-agentmanager 1.11.1 → 1.12.0

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

package/src/agentkit/spec.js

@@ -0,0 +1,109 @@
+// agent.yaml: what an agentkit agent is (docs/agentkit.md). Loaded once at start: paths resolved
+// against the agent's folder, ${VAR} filled from the environment, defaults applied, mistakes
+// reported in one message.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+export const ENGINES = new Set(['claude', 'codex', 'muse']);
+const DURATION = /^(\d+)\s*(s|m|h|d)$/;
+export const toMs = (d) => {
+  const m = DURATION.exec(String(d).trim());
+  return m ? Number(m[1]) * { s: 1e3, m: 6e4, h: 36e5, d: 864e5 }[m[2]] : null;
+};
+
+/** ${VAR} from the environment (missing ones become empty, and are reported). */
+function fillEnv(value, env, missing) {
+  if (typeof value === 'string') return value.replace(/\$\{(\w+)\}/g, (_, k) => (k in env ? env[k] : (missing.add(k), '')));
+  if (Array.isArray(value)) return value.map((v) => fillEnv(v, env, missing));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, fillEnv(v, env, missing)]));
+  return value;
+}
+
+/** Read and check an agent: a folder with agent.yaml (or agent.json), or the file itself. */
+export function loadAgent(ref, { env = process.env } = {}) {
+  let file = path.resolve(ref);
+  if (fs.existsSync(file) && fs.statSync(file).isDirectory()) {
+    file = ['agent.yaml', 'agent.yml', 'agent.json'].map((n) => path.join(file, n)).find((f) => fs.existsSync(f)) ?? path.join(file, 'agent.yaml');
+  }
+  if (!fs.existsSync(file)) throw new Error(`No agent.yaml at ${file}`);
+  const dir = path.dirname(file);
+  const raw = file.endsWith('.json') ? JSON.parse(fs.readFileSync(file, 'utf8')) : YAML.parse(fs.readFileSync(file, 'utf8'));
+  return checkAgent(raw ?? {}, { dir, env, file });
+}
+
+export function checkAgent(raw, { dir, env = process.env, file = 'agent.yaml' } = {}) {
+  const errors = [];
+  const missing = new Set();
+  const a = fillEnv(raw, env, missing);
+  if (!/^[a-z][a-z0-9-]{1,40}$/.test(a.name ?? '')) errors.push('name: lowercase letters, digits and "-" (2-41 characters), starting with a letter');
+  if (!String(a.goal ?? '').trim()) errors.push('goal: say what the agent achieves');
+  const engine = String(a.engine ?? 'claude');
+  if (!ENGINES.has(engine) && !/^acp:[a-z0-9-]+$/.test(engine)) errors.push(`engine: claude, codex, muse or acp:<name> (not "${engine}")`);
+  // Instructions: a file next to agent.yaml, or inline text.
+  let instructions = String(a.instructions ?? '');
+  if (instructions && !instructions.includes('\n') && /\.(md|txt)$/.test(instructions)) {
+    const f = path.resolve(dir, instructions);
+    if (fs.existsSync(f)) instructions = fs.readFileSync(f, 'utf8');
+    else errors.push(`instructions: ${instructions} not found next to the agent`);
+  }
+  const triggers = (Array.isArray(a.triggers) ? a.triggers : []).map((t, i) => {
+    if (t?.every != null) {
+      const ms = toMs(t.every);
+      if (!ms || ms < 10_000) errors.push(`triggers[${i}].every: a duration of at least 10s, like 10m or 1h`);
+      return { kind: 'every', ms, label: `every ${t.every}` };
+    }
+    if (t?.cron) {
+      if (String(t.cron).trim().split(/\s+/).length !== 5) errors.push(`triggers[${i}].cron: five fields (minute hour day month weekday)`);
+      return { kind: 'cron', cron: String(t.cron), label: `cron ${t.cron}` };
+    }
+    if (t?.webhook) return { kind: 'webhook', path: `/${String(t.webhook).replace(/^\/+/, '')}`, label: `webhook ${t.webhook}` };
+    if (t?.watch) return { kind: 'watch', dir: path.resolve(dir, String(t.watch)), label: `watch ${t.watch}` };
+    errors.push(`triggers[${i}]: every, cron, webhook or watch`);
+    return null;
+  }).filter(Boolean);
+  const approveTimeoutMs = a.approveTimeout != null ? toMs(a.approveTimeout) : 30 * 60_000;
+  if (!approveTimeoutMs) errors.push('approveTimeout: a duration, like 30m or 2h');
+  // Where it reports its runs and asks for approvals: AI Agent Manager (the environment wins).
+  // cert: the SHA-256 fingerprint of its remote-access certificate (self-signed), when over https.
+  const report = { url: env.AGENTKIT_REPORT_URL || a.report?.url || null, token: env.AGENTKIT_REPORT_TOKEN || a.report?.token || null, cert: env.AGENTKIT_REPORT_CERT || a.report?.cert || null };
+  if (report.url && !/^https?:\/\//.test(report.url)) errors.push('report.url: an http(s) address of AI Agent Manager');
+  const loop = { plan: true, check: true, maxSteps: 4, budgetUsd: null, ...(a.loop ?? {}) };
+  loop.maxSteps = Math.max(1, Math.min(20, Number(loop.maxSteps) || 4));
+  const iface = a.interfaces ?? {};
+  const out = {
+    name: a.name,
+    title: String(a.title ?? a.name ?? ''),
+    description: String(a.description ?? ''),
+    goal: String(a.goal ?? '').trim(),
+    instructions: instructions.trim(),
+    engine,
+    model: a.model ? String(a.model) : null,
+    dir,
+    file,
+    workdir: path.resolve(dir, String(a.workdir ?? './work')),
+    tools: a.tools && typeof a.tools === 'object' ? a.tools : {},
+    allow: [a.allow ?? []].flat().map(String),
+    approve: [a.approve ?? []].flat().map(String),
+    approveTimeoutMs,
+    report: report.url ? report : null,
+    triggers,
+    loop,
+    memory: a.memory !== false,
+    interfaces: {
+      http: iface.http === false ? null : { port: Number(iface.http?.port ?? 7700), host: String(iface.http?.host ?? '127.0.0.1') },
+      a2a: iface.a2a !== false,
+      acp: iface.acp !== false,
+      mcp: iface.mcp !== false,
+    },
+    missingEnv: [...missing],
+  };
+  if (errors.length) throw Object.assign(new Error(`${file}:\n- ${errors.join('\n- ')}`), { errors });
+  return out;
+}
+
+/** The agent's own files: memory, run logs and engine sessions per conversation. */
+export function agentPaths(agent) {
+  const state = path.join(agent.dir, '.agentkit');
+  return { state, memory: path.join(state, 'memory.md'), runs: path.join(state, 'runs'), sessions: path.join(state, 'sessions.json'), mcp: path.join(state, 'mcp.json') };
+}