ai-agentmanager 1.3.1 → 1.4.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,6 +1,7 @@
 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';
@@ -195,6 +196,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 +795,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 });
@@ -1354,7 +1360,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 +1382,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 +1397,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 +1410,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 {

package/src/server.js

@@ -1,13 +1,14 @@
 import fs from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
+import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { WebSocketServer } from 'ws';
 import { ensureHome, HOST, loadConfig, paths, PORT, saveConfig } from './config.js';
-import { AgentManager, shellNumber } from './manager.js';
+import { AgentManager, MACHINE, shellNumber } from './manager.js';
 import { Backlog } from './backlog.js';
 import { Races } from './races.js';
 import { Review } from './review.js';
@@ -18,6 +19,9 @@ import { Landing } from './landing.js';
 import { Budgets } from './budgets.js';
 import { stats } from './stats.js';
 import { Playbooks } from './playbooks.js';
+import { Updates } from './update.js';
+import { identity } from './identity.js';
+import { Studio } from './studio.js';
 import { Memory } from './memory.js';
 import { doctor } from './doctor.js';
 import { Triggers, tokenMatches } from './triggers.js';
@@ -55,7 +59,7 @@ function isAllowedOrigin(origin, port) {
 }
 
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|update(\/|$)|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
 const HOOK_PATH = '/api/hooks/agents';
 const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
@@ -69,6 +73,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const backlog = new Backlog({ manager, store, config });
   const races = new Races({ manager, store });
   const review = new Review({ manager });
+  const studio = new Studio({ manager, review });
   const teams = new Teams({ manager, store, config });
   const cleanup = new Cleanup({ manager, store, config, teams });
   const landing = new Landing({ manager, store, config });
@@ -87,6 +92,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const budgets = new Budgets({ manager, store, config, notifier });
   const playbooks = new Playbooks({ manager, store });
   const memory = new Memory({ manager, config });
+  const updates = new Updates({ config });
   let remoteServer = null;
   let remotePort = null;
   // Live browser tabs: what a page does is saved on the agent's tab; popups become new tabs.
@@ -233,6 +239,23 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/plan/changes', wrap((req) => manager.requestPlanChanges(req.params.id, req.body?.note)));
   api.post('/agents/:id/plan/review', wrap((req) => manager.setPlanReview(req.params.id, req.body?.on === true)));
   api.post('/agents/:id/handoff', wrap((req) => manager.maybeHandoff(manager.mustGet(req.params.id).id, { force: true })));
+  // ---------------------------------------------------------- studio: files and editor
+  api.get('/agents/:id/files', wrap((req) => studio.list(req.params.id, req.query.dir ?? '')));
+  api.post('/agents/:id/files', wrap((req) => studio.create(req.params.id, req.body?.path, req.body?.type)));
+  api.post('/agents/:id/files/rename', wrap((req) => studio.rename(req.params.id, req.body?.from, req.body?.to)));
+  api.get('/agents/:id/file', wrap((req) => studio.read(req.params.id, req.query.path)));
+  api.put('/agents/:id/file', wrap((req) => studio.write(req.params.id, req.body?.path, req.body?.content, { mtimeMs: req.body?.mtimeMs ?? null, force: Boolean(req.body?.force) })));
+  api.delete('/agents/:id/file', wrap((req) => studio.remove(req.params.id, req.query.path)));
+  api.get('/agents/:id/file/original', wrap((req) => studio.original(req.params.id, req.query.path)));
+  api.get('/agents/:id/search', wrap((req) => studio.search(req.params.id, req.query.q)));
+  // Opening VS Code or Cursor happens on this computer, so only from it.
+  api.get('/editors', wrap(() => studio.editors()));
+  api.post('/agents/:id/open-in', wrap((req) => studio.openIn(req.params.id, req.body?.editor, req.body?.path ?? null)));
+  // The machine terminal: shells in the home folder, not tied to an agent (Open Terminal).
+  api.get('/machine/shells', wrap(() => ({ shells: manager.shellNumbers(MACHINE), home: os.homedir() })));
+  api.post('/machine/shell/new', wrap(() => ({ n: manager.nextShellNumber(MACHINE) })));
+  api.post('/machine/shell/close', wrap((req) => manager.closeShell(MACHINE, req.body?.n ? Number(req.body.n) : undefined)));
+  api.post('/machine/shell/drop', wrap((req) => manager.dropShell(MACHINE, Number(req.body?.n) || 1)));
   api.post('/agents/:id/shell/close', wrap((req) => manager.closeShell(req.params.id, req.body?.n ? Number(req.body.n) : undefined)));
   api.post('/agents/:id/shell/new', wrap((req) => ({ n: manager.nextShellNumber(manager.mustGet(req.params.id).id) })));
   api.post('/agents/:id/shell/drop', wrap((req) => manager.dropShell(req.params.id, Number(req.body?.n) || 1)));
@@ -409,6 +432,18 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/review/ack', wrap((req) => manager.ackReview(req.params.id, req.body?.action)));
   api.get('/about', wrap(() => about({ port, config: { home: paths.home, claudeBin: config.claudeBin } })));
   api.get('/about/latest', wrap(() => latestRelease()));
+  api.get('/me', wrap(async (req) => ({ ...(await identity()), remote: Boolean(req.remote) })));
+  // Updating runs npm or git here and restarts the daemon, so only from this computer.
+  api.get('/update', wrap(() => updates.status()));
+  api.post('/update/check', wrap(async () => (await updates.refresh(), updates.status())));
+  api.post('/update', wrap(() => updates.apply()));
+  api.put(
+    '/update',
+    wrap((req) => {
+      saveConfig({ updates: updates.setCheck(req.body?.check !== false) });
+      return updates.status();
+    }),
+  );
   api.get('/judge', wrap(() => manager.judge.status()));
   // On or off for this daemon, kept in config.json. The judge spends calls on your own engine plan.
   api.put('/judge', wrap((req) => {
@@ -651,14 +686,17 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   });
 
   const termKind = (q) => (shellNumber(q) ? `shell:${shellNumber(q)}` : 'claude');
+  // The machine terminal (Open Terminal) has no agent: its shells live under MACHINE.
+  const termAgent = (id) => (id === MACHINE ? { id: MACHINE } : manager.mustGet(id));
   const attachTerm = (id, kind, client) =>
     shellNumber(kind) ? manager.attachShell(id, client, shellNumber(kind)) : manager.attach(id, client);
   api.get('/agents/:id/term/stream', (req, res) => {
     let agent;
     const kind = termKind(req.query.kind);
     try {
-      agent = manager.mustGet(req.params.id);
-      manager.plugins.check('terminal.open', { agent: manager.auditView(agent), kind });
+      agent = termAgent(req.params.id);
+      if (agent.id === MACHINE) manager.plugins.check('terminal.open', { agent: null, kind: 'machine' });
+      else manager.plugins.check('terminal.open', { agent: manager.auditView(agent), kind });
     } catch (err) {
       return res.status(err.status || 404).json({ error: err.message });
     }
@@ -699,7 +737,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post(
     '/agents/:id/term/input',
     wrap((req) => {
-      const agent = manager.mustGet(req.params.id);
+      const agent = termAgent(req.params.id);
       if (typeof req.body?.d !== 'string') throw fail(400, 'd (string) is required');
       manager.write(agent.id, req.body.d, termKind(req.body.kind));
       return { ok: true };
@@ -708,7 +746,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post(
     '/agents/:id/term/resize',
     wrap((req) => {
-      const agent = manager.mustGet(req.params.id);
+      const agent = termAgent(req.params.id);
       manager.resize(agent.id, req.body?.cols | 0, req.body?.rows | 0, termKind(req.body?.kind));
       return { ok: true };
     }),
@@ -780,12 +818,13 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     if (!m) return ws.close(1008, 'unknown endpoint');
     let session;
     try {
-      const agent = manager.mustGet(m[1]);
+      // The machine terminal has no agent; its shells live under MACHINE.
+      const agent = m[1] === MACHINE ? { id: MACHINE } : manager.mustGet(m[1]);
       const client = {
         send: (msg) => ws.readyState === ws.OPEN && ws.send(JSON.stringify(msg)),
         close: () => ws.close(1000, 'agent removed'),
       };
-      const kind = termKind(url.searchParams.get('kind'));
+      const kind = agent.id === MACHINE ? `shell:${shellNumber(url.searchParams.get('kind')) || 1}` : termKind(url.searchParams.get('kind'));
       session = attachTerm(agent.id, kind, client);
       client.send({ t: 'hello', id: agent.id, kind, running: session.running, backlog: session.backlog });
       ws.on('message', (raw) => {
@@ -854,6 +893,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     triggers.close();
     budgets.close();
     playbooks.close();
+    updates.close();
     assistant.close();
     console.log(`[agentmgr] shutting down (${reason}); closing agents so their sessions are saved`);
     await manager.stopAll({ final: true });