ai-agentmanager 1.11.1 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.12.0 (2026-11-01)
+
+- **agentkit (phase 1): agents you build and run.** An agent is a folder with `agent.yaml` (goal, instructions, engine, MCP tools, allow/approve lists, triggers, loop, memory, interfaces); `agentkit run <agent>` runs it continuously. Each input is a run of plan → act → check (acting again on what's left, up to `maxSteps`) → reflect into memory, through an engine's CLI (Claude Code, Codex, Muse Code or an ACP agent), self-contained (only its own MCP servers; none of your personal Claude settings). Triggers: `every`, `cron`, `webhook`, `watch`. Interfaces: a chat page and HTTP API, A2A (agent card and `message/send` / `tasks/get`), ACP on stdio (`agentkit acp`), and an MCP tool (`agentkit mcp`, one tool `ask_<name>`). `agentkit init`, `check`, `run --once`. See [docs/agentkit.md](docs/agentkit.md).
+- **Agent builder:** a **Built** tab with **+ Build an agent**: describe a task or workflow (attachments welcome) and pick an engine; one call designs the agent: an analysis (problem, inputs, outputs, risks), its `agent.yaml` and instructions, suggested MCP tools and 3–5 test cases. Review and edit the spec (checked on save), **Run tests** (each through the real runtime, judged against its expectation), **Start** it on this computer (its chat page and API), **Download** its folder. Built agents live in `~/.agentmanager/built/<name>/`; `/api/builder` for scripts.
+- **Single executables and background service for agents:** `agentkit package <agent> [--platform]` makes one file (macOS arm64/x64, Linux x64/arm64) that runs the agent with no Node or agentkit installed: a Node single executable with the agent's files embedded, built on the official Node binary (downloaded from nodejs.org, checksum-verified, cached). Linux ones build on a Mac. The executable unpacks to `~/.agentkit/<name>/` and takes the same commands (`--once`, `acp`, `mcp`, `check`). `service install|status|uninstall` keeps an agent running in the background (launchd or a systemd user service: started at login, restarted after a crash). In the Built tab: **Build executable** for a platform, with download links.
+- **Approvals and monitoring for agents:** tools on an agent's `approve` list now ask a person instead of being unavailable (Claude Code engine, through `--permission-prompt-tool` and the agent's own approver), on its chat page and in AI Agent Manager's **Inbox**; the first answer decides, silence past `approveTimeout` is a no, and the approve list wins over `allow`. Agents report to AI Agent Manager (runs, cost, results, open approvals; every 30s, at once after a run): the **Built** tab lists them under *Reporting in*. Agents started here report automatically; others connect with `AGENTKIT_REPORT_URL`, `AGENTKIT_REPORT_TOKEN` and, over remote access, `AGENTKIT_REPORT_CERT` (certificate pinning).
+
 ## 1.11.1 (2026-11-01)
 
 - **Copy and paste in terminals on phones:** **Copy** and **Paste** in the terminal's key bar (and in the Terminal's bar). A phone can't select the terminal's text or paste into it directly, so Copy opens its recent output as plain text you can select (or **Copy all**), and Paste reads the clipboard (the phone asks first) or offers a box to paste into, then inserts it as one paste without pressing Enter.

package/bin/agentkit.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// agentkit: run an agent described by agent.yaml (docs/agentkit.md).
+//   agentkit run <agent> [--once "<input>"] [--port N]   triggers, chat page, API and A2A; or one run
+//   agentkit acp <agent>                                  ACP on stdio
+//   agentkit mcp <agent>                                  MCP on stdio (one tool: ask_<name>)
+//   agentkit check <agent>                                validate agent.yaml
+//   agentkit init <folder>                                a starter agent to edit
+import { main } from '../src/agentkit/cli.js';
+
+main(process.argv.slice(2));

package/docs/agentkit.md

