ai-agentmanager 1.3.0 → 1.4.0

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 {
@@ -1991,18 +1998,19 @@ export class AgentManager extends EventEmitter {
     const id = this.mustGet(ref).id;
     const running = this.refreshing.get(id);
     if (running) {
-      // A pull request check asked for during a plain refresh runs right after it.
-      if (!withPrs || running.withPrs) return running.promise.then(() => this.store.get(id) && this.view(this.store.get(id)));
-      await running.promise.catch(() => {});
-      return this.refresh(id, { withPrs });
-    }
-    const promise = this.doRefresh(id, { withPrs });
-    this.refreshing.set(id, { promise, withPrs });
-    try {
-      return await promise;
-    } finally {
-      this.refreshing.delete(id);
-    }
+      if (!withPrs) return running.promise.then(() => this.store.get(id) && this.view(this.store.get(id)));
+      // A pull request check runs again after the one in progress, which may have read PRs from
+      // before this request; callers arriving meanwhile share that next run.
+      running.next ??= running.promise.catch(() => {}).then(() => this.refresh(id, { withPrs }));
+      return running.next;
+    }
+    // Cleared before anyone waiting on it continues, so the next run starts afresh.
+    const entry = { withPrs };
+    entry.promise = this.doRefresh(id, { withPrs }).finally(() => {
+      if (this.refreshing.get(id) === entry) this.refreshing.delete(id);
+    });
+    this.refreshing.set(id, entry);
+    return entry.promise;
   }
 
   async doRefresh(id, { withPrs }) {

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.
@@ -193,7 +199,8 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   };
   const fail = (status, message) => Object.assign(new Error(message), { status });
 
-  api.get('/health', wrap(() => ({ ok: true, pid: process.pid, home: paths.home, claudeBin: config.claudeBin })));
+  // `closing` while shutting down: it still answers until every agent is closed, then exits.
+  api.get('/health', wrap(() => ({ ok: true, pid: process.pid, home: paths.home, claudeBin: config.claudeBin, closing })));
   api.get('/agents', wrap(() => manager.list()));
   api.get('/engines', wrap(() => listEngines(config)));
   api.post(
@@ -232,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)));
@@ -408,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) => {
@@ -650,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 });
     }
@@ -698,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 };
@@ -707,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 };
     }),
@@ -779,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) => {
@@ -853,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 });

package/src/studio.js

