ai-agentmanager 1.11.0 → 1.12.0

package/public/index.html

@@ -64,6 +64,7 @@
           <button class="side-tab" data-tab="inbox" role="tab" title="Everything waiting on you: prompts, questions, stuck agents, overlaps">Inbox <span id="inbox-count" class="badge"></span></button>
           <button class="side-tab" data-tab="backlog" role="tab">Backlog <span id="backlog-count" class="badge"></span></button>
           <button class="side-tab" data-tab="land" role="tab" title="Agents' open pull requests: what each needs to get merged">Land <span id="land-count" class="badge"></span></button>
+          <button class="side-tab" data-tab="built" role="tab" title="Agents you build for a task or workflow: they plan, act, check themselves and run in the background">Built <span id="built-count" class="badge"></span></button>
         </div>
         <div id="agents-view">
           <div class="counts" id="counts"></div>
@@ -79,6 +80,7 @@
         <div id="backlog-view" hidden></div>
         <div id="inbox-view" hidden></div>
         <div id="land-view" hidden></div>
+        <div id="built-view" hidden></div>
         <div id="empty" class="empty" hidden>
           <p>No agents yet.</p>
           <p>Add one or more intents and a repo or folder to get started.</p>
@@ -161,6 +163,8 @@
           </div>
           <div id="term-drop" class="term-drop" hidden>Drop files to attach</div>
           <div class="keybar" id="keybar" aria-label="Terminal keys">
+            <button data-clip-act="copy" title="Copy text from the terminal">Copy</button>
+            <button data-clip-act="paste" title="Paste into the terminal">Paste</button>
             <button data-key="esc">Esc</button>
             <button data-key="tab">Tab</button>
             <button data-key="stab" title="Shift+Tab: cycle permission mode">⇧Tab</button>
@@ -375,6 +379,25 @@
       </form>
     </dialog>
 
+    <dialog id="build-dialog">
+      <form id="build-form" method="dialog">
+        <h2>Build an agent</h2>
+        <p class="hint">Describe the task or workflow it takes over: what comes in, what it should do, what it must never do. It's designed for you to review (analysis, spec, test cases) before it runs.</p>
+        <label>Task or workflow
+          <textarea name="task" rows="8" required placeholder="Every morning, look at new support tickets in Jira, label each by product area, route it to the right team, and draft a first reply for a person to send. Never close or reply to tickets on its own."></textarea>
+        </label>
+        <div id="build-attach"></div>
+        <label>Engine <select name="engine"><option value="claude">Claude Code</option></select></label>
+        <p id="build-error" class="error" hidden></p>
+        <div class="dialog-actions"><button type="button" id="build-cancel" class="ghost">Cancel</button><button type="submit" class="primary">Design the agent</button></div>
+      </form>
+    </dialog>
+
+    <dialog id="built-dialog" class="doc-dialog">
+      <div class="doc-head"><h2 id="built-title"></h2><span class="spacer"></span><button type="button" id="built-close" class="small ghost">Close</button></div>
+      <div id="built-body" class="built-body"></div>
+    </dialog>
+
     <dialog id="doc-dialog" class="doc-dialog">
       <div class="doc-head">
         <h2 id="doc-title"></h2>
@@ -767,6 +790,8 @@
         <button class="term-tab term-add" id="machine-new" title="Open another terminal">+ Terminal</button>
         <span id="machine-title" class="hint"></span>
         <span class="spacer"></span>
+        <button id="machine-copy" class="ghost small" title="Copy text from the terminal">Copy</button>
+        <button id="machine-paste" class="ghost small" title="Paste into the terminal">Paste</button>
         <button id="machine-close" class="ghost small" title="Hide (the shells keep running)">Hide</button>
       </div>
       <div id="machine-term" class="terminal"></div>

package/public/machine.js

@@ -2,6 +2,7 @@
 // any signed-in device (over remote access it streams like an agent's shell). The shells keep
 // running when the window is hidden; × ends one.
 import { openStream } from '/transport.js';
+import { openCopy, pasteInto } from '/termclip.js';
 
 const MACHINE = '__machine__';
 
@@ -86,6 +87,9 @@ export function initMachine({ api, esc, toast, $, Terminal, FitAddon }) {
     shells = [...new Set([...shells, n])];
     connect(n);
   };
