ai-agentmanager 1.3.1 → 1.5.0

package/src/handoff.js

@@ -0,0 +1,240 @@
+// Moving an agent to another machine through the hub, so it continues there: same session (its
+// conversation), same branch, its uncommitted work. Code travels through the repo's own remote
+// (a handoff branch holding a snapshot of the folder, deleted once the move is done); the
+// conversation travels through the hub in chunks; the hub keeps neither. Both machines must
+// allow "move" in their hub settings.
+//
+// On the machine it leaves: export (close the session, snapshot and push the work, hold the
+// transcript), chunk (pieces of the transcript), done (mark it moved, or start it again if the
+// move failed). On the machine it joins: import (create the agent in the matching project, with
+// the same session id), put (transcript pieces), finish (check out the work, place the
+// conversation, resume it if it was running).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as git from './git.js';
+import { projectRef } from './fleet.js';
+import { engineOf } from './engines/index.js';
+import { briefPath } from './brief.js';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+export const CHUNK_BYTES = 512 * 1024; // base64 keeps a piece under the runner link's 1 MB frames
+const EXPIRE_MS = 30 * 60_000;
+export const handoffBranch = (agentId) => `agentmgr-handoff/${agentId}`;
+const MAX_TRANSCRIPT_BYTES = 200 * 1024 * 1024;
+/** A plain object of links small enough to keep (they come from the other machine). */
+const small = (o) => Boolean(o) && typeof o === 'object' && !Array.isArray(o) && JSON.stringify(o).length < 100_000;
+
+/** A transcript's lines with the old folder replaced by the new one where Claude recorded it. */
+export function moveTranscript(text, fromCwd, toCwd) {
+  if (!fromCwd || fromCwd === toCwd) return text;
+  return text
+    .split('\n')
+    .map((line) => {
+      if (!line.includes(fromCwd)) return line;
+      try {
+        const o = JSON.parse(line);
+        if (o.cwd === fromCwd) o.cwd = toCwd;
+        else if (typeof o.cwd === 'string' && o.cwd.startsWith(`${fromCwd}/`)) o.cwd = toCwd + o.cwd.slice(fromCwd.length);
+        return JSON.stringify(o);
+      } catch {
+        return line;
+      }
+    })
+    .join('\n');
+}
+
+export class Handoff {
+  constructor({ manager, log = (m) => console.log(`[agentmgr] ${m}`) }) {
+    this.manager = manager;
+    this.log = log;
+    this.exports = new Map(); // exportId -> { agentId, buf, wasRunning, at, remote, branch }
+    this.imports = new Map(); // importId -> { agentId, manifest, parts: [], at }
+  }
+
+  sweep() {
+    const old = Date.now() - EXPIRE_MS;
+    for (const [k, v] of this.exports) if (v.at < old) this.exports.delete(k);
+    for (const [k, v] of this.imports) if (v.at < old) this.imports.delete(k);
+  }
+
+  // ------------------------------------------------------------- leaving
+
+  async export(agent) {
+    this.sweep();
+    const m = this.manager;
+    if (agent.kind !== 'task') throw err(400, 'Only task agents can move to another machine');
+    if (agent.status === 'preparing') throw err(409, 'The agent is still setting up');
+    if (agent.movedTo) throw err(409, `Already moved to ${agent.movedTo.machine}`);
+    const dir = agent.workdir;
+    if (!dir || !(await git.isGitRepo(dir))) throw err(400, 'The agent folder is not a git repository');
+    const remote = await git.run('git', ['remote', 'get-url', 'origin'], { cwd: dir }).catch(() => '');
+    if (!remote) throw err(400, "The agent's repository has no remote (origin), so its work can't reach another machine");
+    const engine = engineOf(agent);
+    if (engine.id !== 'claude') throw err(400, `Moving ${engine.label} sessions isn't supported yet`);
+    const info = m.projectInfo(agent);
+    const wasRunning = Boolean(m.runtimes.get(agent.id)?.pty);
+    // Close the session so Claude writes everything; it stays closed here from now on.
+    await m.stop(agent.id);
+    await m.flush().catch(() => {});
+    const snap = await git.snapshot(dir, `agentmgr handoff of ${agent.name}`);
+    if (!snap) throw err(400, 'The agent folder has no commits yet');
+    const branch = handoffBranch(agent.id);
+    await git.run('git', ['push', '--force', '--no-verify', 'origin', `${snap.sha}:refs/heads/${branch}`], { cwd: dir, timeout: 180_000 });
+    const file = engine.sessionFile(dir, agent.sessionId);
+    const buf = fs.existsSync(file) ? fs.readFileSync(file) : Buffer.alloc(0);
+    if (buf.length > MAX_TRANSCRIPT_BYTES) throw err(413, 'The conversation is too large to move');
+    const exportId = crypto.randomBytes(8).toString('hex');
+    this.exports.set(exportId, { agentId: agent.id, buf, wasRunning, at: Date.now(), dir, branch });
+    const brief = m.briefFile?.(agent.id)?.markdown ?? null;
+    this.log(`handoff: ${agent.name} packed for another machine (${buf.length} bytes of conversation, work on ${branch})`);
+    return {
+      exportId,
+      manifest: {
+        from: { agentId: agent.id, workdir: fs.realpathSync(dir) },
+        name: agent.name,
+        intent: agent.intent,
+        priority: agent.priority,
+        model: agent.model ?? null,
+        permissionMode: agent.permissionMode ?? null,
+        notes: agent.notes ?? null,
+        baseRef: agent.baseRef ?? null,
+        links: { prs: agent.prs ?? {}, bugs: agent.bugs ?? {} },
+        brief: brief && brief.length < 200_000 ? brief : null,
+        project: { ref: projectRef(info), name: info.name },
+        branch: agent.git?.branch ?? agent.branch ?? null,
+        handoffBranch: branch,
+        head: snap.head,
+        snapshot: snap.sha,
+        sessionId: agent.sessionId,
+        transcriptBytes: buf.length,
+        chunks: Math.ceil(buf.length / CHUNK_BYTES),
+        wasRunning,
+      },
+    };
+  }
+
+  chunk(exportId, i) {
+    const x = this.exports.get(String(exportId));
+    if (!x) throw err(404, 'That move expired; start it again');
+    const n = Number(i);
+    if (!(n >= 0) || n * CHUNK_BYTES >= Math.max(x.buf.length, 1)) throw err(400, 'No such piece');
+    return { i: n, data: x.buf.subarray(n * CHUNK_BYTES, (n + 1) * CHUNK_BYTES).toString('base64') };
+  }
+
+  /** After the other machine answered: mark the agent moved (and drop the handoff branch), or undo. */
+  async done(exportId, { ok, machine, agentId: newId } = {}) {
+    const x = this.exports.get(String(exportId));
+    if (!x) throw err(404, 'That move expired');
+    this.exports.delete(String(exportId));
+    const m = this.manager;
+    if (!ok) {
+      // It stays here: open it again as it was.
+      await git.run('git', ['push', '--no-verify', 'origin', '--delete', x.branch], { cwd: x.dir, timeout: 60_000 }).catch(() => {});
+      if (x.wasRunning) await m.start(x.agentId).catch(() => {});
+      return m.get(x.agentId);
+    }
+    // The other machine has the work now; the branch was only the way there.
+    await git.run('git', ['push', '--no-verify', 'origin', '--delete', x.branch], { cwd: x.dir, timeout: 60_000 }).catch(() => {});
+    m.patch(x.agentId, { movedTo: { machine: String(machine ?? 'another machine').slice(0, 60), agentId: newId ?? null, at: new Date().toISOString() }, desired: 'stopped' });
+    this.log(`handoff: ${m.store.get(x.agentId)?.name} moved to ${machine}`);
+    return m.get(x.agentId);
+  }
+
+  // ------------------------------------------------------------- joining
+
+  /** Create the agent in the project that matches, with the same session; it sets up its folder. */
+  import(manifest, policy, allowedProject) {
+    this.sweep();
+    const m = this.manager;
+    const mf = manifest && typeof manifest === 'object' ? manifest : {};
+    if (!/^[\w-]{8,64}$/.test(String(mf.sessionId ?? ''))) throw err(400, 'Missing session');
+    if (!/^[0-9a-f]{40,64}$/.test(String(mf.snapshot ?? '')) || !/^[0-9a-f]{40,64}$/.test(String(mf.head ?? ''))) throw err(400, 'Missing work snapshot');
+    if (!/^agentmgr-handoff\/[\w-]{1,40}$/.test(String(mf.handoffBranch ?? ''))) throw err(400, 'Bad handoff branch');
+    const ref = String(mf.project?.ref ?? '');
+    const entry = m.listProjects().find((p) => projectRef(p) === ref);
+    if (!entry) throw err(400, `This machine has no project for ${mf.project?.name ?? ref}`);
+    if (!allowedProject(policy.projects, entry.name, entry.shortcut)) throw err(403, 'This machine does not share that project with the hub');
+    if (m.store.list().some((a) => a.sessionId === mf.sessionId && !a.movedTo)) throw err(409, 'That session is already on this machine');
+    const [agent] = m.createMany([String(mf.intent ?? '').slice(0, 10_000) || 'Moved agent'], {
+      project: entry.shortcut,
+      priority: mf.priority,
+      model: mf.model ?? undefined,
+      permissionMode: ['default', 'acceptEdits', 'plan'].includes(mf.permissionMode) ? mf.permissionMode : undefined,
+      sessionId: mf.sessionId,
+      start: false,
+      name: mf.name ? String(mf.name).slice(0, 60) : undefined,
+    });
+    const importId = crypto.randomBytes(8).toString('hex');
+    this.imports.set(importId, { agentId: agent.id, manifest: mf, parts: [], at: Date.now() });
+    return { importId, agentId: agent.id, name: agent.name };
+  }
+
+  put(importId, i, data) {
+    const x = this.imports.get(String(importId));
+    if (!x) throw err(404, 'That move expired');
+    const n = Number(i);
+    if (!(n >= 0 && n < Math.max(1, Number(x.manifest.chunks) || 0))) throw err(400, 'No such piece');
+    x.parts[n] = Buffer.from(String(data ?? ''), 'base64');
+    return { i: n };
+  }
+
+  /** A move that failed after the agent was created here: remove it again. */
+  async cancel(importId) {
+    const x = this.imports.get(String(importId));
+    if (!x) return { ok: true };
+    this.imports.delete(String(importId));
+    await this.manager.remove(x.agentId, { deleteWorkspace: true }).catch(() => {});
+    return { ok: true };
+  }
+
+  async finish(importId, { timeoutMs = 170_000 } = {}) {
+    const x = this.imports.get(String(importId));
+    if (!x) throw err(404, 'That move expired');
+    const m = this.manager;
+    const mf = x.manifest;
+    const chunks = Number(mf.chunks) || 0;
+    for (let i = 0; i < chunks; i++) if (!x.parts[i]) throw err(400, `Piece ${i + 1} of the conversation is missing`);
+    const buf = Buffer.concat(x.parts.slice(0, chunks));
+    if (buf.length !== Number(mf.transcriptBytes)) throw err(400, 'The conversation arrived incomplete');
+    // Wait for its folder (a clone or worktree of the project).
+    const until = Date.now() + timeoutMs;
+    let agent = m.store.get(x.agentId);
+    while (agent && (agent.status === 'preparing' || !agent.workdir || !fs.existsSync(agent.workdir))) {
+      if (agent.status === 'error') throw err(500, `Setting up the folder failed: ${agent.error ?? 'unknown error'}`);
+      if (Date.now() > until) throw err(504, 'Setting up the folder is taking too long');
+      await new Promise((r) => setTimeout(r, 500));
+      agent = m.store.get(x.agentId);
+    }
+    if (!agent) throw err(404, 'The new agent was removed');
+    const dir = agent.workdir;
+    const opts = { cwd: dir, timeout: 180_000 };
+    await git.run('git', ['fetch', '--no-tags', 'origin', `+refs/heads/${mf.handoffBranch}:refs/agentmgr/handoff/${agent.id}`], opts);
+    const branch = /^[\w./-]{1,200}$/.test(String(mf.branch ?? '')) && !String(mf.branch).includes('..') ? mf.branch : null;
+    if (branch) await git.run('git', ['checkout', '-q', '-B', branch, mf.head], opts);
+    else await git.run('git', ['checkout', '-q', '--detach', mf.head], opts);
+    await git.restoreSnapshot(dir, mf.snapshot);
+    await git.run('git', ['update-ref', '-d', `refs/agentmgr/handoff/${agent.id}`], opts).catch(() => {});
+    // The conversation, where Claude looks for it in this folder.
+    const engine = engineOf(agent);
+    const file = engine.sessionFile(dir, mf.sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, moveTranscript(buf.toString('utf8'), mf.from?.workdir, fs.realpathSync(dir)));
+    m.patch(agent.id, {
+      movedFrom: { machine: mf.fromMachine ? String(mf.fromMachine).slice(0, 60) : null, agentId: mf.from?.agentId ?? null, at: new Date().toISOString() },
+      ...(mf.notes ? { notes: String(mf.notes).slice(0, 20_000) } : {}),
+      ...(mf.baseRef ? { baseRef: String(mf.baseRef).slice(0, 300) } : {}),
+      ...(small(mf.links?.prs) ? { prs: mf.links.prs } : {}),
+      ...(small(mf.links?.bugs) ? { bugs: mf.links.bugs } : {}),
+      ...(branch ? { branch } : {}),
+    });
+    if (mf.brief) {
+      fs.mkdirSync(path.dirname(briefPath(agent.id)), { recursive: true });
+      fs.writeFileSync(briefPath(agent.id), String(mf.brief));
+    }
+    this.imports.delete(String(importId));
+    if (mf.wasRunning) await m.start(agent.id);
+    this.log(`handoff: ${agent.name} arrived${mf.fromMachine ? ` from ${mf.fromMachine}` : ''}${mf.wasRunning ? ' and resumed' : ''}`);
+    return m.get(agent.id);
+  }
+}

