ai-agentmanager 1.11.1 → 1.13.0

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

package/src/agentkit/stdio.js

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

package/src/agentkit/triggers.js

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

package/src/agentkit-reports.js

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