+  // Copy / Paste buttons: on a phone the terminal's text can't be selected or pasted into directly.
+  $('#machine-copy').onclick = () => xterm && openCopy(xterm, { esc, toast });
+  $('#machine-paste').onclick = () => xterm && pasteInto(xterm, { toast });
   $('#machine-close').onclick = () => {
     conn?.close();
     conn = null;

package/public/style.css

@@ -497,6 +497,7 @@ dialog::backdrop { background: rgba(0, 0, 0, .45); }
 .need-head { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; margin-bottom: 4px; }
 .need-kind { font-size: 10.5px; font-weight: 700; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
 .need.prompt .need-kind { color: var(--red); }
+.need.approval .need-kind { color: var(--red); }
 .need.question .need-kind { color: var(--accent); }
 .need.stuck .need-kind { color: var(--yellow); }
 .need.conflict .need-kind { color: #8e59ff; }
@@ -940,3 +941,35 @@ form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px;
 /* Settings → More: separators belong to the links, so hidden (local-only) ones leave none behind. */
 .settings-links button + button::before { content: '·'; display: inline-block; margin: 0 8px; color: var(--muted); }
 body.remote .settings-links .local-only { display: none; }
+
+/* Copy / Paste sheets for terminals on touch screens. */
+.clip-sheet { width: min(760px, calc(100vw - 16px)); max-height: calc(100vh - 32px); padding: 0; display: flex; flex-direction: column; }
+.clip-sheet:not([open]) { display: none; }
+.clip-head { display: flex; align-items: center; gap: 8px; padding: 10px 12px; border-bottom: 1px solid var(--border); flex-wrap: wrap; }
+.clip-text { margin: 0; padding: 10px 12px; overflow: auto; flex: 1; min-height: 200px; max-height: 70vh; font: 12px/1.45 var(--mono, ui-monospace, monospace); white-space: pre-wrap; word-break: break-word; -webkit-user-select: text; user-select: text; background: var(--term-bg); color: #e6edf3; }
+.clip-box { margin: 10px 12px; width: calc(100% - 24px); font: 13px var(--mono, ui-monospace, monospace); }
+.clip-foot { display: flex; align-items: center; gap: 8px; padding: 0 12px 12px; }
+.clip-foot .hint { flex: 1; }
+
+/* Built agents. */
+.built-head { display: flex; flex-direction: column; gap: 6px; padding: 10px 12px; }
+.built-list { list-style: none; margin: 0; padding: 0; }
+.built-list li { padding: 9px 12px; border-bottom: 1px solid var(--border); cursor: pointer; }
+.built-list li:hover { background: var(--panel-2); }
+.built-list .line1 { display: flex; align-items: center; gap: 6px; }
+.built-empty { padding: 0 12px; }
+.dot-run { color: var(--green); font-size: 10px; }
+.dot-run.off { color: var(--muted); }
+.reporting-head { margin-top: 18px; }
+.report-approval { margin: 8px 0; padding: 8px 10px; border: 1px solid var(--yellow); border-radius: 8px; }
+.report-approval pre, .need-input { font-size: 12px; white-space: pre-wrap; max-height: 160px; overflow: auto; margin: 6px 0; }
+#built-connect { padding: 0 12px; } #built-connect pre { white-space: pre-wrap; word-break: break-all; padding: 8px; border: 1px solid var(--border); border-radius: 6px; }
+.built-body { padding: 0 4px 12px; display: flex; flex-direction: column; gap: 10px; }
+.built-body details > summary { cursor: pointer; padding: 4px 0; }
+.built-actions { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.built-exe { margin: 10px 0; padding: 8px 10px; border: 1px solid var(--border); border-radius: 8px; }
+.built-exe-row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 6px; }
+.built-tests li { margin-bottom: 8px; } .built-tests li.pass b { color: var(--green); } .built-tests li.fail b { color: var(--red); }
+.built-tests pre, .built-runs div { white-space: pre-wrap; font-size: 12.5px; }
+.code-area { width: 100%; font: 12.5px/1.45 var(--mono); margin-top: 6px; }
+.built-runs { list-style: none; padding: 0; } .built-runs li { padding: 6px 0; border-bottom: 1px solid var(--border); }

package/public/termclip.js

@@ -0,0 +1,92 @@
+// Copy and paste for terminals on touch screens. xterm draws its text itself, so a phone can't
+// long-press-select it, and its hidden input rarely gets the paste menu. Copy opens the terminal's
+// recent output as plain text the phone can select (or Copy all); Paste reads the clipboard (the
+// phone asks first) or, where it can't, offers a box to paste into, then sends it as one paste.
+
+const MAX_LINES = 600;
+
+/** The terminal's text: the last lines of its buffer, trailing blanks trimmed. */
+export function terminalText(xterm, max = MAX_LINES) {
+  const buf = xterm.buffer.active;
+  const lines = [];
+  for (let i = Math.max(0, buf.length - max); i < buf.length; i++) {
+    const line = buf.getLine(i);
+    if (!line) continue;
+    // A wrapped line continues the one before it.
+    if (line.isWrapped && lines.length) lines[lines.length - 1] += line.translateToString(true);
+    else lines.push(line.translateToString(true));
+  }
+  while (lines.length && !lines.at(-1).trim()) lines.pop();
+  return lines.join('\n');
+}
+
+function sheet(html) {
+  const d = document.createElement('dialog');
+  d.className = 'clip-sheet';
+  d.innerHTML = html;
+  document.body.append(d);
+  d.addEventListener('close', () => d.remove());
+  d.showModal();
+  return d;
+}
+
+async function writeClipboard(text) {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    // Older browsers, or no permission: copy through a selected text area.
+    const t = Object.assign(document.createElement('textarea'), { value: text });
+    t.style.cssText = 'position:fixed;opacity:0';
+    document.body.append(t);
+    t.select();
+    const ok = document.execCommand?.('copy');
+    t.remove();
+    return Boolean(ok);
+  }
+}
+
+/** Copy: the terminal's text in a sheet, selectable with the phone's own handles, and Copy all. */
+export function openCopy(xterm, { esc, toast }) {
+  const text = terminalText(xterm);
+  const d = sheet(`<div class="clip-head"><b>Copy from the terminal</b><span class="hint">Select with your finger, or copy it all</span><span class="spacer"></span><button type="button" class="small primary" data-clip="all">Copy all</button><button type="button" class="small ghost" data-clip="close">Close</button></div>
+    <pre class="clip-text">${esc(text) || '<span class="hint">Nothing in this terminal yet.</span>'}</pre>`);
+  // Open at the end, where the latest output is.
+  const pre = d.querySelector('.clip-text');
+  pre.scrollTop = pre.scrollHeight;
+  d.addEventListener('click', async (e) => {
+    const act = e.target.closest('[data-clip]')?.dataset.clip;
+    if (act === 'close') d.close();
+    if (act === 'all') {
+      toast((await writeClipboard(text)) ? 'Copied the terminal text' : 'Copy failed: select the text and use your phone\'s Copy', 3000);
+      d.close();
+    }
+  });
+}
+
+/** Paste: the clipboard into the terminal (one paste, not submitted), or a box to paste into. */
+export async function pasteInto(xterm, { toast }) {
+  try {
+    const text = await navigator.clipboard.readText();
+    if (text) {
+      xterm.paste(text);
+      return;
+    }
+  } catch {
+    // Not allowed here (or refused): fall back to a box the phone can paste into.
+  }
+  const d = sheet(`<div class="clip-head"><b>Paste into the terminal</b><span class="spacer"></span><button type="button" class="small ghost" data-clip="close">Cancel</button></div>
+    <textarea class="clip-box" rows="6" placeholder="Long-press here and choose Paste"></textarea>
+    <div class="clip-foot"><span class="hint">It goes in as typed text; press Enter (⏎) in the terminal when you want it run.</span><button type="button" class="small primary" data-clip="send">Insert</button></div>`);
+  const box = d.querySelector('.clip-box');
+  box.focus();
+  d.addEventListener('click', (e) => {
+    const act = e.target.closest('[data-clip]')?.dataset.clip;
+    if (act === 'close') d.close();
+    if (act === 'send') {
+      if (box.value) xterm.paste(box.value);
+      else toast('Nothing to paste');
+      d.close();
+    }
+  });
+}

package/src/agentkit/agent.js

@@ -0,0 +1,171 @@
+// The agent at work: each input becomes a run of plan → act → check (→ act again on what's left)
+// → reflect, through the engine (engines.js), one run at a time. Runs are logged as JSONL; memory
+// carries lessons between runs; a conversation (a chat, an A2A context) keeps its engine session.
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Approvals } from './approvals.js';
+import { agentPaths } from './spec.js';
+import { APPROVER, approverServer, turn, writeMcpConfig } from './engines.js';
+
+const now = () => new Date().toISOString();
+const readJson = (f, d) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, 'utf8'));
+  } catch {
+    return d;
+  }
+};
+
+/** The check step's verdict, from a reply that should hold {"done": …, "remaining": …}. */
+export function verdictOf(text) {
+  const m = /\{[\s\S]*\}/.exec(String(text ?? ''));
+  try {
+    const j = JSON.parse(m?.[0] ?? '');
+    return { done: j.done === true, remaining: String(j.remaining ?? '').trim() };
+  } catch {
+    // No JSON: read "done" / "not done" in plain words, else assume done (don't loop on noise).
+    return { done: !/\bnot (yet )?(done|met|complete)\b/i.test(String(text)), remaining: '' };
+  }
+}
+
+export class Agent extends EventEmitter {
+  /** `approvals`: 'ask' (a person decides approval tools, where the engine can ask) or 'deny'. */
+  constructor(spec, { env = process.env, engineTurn = turn, approvals = 'ask' } = {}) {
+    super();
+    this.spec = spec;
+    this.env = env;
+    this.engineTurn = engineTurn;
+    this.paths = agentPaths(spec);
+    fs.mkdirSync(this.paths.runs, { recursive: true });
+    this.mcpFile = writeMcpConfig(spec, this.paths.mcp);
+    this.approvals = new Approvals(spec, { timeoutMs: spec.approveTimeoutMs ?? 30 * 60_000 });
+    this.approvals.on('change', () => this.emit('approvals', this.approvals.pending()));
+    // Only Claude can ask mid-run (the others get approval tools taken away instead).
+    this.asks = approvals === 'ask' && spec.engine === 'claude' && spec.approve.length > 0;
+    this.approverReady = false;
+    this.sessions = readJson(this.paths.sessions, {});
+    this.queue = Promise.resolve();
+    this.current = null;
+  }
+
+  memory() {
+    try {
+      return fs.readFileSync(this.paths.memory, 'utf8').trim();
+    } catch {
+      return '';
+    }
+  }
+
+  system() {
+    const s = this.spec;
+    return [
+      `You are "${s.title}", an autonomous agent that works on its own, without a person watching.`,
+      `Your goal:\n${s.goal}`,
+      s.instructions ? `How to do the job:\n${s.instructions}` : '',
+      s.memory && this.memory() ? `What you learned in earlier runs (keep using it):\n${this.memory().slice(-6000)}` : '',
+      'Work in your folder with your tools. Never invent results: if you could not do something, say so plainly.',
+    ]
+      .filter(Boolean)
+      .join('\n\n');
+  }
+
+  /** Queue a run; resolves with its result. `conversation` continues an engine session. */
+  run(input, { source = 'api', conversation = null } = {}) {
+    const job = this.queue.then(() => this.doRun(String(input ?? ''), { source, conversation }));
+    this.queue = job.catch(() => {});
+    return job;
+  }
+
+  async doRun(input, { source, conversation }) {
+    const id = `${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+    const file = path.join(this.paths.runs, `${id}.jsonl`);
+    const t0 = Date.now();
+    let cost = 0;
+    const log = (rec) => {
+      const r = { t: now(), ...rec };
+      fs.appendFileSync(file, JSON.stringify(r) + '\n');
+      this.emit('step', { run: id, ...r });
+    };
+    this.current = { id, source, startedAt: now() };
+    log({ type: 'start', input, source, conversation });
+    let session = conversation ? this.sessions[conversation] ?? null : null;
+    if (this.asks && !this.approverReady) {
+      const url = await this.approvals.address();
+      this.mcpFile = writeMcpConfig(this.spec, this.paths.mcp, { [APPROVER]: approverServer({ url, token: this.approvals.token }) });
+      this.approverReady = true;
+    }
+    this.approvals.run = id;
+    const ask = async (step, prompt) => {
+      const res = await this.engineTurn(this.spec, { prompt, system: this.system(), session, mcpFile: this.mcpFile, approver: this.asks, env: this.env });
+      session = res.session ?? session;
+      if (res.costUsd) cost += res.costUsd;
+      log({ type: step, text: res.text });
+      if (this.spec.loop.budgetUsd && cost > this.spec.loop.budgetUsd) throw new Error(`Over the run budget ($${cost.toFixed(2)} of $${this.spec.loop.budgetUsd})`);
+      return res.text;
+    };
+    let result = '';
+    let status = 'done';
+    try {
+      // Someone asked (chat, API, A2A, ACP, MCP, the command line), or a trigger fired ("every 10m", …).
+      const from = ['chat', 'api', 'a2a', 'acp', 'mcp', 'cli'].includes(source) ? 'a request' : `a trigger (${source})`;
+      // The goal goes in every step, not only the system prompt: the engine's own framing ("a coding
+      // agent") must not turn an input into a different job than this agent's.
+      const goal = `Your goal (this is your whole job): ${this.spec.goal}`;
+      const given = `New input, from ${from}:\n${input || '(none: do your scheduled work)'}`;
+      if (this.spec.loop.plan) await ask('plan', `${goal}\n\n${given}\n\nWrite a short numbered plan to achieve your goal for this input. Treat the input as material for your goal, not as a new assignment. Don't act yet.`);
+      result = await ask('act', this.spec.loop.plan ? `Carry out the plan now. ${goal}\nWhen you are done, reply with the result your goal calls for.` : `${goal}\n\n${given}\n\nTreat the input as material for your goal, not as a new assignment. Do what your goal calls for and reply with the result.`);
+      for (let step = 1; this.spec.loop.check && step < this.spec.loop.maxSteps; step++) {
+        const v = verdictOf(await ask('check', `Check your last result against your goal. ${goal}\nReply with JSON only: {"done": true|false, "remaining": "<what is still missing for the goal, if anything>"}.`));
+        if (v.done) break;
+        result = await ask('act', `Not done yet. Continue with what is left: ${v.remaining || 'finish the remaining work'}. Then reply with the full result.`);
+        if (step === this.spec.loop.maxSteps - 1) status = 'partial';
+      }
+      if (this.spec.memory) {
+        const lesson = (await ask('reflect', 'In at most two short bullet points, what should you remember for next time (about this kind of input, the tools, or the people)? Reply "nothing" if there is nothing new.')).trim();
+        if (lesson && !/^nothing\.?$/i.test(lesson)) fs.appendFileSync(this.paths.memory, `\n## ${now().slice(0, 10)}\n${lesson}\n`);
+      }
+    } catch (err) {
+      status = 'failed';
+      result = result || `The run failed: ${err.message}`;
+      log({ type: 'error', text: err.message });
+    }
+    if (conversation && session) {
+      this.sessions[conversation] = session;
+      fs.writeFileSync(this.paths.sessions, JSON.stringify(this.sessions, null, 2));
+    }
+    const summary = { id, status, result, source, conversation, costUsd: cost ? Math.round(cost * 1e6) / 1e6 : null, ms: Date.now() - t0 };
+    log({ type: 'end', ...summary });
+    this.current = null;
+    this.approvals.run = null;
+    this.emit('run', summary);
+    return summary;
+  }
+
+  close() {
+    this.approvals.close();
+  }
+
+  /** Recent runs, newest first: id, status, source, start time, result (from each log). */
+  runs(limit = 50) {
+    let names = [];
+    try {
+      names = fs.readdirSync(this.paths.runs).filter((n) => n.endsWith('.jsonl')).sort().reverse().slice(0, limit);
+    } catch {}
+    return names.map((n) => this.runLog(n.slice(0, -6))).filter(Boolean).map((steps) => {
+      const start = steps.find((s) => s.type === 'start');
+      const end = steps.find((s) => s.type === 'end');
+      return { id: start?.id ?? end?.id, startedAt: start?.t, source: start?.source, input: start?.input, status: end?.status ?? 'running', result: end?.result ?? null, costUsd: end?.costUsd ?? null };
+    }).map((r, i) => ({ ...r, id: r.id ?? names[i].slice(0, -6) }));
+  }
+
+  runLog(id) {
+    if (!/^[\w-]+$/.test(id)) return null;
+    try {
+      return fs.readFileSync(path.join(this.paths.runs, `${id}.jsonl`), 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    } catch {
+      return null;
+    }
+  }
+}

package/src/agentkit/approvals.js

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

package/src/agentkit/cli.js

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