package/src/hub.js

@@ -35,7 +35,10 @@ export const ACTION_PERMS = {
   answer: 'inbox', 'prompt-key': 'inbox', nudge: 'inbox', 'dismiss-stuck': 'inbox', 'warn-conflict': 'inbox',
   tell: 'control', start: 'control', stop: 'control', checkpoint: 'control', priority: 'control', create: 'create',
   signin: 'signin',
+  'handoff-export': 'move', 'handoff-chunk': 'move', 'handoff-done': 'move', 'handoff-import': 'move', 'handoff-put': 'move', 'handoff-finish': 'move', 'handoff-cancel': 'move',
 };
+// Run only as steps of a move (POST /api/runners/:id/agents/:agent/move), never one by one.
+const HANDOFF_STEP = /^handoff-/;
 
 const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
 const secret = () => crypto.randomBytes(32).toString('base64url');
@@ -490,7 +493,7 @@ export async function startHub({
   };
 
   /** Ask a machine to do something; resolves with its reply. */
-  function rpc(runnerId, action, args) {
+  function rpc(runnerId, action, args, { timeoutMs = RPC_TIMEOUT_MS } = {}) {
     const l = live.get(runnerId);
     if (!l?.hello) return Promise.reject(fail(409, 'That machine is offline'));
     const perm = ACTION_PERMS[action];
@@ -501,7 +504,7 @@ export async function startHub({
       const timer = setTimeout(() => {
         l.rpcs.delete(id);
         reject(fail(504, 'The machine did not answer in time'));
-      }, RPC_TIMEOUT_MS);
+      }, timeoutMs);
       l.rpcs.set(id, { resolve, reject, timer });
       l.ws.send(JSON.stringify({ t: 'rpc', id, action, args }));
     });
@@ -550,12 +553,57 @@ export async function startHub({
     }),
   );
 