@@ -0,0 +1,161 @@
+# agentkit: agents you build, download and run
+
+Status: the runtime, the builder (AI Agent Manager's **Built** tab), single executables, the background service, approvals and reporting to AI Agent Manager are in.
+
+An **agentkit agent** is a folder (or one executable made from it) that does one job continuously: triage new
+support tickets, keep a dependency report current, answer questions about a codebase, run a
+release checklist. It is described by `agent.yaml`, runs its work through an engine's CLI (Claude
+Code, Codex, Muse Code or any ACP agent), uses tools through MCP servers, and can be reached by
+people (a chat page, an HTTP API), by other agents (A2A, MCP) and by editors (ACP).
+
+## agent.yaml
+
+```yaml
+name: ticket-triage                 # lowercase, used for files and URLs
+title: Support ticket triage
+description: Reads new tickets, labels and routes them, drafts a first reply.
+goal: |
+  Every new ticket is labelled, routed to the right team and has a drafted first reply
+  within 10 minutes, without closing or replying on its own.
+instructions: instructions.md       # or inline text: how to do the job, step by step
+engine: claude                      # claude | codex | muse | acp:<name>
+model: sonnet                       # optional, passed to the engine
+workdir: ./work                     # where it works (a repo, a folder); default ./work
+
+tools:                              # MCP servers the engine gets
+  jira:
+    command: npx
+    args: [-y, "@acme/jira-mcp"]
+    env: { JIRA_TOKEN: "${JIRA_TOKEN}" }  # "${VAR}" (quoted) comes from the environment, never stored
+allow: [Read, Grep, "mcp__jira__*"] # tools it may use without asking (engine names)
+approve: ["mcp__jira__transition"]  # tools that need a person's yes (asked in chat / Inbox)
+approveTimeout: 30m                 # no answer by then counts as no
+report:                             # report to AI Agent Manager (or set AGENTKIT_REPORT_*)
+  url: "${AGENTMGR_URL}"
+  token: "${AGENTMGR_REPORT_TOKEN}"
+
+triggers:
+  - every: 10m                      # interval
+  - cron: "0 9 * * 1-5"             # schedule (minute hour day month weekday)
+  - webhook: /hooks/ticket          # POST here starts a run with the body as input
+  - watch: ./inbox                  # a new or changed file starts a run
+
+loop:
+  plan: true                        # think and write a plan before acting
+  check: true                       # verify the result against the goal after acting
+  maxSteps: 6                       # act/check rounds per run before stopping
+  budgetUsd: 0.50                   # per run (when the engine reports cost)
+
+memory: true                        # keep notes between runs (memory.md)
+
+interfaces:
+  http: { port: 7700 }              # chat page + API
+  a2a: true                         # agent card + tasks over HTTP
+  acp: true                         # `<agent> acp` speaks ACP on stdio
+  mcp: true                         # `<agent> mcp` exposes it as an MCP tool
+```
+
+## A run
+
+1. **Input** arrives: a trigger fires (with its payload), someone chats, an A2A task or an MCP
+   call comes in.
+2. **Plan** (when `loop.plan`): the engine reads the goal, instructions, memory and input and
+   writes a short plan.
+3. **Act**: the engine carries out the plan with its tools (MCP), in `workdir`.
+4. **Check** (when `loop.check`): the engine is asked whether the goal is met for this input,
+   and what's left. If not and steps remain, it acts again on what's left.
+5. **Reflect** (when `memory`): one or two lessons for next time are appended to memory.
+6. **Result**: the final answer goes back to whoever asked; the run (steps, output, cost,
+   duration) is logged in `runs/<id>.jsonl`.
+
+The engine keeps one session per conversation (a chat, an A2A context), so follow-ups continue
+it. Runs from triggers start fresh sessions.
+
+## Interfaces
+
+- **HTTP**: `GET /` chat page; `POST /api/chat {message, conversation?}`; `POST /api/runs {input}`;
+  `GET /api/runs`, `GET /api/runs/:id`; `GET /api/health`.
+- **A2A**: agent card at `GET /.well-known/agent.json`; JSON-RPC at `POST /a2a` with
+  `message/send` and `tasks/get`.
+- **ACP**: `<agent> acp` runs an ACP agent on stdio (initialize, session/new, session/prompt,
+  streamed session/update), so editors (and AI Agent Manager's ACP engine) can drive it.
+- **MCP**: `<agent> mcp` runs an MCP server on stdio with one tool, `ask_<name>`, so other
+  agents can delegate to it.
+
+## Running
+
+`agentkit run ./ticket-triage` (or, packaged, `./ticket-triage`) starts it in the foreground:
+triggers, the HTTP server, the loop. `agentkit run … --once "<input>"` does one run and prints
+the result.
+
+In the background: `agentkit service install ./ticket-triage` (packaged: `./ticket-triage service
+install`) registers it with launchd (macOS) or systemd (Linux, a user service): it starts at login,
+restarts after a crash, and writes to `agent.log` in its folder. It runs through your login shell,
+so it finds the engine CLIs and tokens your terminal has. `service status` and `service uninstall`
+do the rest. On Linux, `loginctl enable-linger $USER` keeps it running while you're logged out.
+
+## One executable
+
+`agentkit package ./ticket-triage [--platform linux-x64] [-o dist]` makes one file that runs the
+agent with no Node or agentkit installed: `ticket-triage-macos-arm64`, `-macos-x64`,
+`-linux-x64` or `-linux-arm64` (about 110 MB; Windows isn't supported yet). It is a Node single
+executable application: the runtime bundled, the agent's files (`agent.yaml`, instructions,
+tests) embedded, injected into the official Node binary for that platform (downloaded once from
+nodejs.org, checked against its published checksums, cached in `~/.agentmanager/node-dist`).
+Linux executables build on any Mac or Linux machine; macOS ones are signed, so they build on a Mac.
+
+On its first run, the executable unpacks its files to `~/.agentkit/<name>/` (or `AGENTKIT_HOME`),
+where its memory and runs live too. Edits there stay until a newer build of the agent replaces the
+files it shipped. Everything else works as with the folder: `./ticket-triage` (run),
+`--once "<input>"`, `acp`, `mcp`, `check`, `service install`. Its engine's CLI (Claude Code, Codex
+or Muse Code) must be installed and signed in where it runs. ACP engines aren't packaged yet.
+
+In AI Agent Manager, a built agent's dialog has **Build executable** (pick the platform) and a
+download link for each one built. Editing the agent drops the old executables.
+
+## Approvals
+
+A tool on the `approve` list runs only after a person says yes. The approve list wins over
+`allow`: with `allow: ["mcp__jira__*"]` and `approve: ["mcp__jira__transition"]`, every Jira tool
+runs freely except transitions, which ask.
+
+With Claude Code as the engine, the agent passes `--permission-prompt-tool` to point Claude at a
+small MCP server of its own (the approver). Claude asks the approver before any tool it isn't
+allowed outright. The approver hands the question to the running agent over a private local
+address, and the agent asks whoever can answer:
+
+- **its chat page**, which shows *Approve …?* with the tool's input and Approve / Deny buttons
+  (`GET /api/approvals`, `POST /api/approvals/<id>` with `{"allow": true}`);
+- **AI Agent Manager**, when the agent reports there: the request shows up in the **Inbox** and the
+  **Built** tab, and the answer goes back with the agent's next check-in (every 2 seconds while
+  something waits).
+
+The first answer decides. No answer within `approveTimeout` (default 30m) counts as no, and so does
+having no one to ask (no chat page, not reporting). Tools on neither list are refused without
+asking. Other engines can't ask mid-run, so for them approval tools aren't available at all. Test
+runs in the builder never wait for anyone.
+
+## Reporting to AI Agent Manager
+
+An agent that reports sends AI Agent Manager who it is (name, host, engine, triggers, chat
+address), each run (status, source, cost, time, the start of its result) and the approvals it's
+waiting on. It checks in every 30 seconds, and right away after a run or a new approval. The
+**Built** tab lists these agents under *Reporting in*: online or last seen, idle or working, runs,
+failures and total cost, recent runs, and approvals to answer. Runs are counted once; the list is
+kept across restarts.
+
+Agents started from the Built tab report automatically. For one running elsewhere (a packaged
+executable on a server, a folder on another Mac), **Connect one from elsewhere** shows what to set
+in its environment (or its service):
+
+```
+AGENTKIT_REPORT_URL=https://192.168.1.20:4718     # AI Agent Manager's remote-access address
+AGENTKIT_REPORT_TOKEN=…                           # the report token (made on first use)
+AGENTKIT_REPORT_CERT=AB:CD:…                      # its certificate's SHA-256 fingerprint
+```
+
+Remote access uses a self-signed certificate, so the agent trusts exactly that certificate (by
+its fingerprint) and sends nothing until the fingerprint matches. The connection details are shown
+only on the computer AI Agent Manager runs on. The report token lets a program report as an agent
+and receive the decisions made for it, and nothing else in AI Agent Manager; keep it like a
+password (give each computer the same one, or rotate it by deleting `~/.agentmanager/agentkit-reports.json`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",
@@ -23,7 +23,8 @@
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "agentmgr": "bin/agentmgr.js"
+    "agentmgr": "bin/agentmgr.js",
+    "agentkit": "bin/agentkit.js"
   },
   "files": [
     "bin",
@@ -51,11 +52,14 @@
     "@xterm/xterm": "^6.0.0",
     "commander": "^15.0.0",
     "dompurify": "^3.4.17",
+    "esbuild": "^0.25.12",
     "express": "^5.2.1",
     "marked": "^18.0.14",
     "mermaid": "^12.2.0",
     "node-pty": "^1.1.0",
+    "postject": "^1.0.0-alpha.6",
     "qrcode": "^1.5.4",
-    "ws": "^8.22.0"
+    "ws": "^8.22.0",
+    "yaml": "^2.9.1"
   }
 }

