ai-agentmanager 1.11.0 → 1.12.0

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