@@ -0,0 +1,255 @@
+// The studio: browse and edit an agent's files from the app (a file tree and an editor), search
+// them, compare a file with where the agent started, and open the folder in VS Code or Cursor.
+// Every path is resolved inside the agent's folder; links that point outside it are refused.
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as git from './git.js';
+import { NO_REPO } from './manager.js';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+export const MAX_FILE_BYTES = 2_000_000;
+// Listed but not opened by default: noisy, huge or generated.
+export const HIDDEN = new Set(['.git', 'node_modules', '.DS_Store', '__pycache__', '.venv', 'dist', 'build', '.next', 'target', 'coverage']);
+const EDITORS = {
+  vscode: { label: 'VS Code', bins: ['code', '/usr/local/bin/code', '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code'] },
+  cursor: { label: 'Cursor', bins: ['cursor', '/usr/local/bin/cursor', '/Applications/Cursor.app/Contents/Resources/app/bin/cursor'] },
+};
+
+/**
+ * `rel` inside `root`, as an absolute path, or an error. Refuses "..", absolute paths and
+ * symlinks that resolve outside the folder (checked on the nearest part that exists).
+ */
+export function resolveInside(root, rel = '') {
+  const realRoot = fs.realpathSync(root);
+  const clean = String(rel ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  if (clean.split('/').includes('..')) throw err(400, 'Paths may not contain ".."');
+  const abs = path.join(realRoot, clean);
+  let probe = abs;
+  while (!fs.existsSync(probe) && probe !== realRoot) probe = path.dirname(probe);
+  const real = fs.realpathSync(probe);
+  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) throw err(403, 'That path is outside the agent folder');
+  return abs;
+}
+
+const statOf = (abs, rel) => {
+  try {
+    return fs.statSync(abs);
+  } catch {
+    throw err(404, `${rel || 'That path'} doesn't exist`);
+  }
+};
+
+/** True when the bytes look like text (no NUL in the first 8 KB). */
+export const isText = (buf) => !buf.subarray(0, 8192).includes(0);
+
+/** A language id for the editor from a file name. */
+export function languageOf(name) {
+  const ext = path.extname(name).toLowerCase().slice(1);
+  const base = path.basename(name).toLowerCase();
+  if (base === 'dockerfile') return 'dockerfile';
+  if (base === 'makefile') return 'makefile';
+  const map = {
+    js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript', ts: 'typescript', tsx: 'typescript', json: 'json', md: 'markdown',
+    py: 'python', rb: 'ruby', go: 'go', rs: 'rust', java: 'java', kt: 'kotlin', swift: 'swift', c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', hpp: 'cpp',
+    cs: 'csharp', php: 'php', sh: 'shell', bash: 'shell', zsh: 'shell', yml: 'yaml', yaml: 'yaml', toml: 'ini', ini: 'ini', html: 'html', css: 'css',
+    scss: 'scss', less: 'less', sql: 'sql', xml: 'xml', svg: 'xml', vue: 'html', graphql: 'graphql', lua: 'lua', r: 'r', scala: 'scala', dart: 'dart',
+  };
+  return map[ext] ?? 'plaintext';
+}
+
+const which = (bin) => new Promise((resolve) => (bin.startsWith('/') ? resolve(fs.existsSync(bin) ? bin : null) : execFile('/usr/bin/env', ['which', bin], (e, out) => resolve(e ? null : out.trim() || null))));
+
+export class Studio {
+  constructor({ manager, review }) {
+    this.manager = manager;
+    this.review = review;
+  }
+
+  agentDir(ref) {
+    const agent = this.manager.mustGet(ref);
+    if (NO_REPO.has(agent.kind) && !agent.workdir) throw err(400, 'This session has no folder');
+    if (!agent.workdir || !fs.existsSync(agent.workdir)) throw err(409, 'The agent folder is not ready yet');
+    return { agent, root: agent.workdir };
+  }
+
+  check(agent, action, details = {}) {
+    this.manager.plugins.check(action, { agent: this.manager.auditView(agent), ...details });
+  }
+
+  /** One folder's entries: folders first, then files, by name. */
+  list(ref, dir = '') {
+    const { root } = this.agentDir(ref);
+    const abs = resolveInside(root, dir);
+    if (!statOf(abs, dir).isDirectory()) throw err(400, 'Not a folder');
+    const entries = fs
+      .readdirSync(abs, { withFileTypes: true })
+      .map((d) => {
+        const rel = path.posix.join(String(dir).replace(/^\/+|\/+$/g, ''), d.name);
+        let type = d.isDirectory() ? 'dir' : 'file';
+        let size = null;
+        if (d.isSymbolicLink()) {
+          try {
+            const st = fs.statSync(resolveInside(root, rel));
+            type = st.isDirectory() ? 'dir' : 'file';
+            size = st.isFile() ? st.size : null;
+          } catch {
+            type = 'link';
+          }
+        } else if (type === 'file') {
+          try {
+            size = fs.statSync(path.join(abs, d.name)).size;
+          } catch {}
+        }
+        return { name: d.name, path: rel, type, size, hidden: HIDDEN.has(d.name) };
+      })
+      .sort((a, b) => (a.type === 'dir') - (b.type === 'dir') ? (b.type === 'dir') - (a.type === 'dir') : a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+    return { root, dir: String(dir).replace(/^\/+|\/+$/g, ''), entries };
+  }
+
+  read(ref, rel) {
+    const { root } = this.agentDir(ref);
+    const abs = resolveInside(root, rel);
+    const st = statOf(abs, rel);
+    if (!st.isFile()) throw err(400, 'Not a file');
+    const base = { path: rel, size: st.size, mtimeMs: st.mtimeMs, language: languageOf(rel) };
+    if (st.size > MAX_FILE_BYTES) return { ...base, tooLarge: true, max: MAX_FILE_BYTES };
+    const buf = fs.readFileSync(abs);
+    if (!isText(buf)) return { ...base, binary: true };
+    return { ...base, content: buf.toString('utf8') };
+  }
+
+  /** Save a file. With `mtimeMs` (from when it was opened), refuses if it changed since. */
+  write(ref, rel, content, { mtimeMs = null, force = false } = {}) {
+    const { agent, root } = this.agentDir(ref);
+    if (typeof content !== 'string') throw err(400, 'content (string) is required');
+    if (Buffer.byteLength(content) > MAX_FILE_BYTES) throw err(413, `Files over ${MAX_FILE_BYTES / 1e6} MB can't be saved from the editor`);
+    const abs = resolveInside(root, rel);
+    this.check(agent, 'agent.files', { op: 'write', path: rel });
+    if (fs.existsSync(abs)) {
+      const st = fs.statSync(abs);
+      if (!st.isFile()) throw err(400, 'Not a file');
+      if (mtimeMs != null && !force && Math.abs(st.mtimeMs - Number(mtimeMs)) > 1) {
+        throw Object.assign(err(409, 'The file changed on disk since you opened it (the agent may have edited it)'), { conflict: true });
+      }
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+    const st = fs.statSync(abs);
+    return { path: rel, size: st.size, mtimeMs: st.mtimeMs };
+  }
+
+  create(ref, rel, type = 'file') {
+    const { agent, root } = this.agentDir(ref);
+    if (!String(rel ?? '').trim()) throw err(400, 'A name is required');
+    const abs = resolveInside(root, rel);
+    if (fs.existsSync(abs)) throw err(409, `${rel} already exists`);
+    this.check(agent, 'agent.files', { op: 'create', path: rel });
+    if (type === 'dir') fs.mkdirSync(abs, { recursive: true });
+    else {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, '');
+    }
+    return { path: rel, type };
+  }
+
+  rename(ref, from, to) {
+    const { agent, root } = this.agentDir(ref);
+    const a = resolveInside(root, from);
+    const b = resolveInside(root, to);
+    if (!fs.existsSync(a)) throw err(404, `${from} doesn't exist`);
+    if (fs.existsSync(b)) throw err(409, `${to} already exists`);
+    if (a === fs.realpathSync(root)) throw err(400, "The agent folder itself can't be renamed");
+    this.check(agent, 'agent.files', { op: 'rename', path: from, to });
+    fs.mkdirSync(path.dirname(b), { recursive: true });
+    fs.renameSync(a, b);
+    return { from, to };
+  }
+
+  remove(ref, rel) {
+    const { agent, root } = this.agentDir(ref);
+    const abs = resolveInside(root, rel);
+    if (abs === fs.realpathSync(root) || !String(rel ?? '').trim()) throw err(400, "The agent folder itself can't be deleted here");
+    if (!fs.existsSync(abs)) throw err(404, `${rel} doesn't exist`);
+    this.check(agent, 'agent.files', { op: 'delete', path: rel });
+    fs.rmSync(abs, { recursive: true, force: true });
+    return { path: rel, deleted: true };
+  }
+
+  /** Text search: git grep in a repository (ignored files skipped), else a bounded walk. */
+  async search(ref, q, { max = 200 } = {}) {
+    const { root } = this.agentDir(ref);
+    const term = String(q ?? '');
+    if (term.trim().length < 2) throw err(400, 'Search for at least 2 characters');
+    const hits = [];
+    if (await git.isGitRepo(root)) {
+      const out = await git
+        .run('git', ['grep', '-n', '-I', '--untracked', '--fixed-strings', '-i', '--full-name', '-e', term], { cwd: root, timeout: 20_000 })
+        .catch((e) => (e.code === 1 ? '' : Promise.reject(e)));
+      for (const line of out.split('\n')) {
+        const m = line.match(/^(.*?):(\d+):(.*)$/);
+        if (m) hits.push({ path: m[1], line: Number(m[2]), text: m[3].slice(0, 300) });
+        if (hits.length >= max) break;
+      }
+      return { q: term, hits, truncated: hits.length >= max };
+    }
+    const lower = term.toLowerCase();
+    const walk = (dir) => {
+      for (const d of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+        if (hits.length >= max) return;
+        if (HIDDEN.has(d.name)) continue;
+        const rel = path.posix.join(dir, d.name);
+        if (d.isDirectory()) walk(rel);
+        else if (d.isFile()) {
+          const buf = fs.readFileSync(path.join(root, rel));
+          if (buf.length > MAX_FILE_BYTES || !isText(buf)) continue;
+          buf.toString('utf8').split('\n').forEach((text, i) => {
+            if (hits.length < max && text.toLowerCase().includes(lower)) hits.push({ path: rel, line: i + 1, text: text.slice(0, 300) });
+          });
+        }
+      }
+    };
+    walk('');
+    return { q: term, hits, truncated: hits.length >= max };
+  }
+
+  /** The file as it was where the agent started (its base), for a side-by-side diff. */
+  async original(ref, rel) {
+    const { agent, root } = this.agentDir(ref);
+    resolveInside(root, rel);
+    if (!(await git.isGitRepo(root))) return { path: rel, content: null, why: 'Not a git repository' };
+    const base = await this.review.base(agent).catch(() => null);
+    const at = base?.sha ?? 'HEAD';
+    const prefix = (await git.run('git', ['rev-parse', '--show-prefix'], { cwd: root }).catch(() => '')).trim();
+    const content = await git.run('git', ['show', `${at}:${prefix}${rel}`], { cwd: root, timeout: 10_000, trim: false }).catch(() => null);
+    return { path: rel, content, base: base?.ref ?? 'HEAD', new: content === null };
+  }
+
+  /** Editors on this machine that can open the folder. */
+  async editors() {
+    const found = [];
+    for (const [id, e] of Object.entries(EDITORS)) {
+      for (const bin of e.bins) {
+        const at = await which(bin);
+        if (at) {
+          found.push({ id, label: e.label, bin: at });
+          break;
+        }
+      }
+    }
+    return found;
+  }
+
+  /** Open the agent's folder (and a file in it) in VS Code or Cursor on this machine. */
+  async openIn(ref, editor = 'vscode', rel = null) {
+    const { root } = this.agentDir(ref);
+    const e = (await this.editors()).find((x) => x.id === editor);
+    if (!e) throw err(404, `${EDITORS[editor]?.label ?? editor} isn't installed (its "${editor === 'cursor' ? 'cursor' : 'code'}" command wasn't found)`);
+    const args = [root];
+    if (rel) args.push('--goto', resolveInside(root, rel));
+    const child = spawn(e.bin, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+    return { ok: true, editor: e.label, folder: root };
+  }
+}