package/public/app.js

@@ -7,6 +7,7 @@ import { openStream, post, REMOTE } from '/transport.js';
 import { attachBox } from '/attach.js';
 import { initSide } from '/side.js';
 import { openCopy, pasteInto } from '/termclip.js';
+import { initBuilt } from '/built.js';
 import { addTools, download, htmlFile, initExport } from '/export.js';
 import { badgeHtml as scoreBadge, scorecardHtml, scorecardSpeech } from '/scorecard.js';
 import { bindListen, listenHtml, play, speakable, now as speaking, stop as stopSpeaking } from '/speak.js';
@@ -125,6 +126,8 @@ $('#new-playbook').onclick = () => {
   playbooksUi.open({ intent: f.intents.value.trim(), projects: f.project.value.trim() ? [f.project.value.trim()] : [], model: f.model.value.trim(), permissionMode: f.permissionMode.value });
 };
 $('#triggers-open').onclick = () => triggersUi.open();
+let builtReports = []; // agents built with agentkit that report here (runs, approvals)
+const builtUi = initBuilt({ api, esc, toast, $, isOpen: () => sideTab === 'built', setCount: (n) => ($('#built-count').textContent = n), reports: () => builtReports });
 const landUi = initLand({ api, esc, toast, agents, $, scoreBadge, select: (id) => (showTab('agents'), select(id)), openReview: (id) => reviewUi.open(id), isOpen: () => sideTab === 'land' });
 
 function statusOf(a) {
@@ -922,6 +925,8 @@ function showTab(tab) {
   $('#backlog-view').hidden = tab !== 'backlog';
   $('#inbox-view').hidden = tab !== 'inbox';
   $('#land-view').hidden = tab !== 'land';
+  $('#built-view').hidden = tab !== 'built';
+  if (tab === 'built') builtUi.load();
   if (tab === 'inbox') loadJudge();
   if (tab === 'land') landUi.load();
   renderBacklog();
@@ -1001,7 +1006,7 @@ function flags(a) {
 }
 
 const TRIAGED = { now: 'sent (AI: urgent)', digest: 'held for the digest', skip: 'dropped by the AI judge' };
-const NEED_ORDER = { prompt: 0, waiting: 1, plan: 1, question: 1, team: 1, review: 2, stuck: 3, conflict: 4 };
+const NEED_ORDER = { approval: 0, prompt: 0, waiting: 1, plan: 1, question: 1, team: 1, review: 2, stuck: 3, conflict: 4 };
 /** What an agent needs from the user. `both`: overlaps on both agents (detail), else only the one that should rebase (inbox). */
 function needsFor(a, { both = false } = {}) {
   const items = [];
@@ -1021,23 +1026,34 @@ function teamNeeds() {
     .filter((t) => ['ready', 'blocked'].includes(t.stage) && agents.has(teamOwner(t)))
     .map((t) => ({ a: agents.get(teamOwner(t)), kind: 'team', key: `team:${t.id}`, t }));
 }
+/** Tools that built agents (agentkit) wait to run until someone approves. */
+function approvalNeeds() {
+  return builtReports.flatMap((r) => r.pending.map((p) => ({ a: { id: r.key, name: r.title, priority: 1 }, kind: 'approval', key: `approval:${r.key}:${p.id}`, r, p })));
+}
 function inboxItems() {
-  return [...[...agents.values()].flatMap((a) => needsFor(a)), ...teamNeeds()]
+  return [...approvalNeeds(), ...[...agents.values()].flatMap((a) => needsFor(a)), ...teamNeeds()]
     .sort((x, y) => NEED_ORDER[x.kind] - NEED_ORDER[y.kind] || (x.a.priority ?? 2) - (y.a.priority ?? 2));
 }
 
-const NEED_LABEL = { team: 'Team', prompt: 'Needs input', waiting: 'Waiting on you', plan: 'Plan review', question: 'Question', review: 'AI review', stuck: 'Stuck?', conflict: 'Overlap' };
+const NEED_LABEL = { approval: 'Approval', team: 'Team', prompt: 'Needs input', waiting: 'Waiting on you', plan: 'Plan review', question: 'Question', review: 'AI review', stuck: 'Stuck?', conflict: 'Overlap' };
 /** Why the AI judge thinks so, as a small tag. */
 const aiTag = (confidence, what = 'AI') => `<span class="tag ai" title="Judged by a model from the agent's activity; your reactions tune later calls">🤖 ${what}${confidence != null ? ` ${Math.round(confidence * 100)}%` : ''}</span>`;
 function needCard(it, { inDetail = false } = {}) {
   const { a } = it;
   const who = inDetail
     ? ''
+    : it.kind === 'approval'
+    ? `<a href="#" class="need-agent" data-ib="built-open">⚙ ${esc(a.name)}</a> <span class="hint">${esc(it.r.host)}</span>`
     : `<a href="#${a.id}" class="need-agent" data-goto="${a.id}">${prioChip(a.priority ?? 2)}${esc(a.name)}</a>${a.projectInfo?.name ? ` <span class="hint">${esc(a.projectInfo.name)}</span>` : ''}`;
   const head = `<div class="need-head"><span class="need-kind ${it.kind}">${NEED_LABEL[it.kind]}</span>${who}</div>`;
   const draft = (k, fallback = '') => esc(needDrafts.get(`${it.key}:${k}`) ?? fallback);
   let body = '';
-  if (it.kind === 'prompt') {
+  if (it.kind === 'approval') {
+    const p = it.p;
+    body = `<p class="need-title">Wants to run <code>${esc(p.tool)}</code> <span class="hint">asked ${ago(p.at)}</span></p>
+      <pre class="need-input">${esc(JSON.stringify(p.input, null, 2).slice(0, 1500))}</pre>
+      <div class="need-actions"><button class="small primary" data-ib="approve" data-allow="1">Approve</button><button class="small" data-ib="approve">Deny</button>${it.r.chat ? `<a class="button small ghost" href="${esc(it.r.chat)}" target="_blank" rel="noopener">Its chat ↗</a>` : ''}</div>`;
+  } else if (it.kind === 'prompt') {
     const p = a.runtime.prompt;
     body = `<p class="need-title">${esc(p?.question || a.runtime.attention)}</p>
       <div class="need-actions">
@@ -1141,7 +1157,7 @@ function judgeLine() {
 
 function renderInbox() {
   const items = inboxItems();
-  const urgent = items.filter((i) => i.kind === 'prompt' || i.kind === 'question' || i.kind === 'waiting').length;
+  const urgent = items.filter((i) => i.kind === 'approval' || i.kind === 'prompt' || i.kind === 'question' || i.kind === 'waiting').length;
   $('#inbox-count').textContent = items.length ? String(items.length) : '';
   $('#inbox-count').className = `badge ${urgent ? 'attention' : ''}`;
   if (sideTab !== 'inbox') return;
@@ -1175,6 +1191,14 @@ async function onNeed(e) {
   const id = card.dataset.agent;
   const key = card.dataset.need;
   switch (el.dataset.ib) {
+    case 'built-open':
+      return showTab('built');
+    case 'approve': {
+      const [, , pid] = key.match(/^approval:(.+):([^:]+)$/);
+      return act(async () => {
+        await api('POST', `/agentkit/agents/${encodeURIComponent(id)}/approvals/${encodeURIComponent(pid)}`, { allow: el.dataset.allow === '1' });
+      }, el.dataset.allow === '1' ? 'Approved; the agent goes on' : 'Declined');
+    }
     case 'key':
       return act(() => api('POST', `/agents/${id}/prompt-key`, { key: el.dataset.key }), 'Sent');
     case 'terminal':
@@ -3604,6 +3628,8 @@ function handleEvent(msg) {
     for (const r of msg.races ?? []) races.set(r.id, r);
     teams.clear();
     for (const t of msg.teams ?? []) teams.set(t.id, t);
+    builtReports = msg.built ?? [];
+    builtUi.render();
     msg.agents.forEach(watchDocs);
     if (selectedId && !agents.has(selectedId)) selectedId = null;
     if (openTermOnLoad && selectedId) {
@@ -3626,6 +3652,9 @@ function handleEvent(msg) {
     teams.set(msg.team.id, msg.team);
   } else if (msg.t === 'team-removed') {
     teams.delete(msg.id);
+  } else if (msg.t === 'built') {
+    builtReports = msg.reports;
+    builtUi.render();
   } else if (msg.t === 'backlog') {
     backlogState = msg.backlog;
   } else if (msg.t === 'projects') {

package/public/built.js

@@ -0,0 +1,207 @@
+// The Built tab: agents made with the builder (agentkit agents, docs/agentkit.md). Build one from
+// a task; review its analysis, spec and tests; test it; run it here; open its chat; download it.
+import { attachBox } from '/attach.js';
+
+const STATUS = { designed: 'designed', 'needs-fixing': 'needs fixing', testing: 'testing…', tested: 'tests pass', failing: 'tests fail', running: 'running' };
+
+const ago = (iso) => {
+  const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+  return s < 60 ? 'just now' : s < 3600 ? `${Math.round(s / 60)} min ago` : s < 86400 ? `${Math.round(s / 3600)} h ago` : `${Math.round(s / 86400)} d ago`;
+};
+
+export function initBuilt({ api, esc, toast, $, isOpen, setCount, reports = () => [] }) {
+  const view = $('#built-view');
+  const dlg = $('#built-dialog');
+  const body = $('#built-body');
+  let list = [];
+  let open = null; // the built agent shown in the dialog
+  let poll = null;
+
+  async function load() {
+    try {
+      list = await api('GET', '/builder');
+    } catch {
+      list = [];
+    }
+    setCount(list.length || '');
+    if (isOpen()) render();
+  }
+
+  function render() {
+    view.innerHTML = `<div class="built-head"><button class="small primary" data-bt="new">+ Build an agent</button><span class="hint">An agent for a task or workflow: it plans, acts, checks itself and keeps working in the background.</span></div>
+      ${list.length ? `<ul class="built-list">${list.map((b) => `<li data-bt-open="${esc(b.name)}"><div class="line1"><b>${esc(b.title ?? b.name)}</b>${b.running ? ' <span class="dot-run" title="Running">●</span>' : ''}<span class="spacer"></span><span class="tag ${b.status === 'tested' ? 'open' : b.status === 'failing' || b.status === 'needs-fixing' ? 'fail' : ''}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span></div>
+        <div class="hint">${esc(b.name)} · ${esc(b.engine ?? '')}${b.results?.total ? ` · tests ${b.results.passed}/${b.results.total}` : ''}${b.triggers.length ? ` · ${esc(b.triggers.join(', '))}` : ''}</div></li>`).join('')}</ul>` : '<p class="hint built-empty">No agents built yet.</p>'}
+      ${reporting()}`;
+  }
+
+  // ------------------------------------------------------------ agents reporting in (here or elsewhere)
+  function reporting() {
+    const rs = reports();
+    const head = `<div class="built-head reporting-head"><b>Reporting in</b><span class="hint">Agents running here or on other computers: their runs, cost and the tools they wait to have approved.</span><span class="spacer"></span><button class="small ghost" data-bt="connect">Connect one from elsewhere</button></div><div id="built-connect" ${connectHtml ? '' : 'hidden'}>${connectHtml ?? ''}</div>`;
+    if (!rs.length) return `${head}<p class="hint built-empty">None yet. Agents you start here report automatically.</p>`;
+    return `${head}<ul class="built-list reports">${rs.map((r) => `<li data-report="${esc(r.key)}">
+      <div class="line1"><span class="dot-run ${r.online ? '' : 'off'}" title="${r.online ? 'Online' : 'Not heard from'}">●</span> <b>${esc(r.title)}</b> <span class="hint">${esc(r.host)}</span><span class="spacer"></span>
+        ${r.chat && r.online ? `<a class="button small ghost" href="${esc(r.chat)}" target="_blank" rel="noopener">Chat ↗</a>` : ''}
+        <button class="small ghost" data-rp="forget" title="Remove it from this list (it shows up again when it reports)">Forget</button></div>
+      <div class="hint">${esc(r.engine)} · ${r.online ? (r.current ? `working on a run (${esc(r.current.source)})` : 'idle') : `last seen ${ago(r.lastSeen)}`} · ${r.totals.runs} run${r.totals.runs === 1 ? '' : 's'}${r.totals.failed ? `, ${r.totals.failed} failed` : ''}${r.totals.costUsd ? ` · $${r.totals.costUsd.toFixed(2)}` : ''}${r.triggers.length ? ` · ${esc(r.triggers.join(', '))}` : ''}</div>
+      ${r.pending.map((p) => `<div class="report-approval" data-ap="${esc(p.id)}"><b>Wants to run <code>${esc(p.tool)}</code></b> <span class="hint">${ago(p.at)}</span><pre>${esc(JSON.stringify(p.input, null, 2).slice(0, 1500))}</pre><button class="small primary" data-rp="approve">Approve</button> <button class="small" data-rp="deny">Deny</button></div>`).join('')}
+      ${r.runs.length ? `<details><summary class="hint">Recent runs</summary><ul class="built-runs">${r.runs.map((x) => `<li><span class="tag ${x.status === 'failed' ? 'fail' : x.status === 'done' ? 'open' : ''}">${esc(x.status)}</span> <span class="hint">${esc(x.source)} · ${x.at ? ago(x.at) : ''}${x.costUsd ? ` · $${x.costUsd.toFixed(3)}` : ''}${x.ms ? ` · ${Math.round(x.ms / 1000)}s` : ''}</span><div>${esc(x.result.slice(0, 400))}</div></li>`).join('')}</ul></details>` : ''}
+    </li>`).join('')}</ul>`;
+  }
+
+  let connectHtml = null; // the connection details, kept open across live re-renders
+  async function connect() {
+    const box = $('#built-connect');
+    if (connectHtml) return (connectHtml = null), (box.hidden = true);
+    try {
+      const c = await api('GET', '/agentkit/connect');
+      const lines = (url, cert) => [`AGENTKIT_REPORT_URL=${url}`, `AGENTKIT_REPORT_TOKEN=${c.token}`, ...(cert ? [`AGENTKIT_REPORT_CERT=${cert}`] : [])].join('\n');
+      box.innerHTML = `<p class="hint">Set these where the agent runs (in its environment, or in its service), then start it. It reports here and asks here for approvals.</p>
+        ${c.remote.length ? c.remote.map((u) => `<p><b>From another computer</b> <span class="hint">(over remote access)</span></p><pre class="code-area">${esc(lines(u.replace(/\/$/, ''), c.cert))}</pre>`).join('') : '<p class="hint">Turn on remote access (Settings) to connect agents on other computers.</p>'}
+        <p><b>On this computer</b></p><pre class="code-area">${esc(lines(c.local))}</pre>`;
+    } catch (err) {
+      box.innerHTML = `<p class="hint">${esc(err.message)}. Open AI Agent Manager on this computer to see the connection details.</p>`;
+    }
+    connectHtml = box.innerHTML;
+    box.hidden = false;
+  }
+
+  // ------------------------------------------------------------ build
+  const buildDlg = $('#build-dialog');
+  const files = attachBox({ slot: $('#build-attach'), form: $('#build-form'), paste: $('#build-form textarea'), esc, toast });
+  async function openBuild() {
+    const sel = $('#build-form').engine;
+    if (sel.options.length <= 1) {
+      const engines = await api('GET', '/engines').catch(() => []);
+      for (const e of engines.filter((x) => x.installed && x.id !== 'claude')) sel.append(Object.assign(document.createElement('option'), { value: e.id.startsWith('acp-') ? `acp:${e.id.slice(4)}` : e.id, textContent: e.label }));
+    }
+    $('#build-error').hidden = true;
+    buildDlg.showModal();
+    $('#build-form textarea').focus();
+  }
+  $('#build-form').addEventListener('submit', async (e) => {
+    e.preventDefault();
+    const f = e.target;
+    if (files.pending()) return toast('Still uploading the attached files');
+    const btn = f.querySelector('button[type=submit]');
+    btn.disabled = true;
+    btn.textContent = 'Designing… (about a minute)';
+    try {
+      const b = await api('POST', '/builder', { task: f.task.value, engine: f.engine.value, attachments: files.paths().length ? files.paths() : undefined });
+      buildDlg.close();
+      f.reset();
+      files.clear();
+      await load();
+      show(b);
+    } catch (err) {
+      $('#build-error').textContent = err.message;
+      $('#build-error').hidden = false;
+    } finally {
+      btn.disabled = false;
+      btn.textContent = 'Design the agent';
+    }
+  });
+  $('#build-cancel').onclick = () => buildDlg.close();
+
+  // ------------------------------------------------------------ one agent
+  function show(b) {
+    open = b;
+    $('#built-title').textContent = b.title ?? b.name;
+    const a = b.analysis ?? {};
+    const li = (xs) => (xs?.length ? `<ul>${xs.map((x) => `<li>${esc(x)}</li>`).join('')}</ul>` : '<p class="hint">—</p>');
+    const r = b.results;
+    body.innerHTML = `
+      <div class="built-actions">
+        <span class="tag ${b.status === 'tested' ? 'open' : b.status === 'failing' || b.status === 'needs-fixing' ? 'fail' : ''}">${esc(b.pending ?? STATUS[b.status] ?? b.status)}</span>
+        ${b.running ? `<span class="hint">running since ${new Date(b.running.since).toLocaleTimeString()}</span>${b.running.url ? ` <a href="${esc(b.running.url)}" target="_blank" rel="noopener">Open its chat ↗</a>` : ''}` : ''}
+        <span class="spacer"></span>
+        <button class="small" data-bt="test" ${b.pending ? 'disabled' : ''} title="Run each test through the real engine and judge the results">${b.pending === 'testing' ? 'Testing…' : 'Run tests'}</button>
+        <button class="small ${b.running ? '' : 'primary'}" data-bt="${b.running ? 'stop' : 'start'}" ${b.specError ? 'disabled' : ''} title="${b.running ? 'Stop it' : 'Run it continuously on this computer: its triggers, chat page and API'}">${b.running ? 'Stop' : 'Start'}</button>
+        <a class="button small ghost" href="/api/builder/${esc(b.name)}/download" title="Its folder (agent.yaml, instructions, tests) to run anywhere with agentkit">Download folder</a>
+        <button class="small ghost" data-bt="delete">Delete</button>
+      </div>
+      <div class="built-exe"><b>Single executable</b> <span class="hint">one file that runs this agent anywhere, no Node or agentkit needed (its engine's CLI must be installed and signed in)</span>
+        <div class="built-exe-row"><select id="built-platform">${(b.platforms ?? []).map((p) => `<option value="${esc(p)}" ${p === b.host ? 'selected' : ''}>${esc(p)}${p === b.host ? ' (this computer)' : ''}</option>`).join('')}</select>
+        <button class="small" data-bt="package" ${b.pending || b.specError ? 'disabled' : ''}>${b.pending?.startsWith('packaging') ? 'Building… (a minute or two)' : 'Build executable'}</button>
+        ${Object.entries(b.executables ?? {}).map(([p, x]) => `<a class="button small ghost" href="/api/builder/${esc(b.name)}/executable/${esc(p)}" title="Built ${esc(new Date(x.at).toLocaleString())}">⬇ ${esc(p)} · ${Math.round(x.size / 1e6)} MB</a>`).join('')}</div>
+        ${b.packageError ? `<p class="error">${esc(b.packageError)}</p>` : ''}</div>
+      ${b.specError ? `<p class="error">${esc(b.specError)}</p>` : ''}
+      ${b.missingEnv.length ? `<p class="hint warn">Set these in the environment before running it: ${esc(b.missingEnv.join(', '))}</p>` : ''}
+      <details open><summary><b>Analysis</b></summary><p>${esc(a.problem ?? '')}</p><div class="row three"><div><b>Inputs</b>${li(a.inputs)}</div><div><b>Outputs</b>${li(a.outputs)}</div><div><b>Risks</b>${li(a.risks)}</div></div>
+        ${b.tools?.length ? `<p><b>Tools</b></p><ul>${b.tools.map((t) => `<li><code>${esc(t.name)}</code> ${esc(t.why)}</li>`).join('')}</ul>` : ''}</details>
+      <details ${r ? 'open' : ''}><summary><b>Tests</b> ${r?.total ? `<span class="hint">${r.passed}/${r.total} pass · ${new Date(r.at).toLocaleString()}</span>` : '<span class="hint">not run yet</span>'}</summary>
+        ${r?.error ? `<p class="error">${esc(r.error)}</p>` : ''}
+        <ol class="built-tests">${(r?.list?.length ? r.list : b.tests ?? []).map((t) => `<li class="${t.pass === true ? 'pass' : t.pass === false ? 'fail' : ''}"><div><b>${t.pass === true ? '✓' : t.pass === false ? '✗' : '·'}</b> ${esc(t.input)}</div><div class="hint">Expect: ${esc(t.expect)}</div>${t.why ? `<div class="hint">${esc(t.why)}</div>` : ''}${t.result ? `<details><summary class="hint">Result</summary><pre>${esc(t.result)}</pre></details>` : ''}</li>`).join('')}</ol></details>
+      <details><summary><b>agent.yaml</b> and instructions</summary>
+        <textarea id="built-yaml" class="code-area" rows="16" spellcheck="false">${esc(b.yaml)}</textarea>
+        <textarea id="built-instr" class="code-area" rows="10" spellcheck="false">${esc(b.instructionsText)}</textarea>
+        <div class="dialog-actions"><button class="small primary" data-bt="save">Save</button></div></details>
+      ${b.runs.length ? `<details><summary><b>Recent runs</b></summary><ul class="built-runs">${b.runs.map((x) => `<li><span class="tag">${esc(x.status)}</span> <span class="hint">${esc(x.source ?? '')} · ${x.startedAt ? new Date(x.startedAt).toLocaleString() : ''}</span><div>${esc(String(x.result ?? '').slice(0, 300))}</div></li>`).join('')}</ul></details>` : ''}
+      <p class="hint">Task: ${esc(b.task ?? '')}</p>`;
+    if (!dlg.open) dlg.showModal();
+    clearInterval(poll);
+    if (b.pending) poll = setInterval(refresh, 3000);
+  }
+
+  async function refresh() {
+    if (!open || !dlg.open) return clearInterval(poll);
+    try {
+      const b = await api('GET', `/builder/${open.name}`);
+      if (b.pending !== open.pending || b.updatedAt !== open.updatedAt) show(b);
+      if (!b.pending) clearInterval(poll), load();
+    } catch {}
+  }
+
+  async function act(what) {
+    const name = open?.name;
+    try {
+      if (what === 'test') show(await api('POST', `/builder/${name}/test`));
+      else if (what === 'package') show(await api('POST', `/builder/${name}/package`, { platform: $('#built-platform').value }));
+      else if (what === 'start') {
+        show(await api('POST', `/builder/${name}/start`));
+        setTimeout(refresh, 1500);
+      } else if (what === 'stop') show(await api('POST', `/builder/${name}/stop`));
+      else if (what === 'save') {
+        show(await api('PUT', `/builder/${name}`, { yaml: $('#built-yaml').value, instructions: $('#built-instr').value }));
+        toast('Saved');
+      } else if (what === 'delete') {
+        if (!confirm(`Delete ${name} and its folder?`)) return;
+        await api('DELETE', `/builder/${name}`);
+        dlg.close();
+      }
+      load();
+    } catch (err) {
+      toast(`Error: ${err.message}`, 6000);
+    }
+  }
+
+  view.addEventListener('click', async (e) => {
+    if (e.target.closest('[data-bt="new"]')) return openBuild();
+    if (e.target.closest('[data-bt="connect"]')) return connect();
+    const rp = e.target.closest('[data-rp]');
+    if (rp) {
+      const key = rp.closest('[data-report]').dataset.report;
+      try {
+        if (rp.dataset.rp === 'forget') await api('DELETE', `/agentkit/agents/${encodeURIComponent(key)}`);
+        else {
+          rp.disabled = true;
+          await api('POST', `/agentkit/agents/${encodeURIComponent(key)}/approvals/${encodeURIComponent(rp.closest('[data-ap]').dataset.ap)}`, { allow: rp.dataset.rp === 'approve' });
+          toast(rp.dataset.rp === 'approve' ? 'Approved; the agent goes on' : 'Declined');
+        }
+      } catch (err) {
+        toast(`Error: ${err.message}`, 6000);
+      }
+      return;
+    }
+    const li = e.target.closest('[data-bt-open]');
+    if (li) show(await api('GET', `/builder/${li.dataset.btOpen}`));
+  });
+  body.addEventListener('click', (e) => {
+    const b = e.target.closest('[data-bt]');
+    if (b) act(b.dataset.bt);
+  });
+  $('#built-close').onclick = () => (clearInterval(poll), dlg.close());
+
+  load();
+  return { load, render };
+}

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>
@@ -377,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>

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; }
@@ -949,3 +950,26 @@ body.remote .settings-links .local-only { display: none; }
 .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); }