+  // Move an agent to another machine: its work through the repo's remote, its conversation through
+  // here in pieces (kept in memory only for the move). Both machines must allow "move".
+  async function moveAgent(from, agentId, to, by) {
+    const step = (what) => log(`move ${agentId} ${from.name} → ${to.name}: ${what}`);
+    const exp = await rpc(from.id, 'handoff-export', { agent: agentId }, { timeoutMs: 240_000 });
+    step('packed');
+    let imp = null;
+    try {
+      imp = await rpc(to.id, 'handoff-import', { manifest: { ...exp.manifest, fromMachine: from.name } }, { timeoutMs: 60_000 });
+      for (let i = 0; i < exp.manifest.chunks; i++) {
+        const piece = await rpc(from.id, 'handoff-chunk', { exportId: exp.exportId, i }, { timeoutMs: 60_000 });
+        await rpc(to.id, 'handoff-put', { importId: imp.importId, i, data: piece.data }, { timeoutMs: 60_000 });
+      }
+      step(`conversation sent (${exp.manifest.chunks} piece(s))`);
+      const fin = await rpc(to.id, 'handoff-finish', { importId: imp.importId }, { timeoutMs: 240_000 });
+      await rpc(from.id, 'handoff-done', { exportId: exp.exportId, ok: true, machine: to.name, agentId: imp.agentId }, { timeoutMs: 60_000 }).catch((e) => step(`marking it moved failed: ${e.message}`));
+      audit(`${by} moved ${from.name}/${agentId} to ${to.name}/${imp.agentId}`);
+      return { ok: true, from: { machine: from.name, agent: agentId }, to: { machine: to.name, agent: imp.agentId }, agent: fin.agent };
+    } catch (e) {
+      step(`failed: ${e.message}`);
+      if (imp) await rpc(to.id, 'handoff-cancel', { importId: imp.importId }, { timeoutMs: 60_000 }).catch(() => {});
+      await rpc(from.id, 'handoff-done', { exportId: exp.exportId, ok: false }, { timeoutMs: 60_000 }).catch(() => {});
+      audit(`${by} failed to move ${from.name}/${agentId} to ${to.name}: ${e.message}`);
+      throw e;
+    }
+  }
+  const runnerByRef = (ref) => store.data.runners[ref] ?? Object.values(store.data.runners).find((x) => x.name.toLowerCase() === String(ref ?? '').toLowerCase());
+  api.post(
+    '/runners/:id/agents/:agent/move',
+    wrap(async (req) => {
+      const from = runnerByRef(req.params.id);
+      const to = runnerByRef(req.body?.to);
+      if (!from) throw fail(404, `No machine ${req.params.id}`);
+      if (!to) throw fail(400, 'Pick the machine to move it to');
+      if (to.id === from.id) throw fail(400, 'It is already on that machine');
+      for (const r of [from, to]) {
+        const l = live.get(r.id);
+        if (!l?.hello) throw fail(409, `${r.name} is offline`);
+        if (!l.hello.policy.allow.includes('move')) throw fail(403, `${r.name} doesn't allow "move" from the hub`);
+      }
+      return moveAgent(from, String(req.params.agent).slice(0, 40), to, req.auth);
+    }),
+  );
+
   api.post(
     '/runners/:id/actions',
     wrap(async (req) => {
       const r = store.data.runners[req.params.id];
       if (!r) throw fail(404, `No machine ${req.params.id}`);
       const { action, args = {} } = req.body ?? {};
+      if (HANDOFF_STEP.test(String(action))) throw fail(400, 'Moving an agent is one request: POST /api/runners/<machine>/agents/<agent>/move');
       const what = `${String(action).slice(0, 40)}${args.agent ? ` on ${r.name}/${String(args.agent).slice(0, 40)}` : ` on ${r.name}`}`;
       try {
         const out = await rpc(r.id, action, args);

package/src/hubactions.js

@@ -10,11 +10,13 @@
 //   terminal  live Claude terminals
 //   shell     shells in an agent's folder (runs any command: grant with care)
 //   signin    one-time sign-in links to this machine's own page (full access there: grant with care)
+//   move      move agents to and from other machines (their work goes through the repo's remote)
 import { engineOf, installed } from './engines/index.js';
 import { allowedProject } from './fleet.js';
 import { createTicket } from './remote.js';
+import { Handoff } from './handoff.js';
 
-export const PERMISSIONS = ['view', 'inbox', 'control', 'create', 'terminal', 'shell', 'signin'];
+export const PERMISSIONS = ['view', 'inbox', 'control', 'create', 'terminal', 'shell', 'signin', 'move'];
 // The hub may not start agents that skip permission prompts.
 const HUB_PERMISSION_MODES = new Set(['default', 'acceptEdits', 'plan']);
 
@@ -58,8 +60,18 @@ export const ACTIONS = {
   priority: { perm: 'control', run: (m, a, args) => m.update(a.id, { priority: args.priority }) },
   create: { perm: 'create', agentless: true, run: (m, _a, args, policy) => createAgent(m, args, policy) },
   signin: { perm: 'signin', agentless: true, run: () => ({ ticket: createTicket() }) },
+  // Moving an agent between machines (src/handoff.js); both machines must allow "move".
+  'handoff-export': { perm: 'move', raw: true, run: (m, a) => handoffOf(m).export(a) },
+  'handoff-chunk': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).chunk(args.exportId, args.i) },
+  'handoff-done': { perm: 'move', agentless: true, run: (m, _a, args) => handoffOf(m).done(args.exportId, { ok: Boolean(args.ok), machine: args.machine, agentId: args.agentId }) },
+  'handoff-import': { perm: 'move', agentless: true, raw: true, run: (m, _a, args, policy) => handoffOf(m).import(args.manifest, policy, allowedProject) },
+  'handoff-put': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).put(args.importId, args.i, args.data) },
+  'handoff-finish': { perm: 'move', agentless: true, run: (m, _a, args) => handoffOf(m).finish(args.importId) },
+  'handoff-cancel': { perm: 'move', agentless: true, raw: true, run: (m, _a, args) => handoffOf(m).cancel(args.importId) },
 };
 
