ai-agentmanager 1.10.0 → 1.11.0

package/public/index.html

@@ -245,6 +245,10 @@
           <input type="checkbox" name="worktree" checked />
           Give each agent its own git worktree and branch <span class="hint">(for a git folder; always on when cloning a repo URL)</span>
         </label>
+        <label class="check" id="container-field" hidden title="The agent sees only its own folder, its git data, brief and uploads, not the rest of this computer. Claude Code and Codex">
+          <input type="checkbox" name="container" />
+          Run each agent in its own container <span class="hint" id="container-hint">(Docker: it sees only its own folder)</span>
+        </label>
         <label class="check">
           <input type="checkbox" name="plan" checked />
           Plan with Claude while the repo clones <span class="hint">(repo URLs only; the session moves into the repo when it's ready)</span>
@@ -722,6 +726,15 @@
           <label class="check"><input type="checkbox" name="startAtLogin" /> Start AI Agent Manager when I log in</label>
           <p class="hint">After a restart or a crash, the daemon comes back by itself and running agents resume; without it, it starts only when you run <code>agentmgr</code>. <span id="settings-service-state"></span></p>
         </fieldset>
+        <fieldset class="local-only" id="settings-containers">
+          <legend>Containers</legend>
+          <p class="hint">Agents in a container (Docker) see only their own folder, its git data, brief and uploads: not the rest of this computer. <span id="settings-containers-state"></span></p>
+          <div class="row">
+            <label>Claude token for containers <span class="hint">run <code>claude setup-token</code> in a terminal and paste it</span><input name="claudeToken" type="password" autocomplete="new-password" /></label>
+            <div class="containers-actions"><button type="button" class="small" id="containers-build">Build image</button></div>
+          </div>
+          <label class="check"><input type="checkbox" name="containerDefault" /> Run new agents in containers by default</label>
+        </fieldset>
         <fieldset class="local-only">
           <legend>Jira</legend>
           <p class="hint">For an agent created from a Jira link, its description shows the issue's summary. Public issues on Atlassian Cloud need nothing here; for your company's site, add it with your email and an <a href="https://id.atlassian.com/manage-profile/security/api-tokens" target="_blank" rel="noopener">API token</a>. The token is kept on this computer and sent only to that site.</p>
@@ -738,7 +751,7 @@
         </fieldset>
         <fieldset>
           <legend>More</legend>
-          <p class="hint settings-links"><button type="button" class="link" data-open="cleanup-btn">Clean up old agents</button> · <button type="button" class="link" data-open="spend-btn">Spend and budgets</button> · <button type="button" class="link local-only" data-open="alerts-btn">Slack alerts</button> · <button type="button" class="link local-only" data-open="remote-btn">Remote access</button></p>
+          <p class="hint settings-links"><button type="button" class="link" data-open="cleanup-btn">Clean up old agents</button><button type="button" class="link" data-open="spend-btn">Spend and budgets</button><button type="button" class="link local-only" data-open="alerts-btn">Slack alerts</button><button type="button" class="link local-only" data-open="remote-btn">Remote access</button></p>
         </fieldset>
         <p id="settings-error" class="error" hidden></p>
         <div class="dialog-actions">

package/public/menu.js

@@ -55,6 +55,36 @@ export function initMenu({ api, esc, toast, $ }) {
   const form = $('#settings-form');
   let service = null; // the login service as the dialog opened
   let jira = null; // the Jira settings as the dialog opened
+  let containers = null; // Docker and the agent image as the dialog opened
+  function showContainers() {
+    const c = containers;
+    $('#settings-containers').hidden = !c;
+    if (!c) return;
+    $('#settings-containers-state').textContent = !c.available
+      ? `Docker isn't running here${c.error ? ` (${c.error})` : ''}.`
+      : `Docker ${c.version} · image ${c.image}: ${c.building ? 'building…' : c.imageBuilt ? 'built' : 'not built yet'}${c.buildError ? ` (last build failed: ${c.buildError})` : ''} · Claude token ${c.hasClaudeToken ? 'set' : 'not set'}.`;
+    $('#containers-build').disabled = !c.available || c.building;
+    $('#containers-build').textContent = c.building ? 'Building…' : c.imageBuilt ? 'Rebuild image' : 'Build image';
+    form.containerDefault.disabled = !c.available;
+  }
+  $('#containers-build').onclick = async () => {
+    try {
+      containers = await api('POST', '/isolation/build');
+      showContainers();
+      toast('Building the agent image; it takes a few minutes the first time', 6000);
+      // Watch it finish.
+      const t = setInterval(async () => {
+        containers = await api('GET', '/isolation').catch(() => containers);
+        if (dialog.open) showContainers();
+        if (!containers?.building) {
+          clearInterval(t);
+          toast(containers?.imageBuilt && !containers.buildError ? 'Agent image built: agents can run in containers' : `Image build failed: ${containers?.buildError ?? 'see the daemon log'}`, 8000);
+        }
+      }, 5000);
+    } catch (err) {
+      toast(`Error: ${err.message}`, 6000);
+    }
+  };
   $('#settings-btn').onclick = async () => {
     $('#settings-error').hidden = true;
     try {
@@ -70,6 +100,11 @@ export function initMenu({ api, esc, toast, $ }) {
         form.jiraEmail.value = jira?.email ?? '';
         form.jiraToken.value = '';
         form.jiraToken.placeholder = jira?.hasToken ? 'saved (type to replace)' : '';
+        containers = await api('GET', '/isolation').catch(() => null);
+        showContainers();
+        form.claudeToken.value = '';
+        form.claudeToken.placeholder = containers?.hasClaudeToken ? 'saved (type to replace)' : 'from claude setup-token';
+        form.containerDefault.checked = containers?.default === 'container';
         service = await api('GET', '/service').catch(() => null);
         $('#settings-service').hidden = !service?.supported;
         form.startAtLogin.checked = Boolean(service?.installed);
@@ -96,6 +131,10 @@ export function initMenu({ api, esc, toast, $ }) {
         await api('PUT', '/jira', { site: form.jiraSite.value.trim(), email: form.jiraEmail.value.trim(), token: form.jiraToken.value.trim() || undefined });
         toast('Jira saved; summaries for agents from Jira links are being fetched', 4000);
       }
+      if (!remote() && containers?.available) {
+        if (form.claudeToken.value.trim()) await api('PUT', '/isolation/token', { token: form.claudeToken.value.trim() });
+        if (form.containerDefault.checked !== (containers.default === 'container')) await api('PUT', '/isolation/default', { container: form.containerDefault.checked });
+      }
       // Only when it changed: installing touches launchd / systemd.
       if (!remote() && service?.supported && form.startAtLogin.checked !== Boolean(service.installed)) {
         const s = await api('PUT', '/service', { enabled: form.startAtLogin.checked });

package/public/style.css

@@ -934,3 +934,9 @@ form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px;
 .rv-hunk.flash td { animation: rvflash 1.6s; }
 @keyframes rvflash { 0%, 60% { background: var(--accent); color: var(--accent-text); } }
 @media (max-width: 640px) { .sc-row { grid-template-columns: 56px 1fr 28px; } .sc-why { grid-column: 1 / -1; } }
+
+.containers-actions { display: flex; align-items: flex-end; }
+
+/* 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; }

package/src/backlog.js

@@ -89,7 +89,7 @@ export class Backlog extends EventEmitter {
   // ------------------------------------------------------------ editing
 
   /** Queue one item per title. Options are what an agent would take (repo, dir, base, project, ...). */
-  add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, attachments, priority = 2 } = {}) {
+  add(titles, { repo, dir, base, project, worktree, permissionMode, model, plan, planReview, engine, attachments, isolation, priority = 2 } = {}) {
     const list = titles.map((t) => String(t ?? '').trim()).filter(Boolean);
     if (!list.length) throw err(400, 'At least one item is required');
     const pr = parsePriority(priority);
@@ -122,6 +122,8 @@ export class Backlog extends EventEmitter {
         engine: engine || null,
         // Staged uploads; each item's agent gets its own copies when it starts.
         attachments: Array.isArray(attachments) && attachments.length ? attachments.slice(0, 20).map(String) : undefined,
+        // "container", "" (on this computer), or undefined (the default when it starts).
+        isolation: isolation === undefined ? undefined : isolation || '',
         plan: Boolean(plan),
         planReview: planReview ?? null,
         priority: pr,
@@ -222,6 +224,7 @@ export class Backlog extends EventEmitter {
       model: it.model,
       engine: it.engine ?? undefined,
       attachments: it.attachments,
+      isolation: it.isolation,
       plan: it.plan,
       planReview: it.planReview ?? undefined,
       priority: it.priority,

package/src/cli.js

@@ -343,6 +343,8 @@ export async function main(argv) {
     .option('-m, --model <model>', 'model (for the chosen engine)')
     .option('-e, --engine <engine>', 'agent engine: claude (default), codex, antigravity or muse')
     .option('--file-attach <path>', 'attach a file to the request (a screenshot, a log); repeat for more', collect)
+    .option('--container', 'run each agent in its own Docker container (see agentmgr sandbox)')
+    .option('--no-container', 'run on this computer even if containers are the default')
     .option('--plan', 'while a repo URL clones, plan the task with Claude (moves into the repo when ready)')
     .option('--no-start', 'create without launching')
     .option('-a, --attach', 'attach to the agent after launch (single intent only)')
@@ -357,6 +359,7 @@ export async function main(argv) {
       const created = await api('POST', '/agents', {
         intents,
         attachments,
+        isolation: cmd.getOptionValueSource('container') === 'cli' ? (opts.container ? 'container' : '') : undefined,
         repo: opts.repo,
         dir: opts.dir,
         name: opts.name,
@@ -383,6 +386,39 @@ export async function main(argv) {
       }
     });
 
+  const sb = program.command('sandbox').description('Agents in Docker containers: status, building the agent image, the Claude token');
+  sb.command('status')
+    .description('Whether Docker runs, the agent image is built, and containers can sign in to Claude')
+    .action(async () => {
+      await daemon();
+      const s = await api('GET', '/isolation');
+      console.log(`Docker:       ${s.available ? green(`running (${s.version})`) : yellow(`not available${s.error ? `: ${s.error}` : ''}`)}`);
+      console.log(`Agent image:  ${s.image} ${s.imageBuilt ? green('built') : s.building ? yellow('building…') : yellow('not built (agentmgr sandbox build)')}`);
+      console.log(`Claude token: ${s.hasClaudeToken ? green('set') : yellow('not set (run `claude setup-token`, then agentmgr sandbox token <token>)')}`);
+      console.log(`Default:      ${s.default === 'container' ? 'new agents run in containers' : 'new agents run on this computer'}`);
+      if (s.buildError) console.log(yellow(`Last build failed: ${s.buildError}`));
+    });
+  sb.command('build')
+    .description('Build the image agents run in (Node, git, Claude Code, Codex); a few minutes the first time')
+    .action(async () => {
+      const { buildImage, isolationSettings } = await import('./container.js');
+      const { loadConfig } = await import('./config.js');
+      const cfg = loadConfig();
+      console.log(dim(`building ${isolationSettings(cfg).image}…`));
+      await buildImage(cfg, { log: (l) => process.stderr.write(dim(l)) });
+      console.log(`${green('✓')} built ${isolationSettings(cfg).image}`);
+    });
+  sb.command('token')
+    .description('Save the Claude Code token containers sign in with (from `claude setup-token`); --clear removes it')
+    .argument('[token]')
+    .option('--clear', 'remove the saved token')
+    .action(async (token, opts) => {
+      const { saveSecrets } = await import('./container.js');
+      if (!opts.clear && !token) throw new Error('Give the token from `claude setup-token`, or --clear');
+      saveSecrets({ claudeOauthToken: opts.clear ? null : token.trim() });
+      console.log(opts.clear ? 'Token removed' : `${green('✓')} token saved (in ~/.agentmanager/secrets.json, readable only by you)`);
+    });
+
   program
     .command('ask')
     .description('Open a general session (no repo or folder) on any engine and attach to it')

package/src/container.js

@@ -0,0 +1,189 @@
+// Isolation: an agent that runs in its own Docker container instead of directly on this computer.
+// It sees only its own folder (mounted at the same path, so paths, transcripts and git all line up),
+// its repository's git data, its brief folder and its uploads; nothing else of yours. Claude Code
+// and Codex keep their sessions in your usual folders (mounted in), so tracking, resume and usage
+// work as they do on the host. Each engine gets its own config home for containers, with sign-in
+// from a token (Claude: `claude setup-token`) or Codex's auth.json, read-only.
+import { execFile, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { paths } from './config.js';
+import { trustFolder } from './trust.js';
+
+export const DEFAULT_IMAGE = 'ai-agentmanager-agent:1';
+export const CONTAINER_ENGINES = new Set(['claude', 'codex']);
+const DOCKERFILE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'docker', 'agent.Dockerfile');
+const homes = () => path.join(paths.home, 'containers');
+const secretsFile = () => path.join(paths.home, 'secrets.json');
+
+export const containerName = (agentId, kind = 'agent') => `agentmgr-${agentId}${kind === 'agent' ? '' : `-${kind}`}`;
+export const isolationSettings = (config = {}) => ({ image: DEFAULT_IMAGE, cpus: null, memory: null, network: null, ...(config.isolation ?? {}) });
+
+// ------------------------------------------------------------ secrets (the Claude token)
+
+export function loadSecrets() {
+  try {
+    return JSON.parse(fs.readFileSync(secretsFile(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveSecrets(patch) {
+  const next = { ...loadSecrets(), ...patch };
+  for (const [k, v] of Object.entries(next)) if (v == null || v === '') delete next[k];
+  fs.mkdirSync(paths.home, { recursive: true });
+  fs.writeFileSync(secretsFile(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  return next;
+}
+
+/** The Claude Code token for containers: saved (Settings, `agentmgr sandbox token`), else CLAUDE_CODE_OAUTH_TOKEN. */
+export const claudeToken = (env = process.env) => loadSecrets().claudeOauthToken || env.CLAUDE_CODE_OAUTH_TOKEN || '';
+
+// ------------------------------------------------------------ docker
+
+const docker = (args, opts = {}) =>
+  new Promise((resolve, reject) =>
+    execFile('docker', args, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024, ...opts }, (err, stdout, stderr) => (err ? reject(Object.assign(err, { stderr })) : resolve(String(stdout).trim()))),
+  );
+
+/** Whether Docker runs here, and whether the agent image is built. */
+export async function dockerStatus(config = {}) {
+  const { image } = isolationSettings(config);
+  try {
+    const version = await docker(['version', '--format', '{{.Server.Version}}']);
+    const has = await docker(['image', 'inspect', image, '--format', '{{.Id}}']).then(() => true, () => false);
+    return { available: true, version, image, imageBuilt: has };
+  } catch (err) {
+    return { available: false, version: null, image, imageBuilt: false, error: String(err.stderr || err.message).trim().split('\n')[0].slice(0, 200) };
+  }
+}
+
+let building = null;
+/** Build the agent image from docker/agent.Dockerfile (a few minutes the first time). */
+export function buildImage(config = {}, { log = () => {} } = {}) {
+  if (building) return building;
+  const { image } = isolationSettings(config);
+  building = new Promise((resolve, reject) => {
+    const child = execFile('docker', ['build', '-t', image, '-f', DOCKERFILE, path.dirname(DOCKERFILE)], { timeout: 30 * 60_000, maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+      building = null;
+      if (err) reject(new Error(`docker build failed: ${String(stderr || err.message).trim().split('\n').slice(-3).join(' ')}`));
+      else resolve({ image });
+    });
+    child.stderr?.on('data', (d) => log(String(d)));
+  });
+  return building;
+}
+export const isBuilding = () => Boolean(building);
+
+/** Remove a leftover container of this name (a restart reuses the name). */
+export function removeContainer(name) {
+  try {
+    execFileSync('docker', ['rm', '-f', name], { stdio: 'ignore', timeout: 15_000 });
+  } catch {}
+}
+
+/** Stop a running container, giving the agent time to save (it is removed when it stops). */
+export function stopContainer(name, seconds = 10) {
+  execFile('docker', ['stop', '-t', String(seconds), name], { timeout: (seconds + 20) * 1000 }, () => {});
+}
+
+export function containerRunning(name) {
+  try {
+    return execFileSync('docker', ['inspect', '-f', '{{.State.Running}}', name], { timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------ what a container sees
+
+/** A worktree's shared git folder (its .git file points into the main repository's), or null. */
+export function gitCommonDir(cwd) {
+  const dotgit = path.join(cwd, '.git');
+  try {
+    if (fs.statSync(dotgit).isDirectory()) return null; // a plain clone: its .git is inside the folder
+    const gitdir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotgit, 'utf8'))?.[1]?.trim();
+    if (!gitdir) return null;
+    const abs = path.resolve(cwd, gitdir);
+    const common = fs.existsSync(path.join(abs, 'commondir')) ? path.resolve(abs, fs.readFileSync(path.join(abs, 'commondir'), 'utf8').trim()) : abs;
+    return fs.realpathSync(common);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The engine's config home for containers (seeded once), with this folder trusted. Claude: a
+ * .claude.json with onboarding done; Codex: config.toml. Returns the host folder.
+ */
+export function engineHome(engineId, cwd) {
+  const dir = path.join(homes(), engineId);
+  fs.mkdirSync(dir, { recursive: true });
+  if (engineId === 'claude') {
+    const file = path.join(dir, '.claude.json');
+    if (!fs.existsSync(file)) fs.writeFileSync(file, JSON.stringify({ hasCompletedOnboarding: true, theme: 'dark', projects: {} }, null, 2), { mode: 0o600 });
+    trustFolder(cwd, file);
+  } else if (engineId === 'codex') {
+    const file = path.join(dir, 'config.toml');
+    const key = cwd.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const raw = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    if (!raw.includes(`[projects."${key}"]`)) fs.appendFileSync(file, `${raw && !raw.endsWith('\n') ? '\n' : ''}[projects."${key}"]\ntrust_level = "trusted"\n`);
+  }
+  return dir;
+}
+
+/**
+ * `docker run` arguments for an agent: the container, its mounts and limits, then the engine's
+ * own command (`bin` + `args`). Secrets are passed by name (`-e NAME`, the value from the docker
+ * command's environment), never in the arguments.
+ */
+export function runArgs({ agentId, engineId, cwd, bin, args, config = {}, mounts = [], env = [], user = process.getuid?.() != null ? `${process.getuid()}:${process.getgid()}` : null, name = containerName(agentId) }) {
+  const s = isolationSettings(config);
+  const out = ['run', '--rm', '-i', '-t', '--init', '--name', name, '--label', `agentmgr.agent=${agentId}`, '-w', cwd];
+  if (user) out.push('--user', user);
+  if (s.cpus) out.push('--cpus', String(s.cpus));
+  if (s.memory) out.push('--memory', String(s.memory));
+  if (s.network) out.push('--network', String(s.network));
+  const seen = new Set();
+  for (const m of [{ host: cwd }, ...mounts]) {
+    const inside = m.inside ?? m.host;
+    if (!m.host || seen.has(inside)) continue;
+    seen.add(inside);
+    out.push('-v', `${m.host}:${inside}${m.readOnly ? ':ro' : ''}`);
+  }
+  for (const e of env) out.push('-e', e);
+  out.push(s.image, ...[bin].flat(), ...args);
+  return out;
+}
+
+/**
+ * Everything an engine needs mounted and set in its container: its config home, your session
+ * folders (so the manager reads them where it always does) and its sign-in.
+ */
+export function engineMounts(engineId, cwd, env = process.env) {
+  const home = engineHome(engineId, cwd);
+  if (engineId === 'claude') {
+    const projects = path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'projects');
+    fs.mkdirSync(projects, { recursive: true });
+    return {
+      mounts: [{ host: home, inside: '/agentmgr/claude' }, { host: projects, inside: '/agentmgr/claude/projects' }],
+      env: ['CLAUDE_CONFIG_DIR=/agentmgr/claude', 'CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'],
+      bin: 'claude',
+    };
+  }
+  if (engineId === 'codex') {
+    const codexHome = env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    const sessions = path.join(codexHome, 'sessions');
+    fs.mkdirSync(sessions, { recursive: true });
+    const auth = path.join(codexHome, 'auth.json');
+    return {
+      mounts: [{ host: home, inside: '/agentmgr/codex' }, { host: sessions, inside: '/agentmgr/codex/sessions' }, ...(fs.existsSync(auth) ? [{ host: auth, inside: '/agentmgr/codex/auth.json', readOnly: true }] : [])],
+      env: ['CODEX_HOME=/agentmgr/codex', 'OPENAI_API_KEY'],
+      bin: 'codex',
+    };
+  }
+  throw Object.assign(new Error(`${engineId} can't run in a container yet (Claude Code and Codex can)`), { status: 400 });
+}

package/src/engines/acp.js

@@ -0,0 +1,222 @@
+// Engines for agents that speak ACP (the Agent Client Protocol): Gemini CLI, OpenCode, Goose,
+// Qwen Code and any other, from one line of config. AI Agent Manager runs its own terminal client
+// (bin/acp-client.js) in the agent's terminal, which talks ACP to the agent and keeps a session log
+// in ~/.agentmanager/acp/<engine>/<session>.jsonl; this adapter reads that log for usage, PR and
+// bug links, stuck detection and Explain.
+//
+// config.json: "acp": { "<name>": { "command": ["opencode", "acp"], "label": "OpenCode" } }
+// adds (or changes) the engine "acp-<name>". The presets below are offered when installed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { paths } from '../config.js';
+import { norm, tailOf } from '../stuck.js';
+import { extractRefs } from '../tracker.js';
+
+const CLIENT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'bin', 'acp-client.js');
+export const ACP_PRESETS = {
+  gemini: { label: 'Gemini CLI', command: ['gemini', '--experimental-acp'] },
+  opencode: { label: 'OpenCode', command: ['opencode', 'acp'] },
+  goose: { label: 'Goose', command: ['goose', 'acp'] },
+  qwen: { label: 'Qwen Code', command: ['qwen', '--experimental-acp'] },
+};
+const ANSI = /\x1b(\[[0-9;?<>=]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[()][0-9A-B]|[=>78c])/g;
+const real = (p) => {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+};
+
+/** Complete JSON lines added since the cursor's offset. */
+function newRecords(file, cursor) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'r');
+  } catch {
+    return null;
+  }
+  try {
+    const { size, mtime } = fs.fstatSync(fd);
+    cursor.lastActivity = mtime.toISOString();
+    if (size < cursor.offset) cursor.offset = 0;
+    if (size === cursor.offset) return [];
+    const buf = Buffer.alloc(size - cursor.offset);
+    fs.readSync(fd, buf, 0, buf.length, cursor.offset);
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl < 0) return [];
+    cursor.offset += lastNl + 1;
+    const out = [];
+    for (const line of buf.subarray(0, lastNl).toString('utf8').split('\n')) {
+      try {
+        if (line) out.push(JSON.parse(line));
+      } catch {}
+    }
+    return out;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** The engine for one ACP agent. */
+export function acpEngine(name, { command, label, args = [] }) {
+  const id = `acp-${name}`;
+  const logDir = () => path.join(paths.home, 'acp', name);
+  const fileOf = (sid) => path.join(logDir(), `${String(sid).replace(/[^\w.-]/g, '_')}.jsonl`);
+  const cmd = [command].flat().map(String);
+  return {
+    id,
+    label: label ?? name,
+    acp: true,
+    // Bypass answers its permission requests "allow" by itself; other modes ask (the inbox can answer).
+    supports: { chooseSessionId: false, cost: false, planHandoff: false, fork: false, oneShot: true, resumePrompt: true },
+    permissionModes: ['default', 'bypassPermissions'],
+    rulesFiles: ['AGENTS.md'],
+    install: `Install ${label ?? name} (\`${cmd[0]}\` on the daemon's PATH) and sign in once in a terminal`,
+
+    // The command that has to be installed is the agent's; the client is ours.
+    bin: () => process.execPath,
+    installedBin: () => cmd[0],
+    extraArgs: () => [],
+
+    /** The client in the agent's terminal: the log folder, resume, the first message, then the agent. */
+    launchArgs({ permissionMode, writableDir, instructions, sessionId, resume, prompt }) {
+      const out = [CLIENT, '--log', logDir()];
+      if (permissionMode === 'bypassPermissions') out.push('--yes');
+      for (const d of [writableDir ?? []].flat()) out.push('--allow-dir', d);
+      if (resume) out.push('--session', sessionId);
+      const first = resume ? prompt : [instructions, prompt && (instructions ? `Your task:\n${prompt}` : prompt)].filter(Boolean).join('\n\n---\n\n');
+      if (first) out.push('--prompt', first);
+      return [...out, '--', ...cmd, ...args];
+    },
+
+    sessionFile: (cwd, sid) => fileOf(sid),
+    hasSession: (cwd, sid) => fs.existsSync(fileOf(sid)),
+    subagentFiles: () => [],
+
+    /** Sessions the client started in this folder since a time (from each log's first line). */
+    recentSessions(cwd, sinceMs) {
+      const want = real(cwd);
+      const out = [];
+      let names = [];
+      try {
+        names = fs.readdirSync(logDir()).filter((n) => n.endsWith('.jsonl'));
+      } catch {}
+      for (const n of names) {
+        const file = path.join(logDir(), n);
+        const st = fs.statSync(file);
+        if (st.mtimeMs < sinceMs) continue;
+        let meta = null;
+        try {
+          meta = JSON.parse(fs.readFileSync(file, 'utf8').split('\n')[0]);
+        } catch {}
+        if (meta?.type !== 'meta' || real(meta.cwd) !== want) continue;
+        out.push({ sessionId: meta.sessionId, file, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs });
+      }
+      return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    },
+
+    /** Usage (the agent's context use, when it reports it), PR and bug links from messages and tool output. */
+    scan(file, cursor, bugPatterns = []) {
+      const result = { prs: [], bugs: [], title: null, lastPrompt: null, cost: null, lastActivity: null };
+      cursor.usage ??= new Map();
+      cursor.offset ??= 0;
+      const recs = newRecords(file, cursor);
+      result.lastActivity = cursor.lastActivity ?? null;
+      if (!recs) return result;
+      for (const r of recs) {
+        if (r.type === 'user') result.lastPrompt = String(r.text ?? '').slice(0, 500);
+        if (r.type === 'usage' && r.used != null) cursor.usage.set('context', { input: r.used, output: 0, cacheCreation: 0, cacheRead: 0 });
+        const text = r.type === 'agent' || r.type === 'user' ? r.text : r.type === 'tool' ? r.output : '';
+        if (text) {
+          const refs = extractRefs(String(text), bugPatterns);
+          result.prs.push(...refs.prs);
+          result.bugs.push(...refs.bugs);
+        }
+      }
+      return result;
+    },
+
+    /** Commands and edits, for stuck detection. */
+    activity(file, state) {
+      state.events ??= [];
+      state.offset ??= 0;
+      state.inputs ??= {};
+      const recs = newRecords(file, state);
+      if (!recs) return state;
+      for (const r of recs) {
+        const t = Date.parse(r.t) || Date.now();
+        if (r.type === 'tool' && r.input) state.inputs[r.id] = r.input;
+        if (r.type === 'tool' && (r.status === 'completed' || r.status === 'failed') && r.kind === 'execute') {
+          const input = r.input ?? state.inputs[r.id] ?? {};
+          const out = String(r.output ?? '');
+          state.events.push({ t, kind: 'cmd', cmd: norm(String(input.command ?? r.title ?? '')).slice(0, 300), failed: Boolean(r.failed), result: tailOf(out), shown: out.replace(/\s+/g, ' ').trim().slice(-160) });
+        } else if (r.type === 'edit') {
+          state.events.push({ t, kind: 'edit', file: r.path, edits: [[norm(r.oldText ?? ''), norm(r.newText ?? '')]] });
+        }
+      }
+      if (state.events.length > 400) state.events = state.events.slice(-400);
+      return state;
+    },
+
+    /** A readable digest of the conversation, for Explain and documents. */
+    digest(file, { maxChars = 24_000 } = {}) {
+      const events = [];
+      const edited = new Set();
+      for (const r of newRecords(file, { offset: 0 }) ?? []) {
+        if (r.type === 'user') events.push(`[user] ${String(r.text).slice(0, 1200)}`);
+        else if (r.type === 'agent') events.push(`[agent] ${String(r.text).slice(0, 1800)}`);
+        else if (r.type === 'tool' && (r.status === 'completed' || r.status === 'failed')) events.push(`[action] ${r.title}${r.failed ? ' (failed)' : ''}`);
+        else if (r.type === 'edit') edited.add(r.path), events.push(`[action] edited ${r.path}`);
+      }
+      const head = events.find((e) => e.startsWith('[user]'));
+      const tail = [];
+      let used = head?.length ?? 0;
+      for (let i = events.length - 1; i >= 0 && events[i] !== head; i--) {
+        if (used + events[i].length > maxChars) {
+          tail.unshift('… (earlier events omitted) …');
+          break;
+        }
+        tail.unshift(events[i]);
+        used += events[i].length + 1;
+      }
+      return { digest: [head, ...tail].filter(Boolean).join('\n'), events: events.length, edited: [...edited] };
+    },
+
+    copySession: () => false,
+
+    attention: [[/Permissionneeded:/i, 'Permission prompt']],
+    // Its menu reads a line: a choice is the number, then Enter.
+    promptKeyEnter: true,
+
+    /** The client's menu: "Permission needed: <title> 1. Allow once 2. Always allow 3. Reject Choose 1-3". */
+    promptChoices(screen) {
+      const text = String(screen ?? '').replace(ANSI, ' ').replace(/\s+/g, ' ');
+      const at = text.lastIndexOf('Permission needed:');
+      if (at < 0) return { question: '', choices: [] };
+      const tail = text.slice(at);
+      const question = (/^Permission needed: (.*?)(?= 1\. )/.exec(tail)?.[1] ?? '').trim().slice(0, 200);
+      const choices = [];
+      for (const m of tail.matchAll(/\b(\d)\. (.+?)(?= \d\. | Choose |$)/g)) choices.push({ key: m[1], label: m[2].trim().slice(0, 80) });
+      return { question: question ? `Allow: ${question}?` : 'Allow this?', choices };
+    },
+
+    trust: () => false,
+
+    /** One-shot: the client in --once mode, every permission refused (read-only), the prompt on stdin. */
+    oneShotArgs: () => [CLIENT, '--once', '--', ...cmd, ...args],
+
+    stripEnv: [],
+  };
+}
+
+/** The ACP engines to offer: the presets, with config's own added or changed. */
+export function acpEngines(config = {}) {
+  const defs = { ...ACP_PRESETS };
+  for (const [name, def] of Object.entries(config.acp ?? {})) {
+    if (def === false) delete defs[name];
+    else if (def?.command) defs[name] = { ...defs[name], ...def };
+  }
+  return Object.entries(defs).map(([name, def]) => acpEngine(name, def));
+}

package/src/engines/index.js

@@ -6,6 +6,7 @@ import antigravity from './antigravity.js';
 import claude from './claude.js';
 import codex from './codex.js';
 import muse from './muse.js';
+import { acpEngines } from './acp.js';
 
 export const ENGINES = { claude, codex, antigravity, muse };
 export const DEFAULT_ENGINE = 'claude';
@@ -17,16 +18,23 @@ export function registerEngine(def) {
   ENGINES[def.id] = def;
 }
 
+/** ACP agents from config.json's "acp" and the presets (acp.js); call again when the config changes. */
+export function registerAcpEngines(config = {}) {
+  for (const id of Object.keys(ENGINES)) if (ENGINES[id].acp) delete ENGINES[id];
+  for (const e of acpEngines(config)) ENGINES[e.id] = e;
+}
+
 /** Whether an engine's command is on this machine (an absolute path, or found on PATH). */
 export function installed(engine, config) {
-  const bin = engine.bin(config);
+  // An ACP engine runs our client with Node; what has to be installed is the agent's own command.
+  const bin = engine.installedBin?.(config) ?? engine.bin(config);
   if (path.isAbsolute(bin)) return fs.existsSync(bin);
   return (process.env.PATH ?? '').split(path.delimiter).some((d) => d && fs.existsSync(path.join(d, bin)));
 }
 
 /** What to tell the person when an engine's command isn't on this machine. */
 export function notInstalled(engine, config) {
-  const bin = engine.bin(config);
+  const bin = engine.installedBin?.(config) ?? engine.bin(config);
   const how = engine.install ?? `Install ${engine.label}`;
   const where = path.isAbsolute(bin) ? `${bin} doesn't exist` : `\`${bin}\` isn't on the daemon's PATH`;
   return `${engine.label} not found: ${where}. ${how}, then run \`agentmgr restart\`. If it's installed somewhere else, set its path in config.json${engine.id === 'claude' ? ' ("claudeBin") or AGENTMGR_CLAUDE_BIN' : ` ("engines": {"${engine.id}": {"bin": "…"}})`}.`;