+const handoffOf = (m) => (m.handoff ??= new Handoff({ manager: m }));
+
 function createAgent(manager, args, policy) {
   const entry = manager.resolveProject(String(args.project ?? ''));
   if (!entry) throw err(400, 'Pick one of the projects this machine shares');
@@ -89,6 +101,7 @@ export async function runAction(manager, policy, action, args = {}) {
   manager.plugins?.check('hub.action', { action, agent: agent ? manager.auditView(agent) : null });
   manager.plugins?.emit('hub.action', { action, agent: agent ? manager.auditView(agent) : null });
   const out = await def.run(manager, agent, args, policy);
+  if (def.raw) return { ok: true, ...out };
   // Enough for the hub to confirm; the next state frame carries the rest.
   if (out?.ticket) return { ok: true, ticket: out.ticket };
   if (Array.isArray(out)) return { ok: true, agents: out.map((a) => ({ id: a.id, name: a.name })) };

package/src/identity.js

@@ -0,0 +1,41 @@
+// Who this Agent Manager runs as, for the menu in the top bar: the computer's user, the Claude
+// account its agents use (as Claude Code recorded it in ~/.claude.json), and the git identity
+// their commits get. Read on request; nothing here leaves the machine.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const gitConfig = (key) =>
+  new Promise((resolve) => execFile('git', ['config', '--global', key], { timeout: 3000 }, (e, out) => resolve(e ? null : out.trim() || null)));
+
+/** The signed-in Claude account from Claude Code's settings file, or null. */
+export function claudeAccount(file = path.join(os.homedir(), '.claude.json')) {
+  try {
+    const a = JSON.parse(fs.readFileSync(file, 'utf8')).oauthAccount;
+    if (!a?.emailAddress) return null;
+    return { email: a.emailAddress, name: a.displayName || a.fullName || null, organization: a.organizationName || null };
+  } catch {
+    return null;
+  }
+}
+
+export async function identity() {
+  const [gitName, gitEmail] = await Promise.all([gitConfig('user.name'), gitConfig('user.email')]);
+  let user = null;
+  try {
+    user = os.userInfo().username;
+  } catch {
+    // No passwd entry (some containers).
+  }
+  const claude = claudeAccount();
+  return {
+    user,
+    host: os.hostname().replace(/\.local$/, ''),
+    claude,
+    git: gitName || gitEmail ? { name: gitName, email: gitEmail } : null,
+    // What the menu shows first: a name, then an email.
+    display: claude?.name || gitName || user || 'You',
+    email: claude?.email || gitEmail || null,
+  };
+}

package/src/manager.js

@@ -1,12 +1,15 @@
 import crypto from 'node:crypto';
 import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import pty from 'node-pty';
 import { expandHome, paths } from './config.js';
 import { DEFAULT_ENGINE, ENGINES, engineOf, installed, notInstalled } from './engines/index.js';
 import {
   DOC_KINDS,
+  diagramsOnly,
+  diagramsPrompt,
   briefDir,
   briefPath,
   briefPrompt,
@@ -32,11 +35,24 @@ const SUMMARIES = {
   insights: { field: 'insights', prompt: insightsPrompt },
   ...Object.fromEntries(Object.keys(DOC_KINDS).map((k) => [k, { doc: k, prompt: (ctx) => docPrompt(k, ctx) }])),
   humanai: { doc: 'humanai', run: 'runHumanAi' },
+  diagrams: { doc: 'diagrams', run: 'runDiagrams' },
 };
 /** Read / write where a summary of `kind` is kept on the agent record. */
 const getSummary = (agent, kind) => (SUMMARIES[kind].doc ? agent.docs?.[kind] : agent[SUMMARIES[kind].field]);
 const summaryPatch = (agent, kind, value) =>
   SUMMARIES[kind].doc ? { docs: { ...agent.docs, [kind]: value } } : { [SUMMARIES[kind].field]: value };
+
+/** The folders of a repo with how many files each holds, two levels deep: a map for drawing it. */
+async function repoLayout(dir) {
+  const files = (await git.run('git', ['ls-files'], { cwd: dir, timeout: 20_000 })).split('\n').filter(Boolean);
+  const counts = new Map();
+  for (const f of files) {
+    const parts = f.split('/');
+    const key = parts.length > 2 ? `${parts[0]}/${parts[1]}/` : parts.length === 2 ? `${parts[0]}/` : f;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts].slice(0, 150).map(([k, n]) => (k.endsWith('/') ? `${k} (${n} files)` : k)).join('\n');
+}
 import { spawn } from 'node:child_process';
 import * as git from './git.js';
 import { conflictMessage, findConflicts, related, repoKey, summarize as summarizeConflicts } from './conflicts.js';
@@ -195,6 +211,9 @@ function loadScrollback(id) {
 }
 const baseLabel = ({ ref, sha }) => `${ref} @ ${sha.slice(0, 9)}`;
 
+/** The id of the machine terminal's shells (agent ids are hex, so it can't clash). */
+export const MACHINE = '__machine__';
+
 export class AgentManager extends EventEmitter {
   constructor({ store, config, plugins = new Plugins() }) {
     super();
@@ -791,6 +810,8 @@ export class AgentManager extends EventEmitter {
   start(ref, { fresh = false, sessionId } = {}) {
     const agent = this.mustGet(ref);
     if (this.closing) throw Object.assign(new Error('AI Agent Manager is shutting down'), { status: 503 });
+    // Its session continues on the other machine; two copies of one conversation would diverge.
+    if (agent.movedTo) throw Object.assign(new Error(`${agent.name} moved to ${agent.movedTo.machine}; it continues there`), { status: 409 });
     const live = this.runtimes.get(agent.id);
     if (!live?.pty) {
       this.plugins.check('agent.start', { agent: this.auditView(agent), fresh });
@@ -841,15 +862,15 @@ export class AgentManager extends EventEmitter {
         resume = true;
       }
     }
-    const args = engine.launchArgs({
-      ...this.launchOptions(agent),
-      sessionId: sid,
-      resume,
-      name: agent.name,
-      // A team member's first message is its first step, not just the problem.
-      prompt: resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent),
-    });
+    // A team member's first message is its first step, not just the problem.
+    const prompt = resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent);
+    const args = engine.launchArgs({ ...this.launchOptions(agent), sessionId: sid, resume, name: agent.name, prompt });
     const proc = this.spawnAgent(agent, agent.workdir, args);
+    // Engines whose resume takes no message get it typed once the session is idle.
+    if (resume && prompt && engine.supports.resumePrompt === false) {
+      if (!this.outbox.has(agent.id)) this.outbox.set(agent.id, []);
+      this.outbox.get(agent.id).unshift({ text: prompt, source: 'system', at: now() });
+    }
 
     const session = agent.sessions.find((s) => s.id === sid);
     if (session) {
@@ -1096,7 +1117,8 @@ export class AgentManager extends EventEmitter {
         done.dispose();
         resolve(this.view(this.store.get(agent.id) ?? agent));
       });
-      rt.pty.kill('SIGHUP');
+      // A hangup, as when a terminal closes, unless the engine shuts down cleanly on another signal.
+      rt.pty.kill(engineOf(agent).stopSignal ?? 'SIGHUP');
       rt.killTimer = setTimeout(() => rt.pty?.kill('SIGKILL'), timeoutMs);
     });
   }
@@ -1162,7 +1184,7 @@ export class AgentManager extends EventEmitter {
   }
 
   childEnv(agent) {
-    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor' };
+    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor', AGENTMGR_TERMINAL: '1' };
     for (const key of STRIP_ENV) delete env[key];
     return env;
   }
@@ -1354,7 +1376,8 @@ export class AgentManager extends EventEmitter {
 
   /** Start (if needed) login shell number `n` in the agent's folder, for running commands by hand. */
   openShell(ref, n = 1) {
-    const agent = this.mustGet(ref);
+    // The machine terminal: a shell in the home folder, not tied to any agent.
+    const agent = ref === MACHINE ? { id: MACHINE, workdir: os.homedir(), machine: true } : this.mustGet(ref);
     const shells = this.shellsOf(agent.id);
     const prev = shells.get(n);
     if (prev?.pty) return prev;
@@ -1375,7 +1398,7 @@ export class AgentManager extends EventEmitter {
       cols: rt.cols,
       rows: rt.rows,
       cwd: agent.workdir,
-      env: this.childEnv(agent),
+      env: this.childEnv(agent.machine ? null : agent),
     });
     rt.pty = proc;
     shells.set(n, rt);
@@ -1390,7 +1413,7 @@ export class AgentManager extends EventEmitter {
       const a = this.store.get(agent.id);
       if (a) this.changed(a);
     });
-    this.changed(agent);
+    if (!agent.machine) this.changed(agent);
     return rt;
   }
 
@@ -1403,8 +1426,8 @@ export class AgentManager extends EventEmitter {
   }
 
   attachShell(ref, client, n = 1) {
-    const agent = this.mustGet(ref);
-    this.plugins.check('terminal.open', { agent: this.auditView(agent), kind: `shell:${n}` });
+    const agent = ref === MACHINE ? { id: MACHINE } : this.mustGet(ref);
+    this.plugins.check('terminal.open', ref === MACHINE ? { agent: null, kind: 'machine' } : { agent: this.auditView(agent), kind: `shell:${n}` });
     const rt = this.openShell(agent.id, n);
     rt.clients.add(client);
     return {
@@ -1919,8 +1942,10 @@ export class AgentManager extends EventEmitter {
 
   /** One tool-less, read-only call to an engine; resolves to its text output. */
   oneShot(agent, text, { engine, model, timeoutMs = 300_000 }) {
-    // Some engines take the prompt as an argument instead of on stdin.
-    const args = [...engine.extraArgs(this.config), ...engine.oneShotArgs(this.config, { model, prompt: text })];
+    // Some engines take the prompt as an argument instead of on stdin, and some need their extra
+    // arguments after a subcommand (oneShotExtra: they place them).
+    const extra = engine.extraArgs(this.config);
+    const args = engine.oneShotExtra ? engine.oneShotArgs(this.config, { model, prompt: text, extra }) : [...extra, ...engine.oneShotArgs(this.config, { model, prompt: text })];
     return new Promise((resolve, reject) => {
       const child = spawn(engine.bin(this.config), args, { cwd: paths.home, env: this.childEnv(agent), stdio: ['pipe', 'pipe', 'pipe'] });
       let out = '';
@@ -1938,6 +1963,37 @@ export class AgentManager extends EventEmitter {
     });
   }
 
+  /** Diagrams only: the problem and its solution drawn from the documents already written and the live context. */
+  async runDiagrams(agent, ctx) {
+    const cur0 = this.store.get(agent.id) ?? agent;
+    const written = [
+      ...['analysis', 'design', 'flow', 'proposal'].map((k) => [DOC_KINDS[k].title, cur0.docs?.[k]?.markdown]),
+      ['Implementation plan', cur0.planReview?.markdown],
+      ['Explanation', cur0.explanation?.markdown],
+    ].filter(([, md]) => md);
+    const documents = written.map(([title, md]) => `<document title="${title}">\n${md.slice(0, 12_000)}\n</document>`).join('\n');
+    const repoMap = agent.workdir ? await repoLayout(agent.workdir).catch(() => '') : '';
+    const writer = this.writerFor(agent);
+    const markdown = diagramsOnly(await this.oneShot(agent, diagramsPrompt({ ...ctx, documents, repoMap }), writer));
+    const cur = this.store.get(agent.id);
+    if (!cur) return null;
+    const from = written.map(([title]) => title);
+    return this.view(
+      this.patch(
+        agent.id,
+        summaryPatch(cur, 'diagrams', {
+          markdown,
+          from,
+          writer: `${writer.engine.label}${writer.model ? ` (${writer.model})` : ''}`,
+          at: now(),
+          briefUpdatedAt: cur.brief?.updatedAt ?? null,
+          pending: false,
+          error: null,
+        }),
+      ),
+    );
+  }
+
   /** Human vs AI: the writer splits and answers the open questions, then another model double-checks it. */
   async runHumanAi(agent, ctx) {
     const writer = this.writerFor(agent);