dsh-thoughtdag 0.4.9 → 0.4.11

package/lib/runtime/agents/codex.cjs

@@ -0,0 +1,380 @@
+// Codex as an agent runtime: one long-lived `codex app-server` (JSON-RPC 2.0
+// over stdio, newline-delimited). A run is one turn on one thread: fresh
+// (`thread/start` in the working directory), continued (`thread/resume`),
+// or branched (`thread/fork`). The server's notifications become the same
+// event kinds the Pi runtime emits, so the renderer reads nothing new:
+// text and reasoning deltas, tool starts and ends, questions (the server's
+// own approval and user-input requests), run_end. Codex keeps its rollout
+// files, login and model list; the shell only asks.
+'use strict';
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const { randomUUID } = require('node:crypto');
+const { snapshotDir, diffSnapshots } = require('./fs-diff.cjs');
+
+const fsp = fs.promises;
+const RESPONSE_MS = 30 * 1000;
+const CANDIDATE_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', path.join(os.homedir(), '.bun', 'bin'), path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.local', 'bin')];
+
+async function executable(p) { try { await fsp.access(p, fs.constants.X_OK); return true; } catch { return false; } }
+async function findCodex() {
+  const names = process.platform === 'win32' ? ['codex.cmd', 'codex.exe', 'codex'] : ['codex'];
+  const dirs = [...(process.env.PATH || '').split(path.delimiter), ...CANDIDATE_DIRS].filter(Boolean);
+  for (const d of dirs) for (const n of names) { const p = path.join(d, n); if (await executable(p)) return p; }
+  return null;
+}
+function childEnv() {
+  const seen = new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean));
+  return { ...process.env, PATH: [...seen, ...CANDIDATE_DIRS.filter((d) => !seen.has(d))].join(path.delimiter) };
+}
+
+/** The guard file the canvas writes per working directory, as Codex policy. */
+async function policyFor(cwd) {
+  try {
+    const raw = JSON.parse(await fsp.readFile(path.join(cwd, '.thoughtdag', 'guard.json'), 'utf8'));
+    if (raw?.mode === 'allow') return { approvalPolicy: 'never', sandbox: 'danger-full-access' };
+  } catch { /* default */ }
+  return { approvalPolicy: 'on-request', sandbox: 'workspace-write' };
+}
+
+// the thread id is in the rollout's file name; take the LAST UUID in the
+// path in case a directory carries one of its own
+const threadIdOf = (sessionPath) => {
+  const all = String(sessionPath ?? '').match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi);
+  return all && all.length ? all[all.length - 1] : null;
+};
+
+function createCodexRuntime({ log } = {}) {
+  const say = log || (() => {});
+  let proc = null;            // the app-server child
+  let ready = null;           // initialize handshake
+  let buf = '';
+  let nextId = 1;
+  const pending = new Map();  // our request id → resolve
+  const runs = new Map();     // runId → run state
+  const byThread = new Map(); // threadId → runId
+  const serverAsks = new Map(); // question id → { rpcId, respond(answer) }
+  let binPromise = null;
+  const bin = () => { if (!binPromise) binPromise = findCodex(); return binPromise; };
+
+  const write = (obj) => { try { proc.stdin.write(JSON.stringify(obj) + '\n'); return true; } catch { return false; } };
+  const send = (method, params, timeoutMs = RESPONSE_MS) => new Promise((resolve, reject) => {
+    if (!proc) return reject(new Error('codex app-server is not running'));
+    lastUse = Date.now();
+    const id = nextId++;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`codex did not answer ${method} in ${timeoutMs / 1000}s`)); }, timeoutMs);
+    pending.set(id, (msg) => { clearTimeout(timer); if (msg.error) reject(new Error(msg.error.message || `codex refused ${method}`)); else resolve(msg.result); });
+    if (!write({ jsonrpc: '2.0', id, method, params })) { clearTimeout(timer); pending.delete(id); reject(new Error('codex stdin closed')); }
+  });
+
+  // The app-server retires after SERVER_IDLE_MS without a run or a request:
+  // a catalog read at picker time must not pin a hundred megabytes for the
+  // rest of the launch. The next run starts it again.
+  const SERVER_IDLE_MS = Number(process.env.TD_AGENT_IDLE_MS) || 10 * 60 * 1000;
+  let lastUse = Date.now();
+  const retire = setInterval(() => {
+    if (!proc || runs.size || pending.size || Date.now() - lastUse < SERVER_IDLE_MS) return;
+    say('codex app-server idle; stopping it');
+    try { proc.kill(); } catch { /* gone */ }
+    proc = null; ready = null;
+  }, 30 * 1000);
+  retire.unref?.();
+
+  const die = (reason) => {
+    for (const p of pending.values()) p({ error: { message: reason } });
+    pending.clear();
+    for (const r of runs.values()) { r.emit({ type: 'run_error', message: reason }); r.end('exit'); }
+    proc = null; ready = null;
+  };
+
+  async function ensureServer() {
+    if (proc && ready) return ready;
+    const b = await bin();
+    if (!b) throw new Error('codex is not installed (no `codex` on PATH or in the usual places)');
+    proc = spawn(b, ['app-server'], { env: childEnv(), stdio: ['pipe', 'pipe', 'pipe'] });
+    buf = '';
+    proc.stdout.on('data', (d) => {
+      buf += d.toString();
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i); buf = buf.slice(i + 1);
+        if (!line.trim()) continue;
+        let msg; try { msg = JSON.parse(line); } catch { continue; }
+        dispatch(msg);
+      }
+    });
+    proc.stderr.on('data', (d) => say('[codex stderr] ' + d.toString().trim().slice(0, 400)));
+    proc.on('error', (e) => die('spawn error: ' + e.message));
+    proc.on('exit', (code, signal) => die(`codex exited (${signal || code})`));
+    ready = send('initialize', { clientInfo: { name: 'thoughtdag', title: 'ThoughtDAG', version: '0.5.0' }, capabilities: null })
+      .then(() => { write({ jsonrpc: '2.0', method: 'initialized', params: {} }); });
+    return ready;
+  }
+
+  // the effort a turn ran at, as the rollout records it (turn_context.effort):
+  // the model's own default when the canvas named none
+  async function turnEffortOf(file) {
+    if (!file) return null;
+    try {
+      const lines = (await fsp.readFile(file, 'utf8')).split('\n');
+      for (let i = lines.length - 1; i >= 0; i--) {
+        if (!lines[i].includes('"turn_context"')) continue;
+        try { const o = JSON.parse(lines[i]); if (o.type === 'turn_context' && typeof o.payload?.effort === 'string') return o.payload.effort; } catch { /* torn line */ }
+      }
+    } catch { /* no file yet */ }
+    return null;
+  }
+
+  // ~/.codex/config.toml `model_reasoning_effort` overrides every model's own
+  // default; the picker's 'default' must name what a turn will actually use
+  async function configuredEffort() {
+    try {
+      const home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+      const m = (await fsp.readFile(path.join(home, 'config.toml'), 'utf8')).match(/^\s*model_reasoning_effort\s*=\s*"([^"]+)"/m);
+      return m ? m[1] : null;
+    } catch { return null; }
+  }
+
+  const runOf = (threadId) => { const id = byThread.get(threadId); return id ? runs.get(id) : undefined; };
+
+  // ── the server speaks: responses, notifications, and its own requests ──
+  function dispatch(msg) {
+    lastUse = Date.now();
+    if (msg.id !== undefined && msg.method === undefined) { const p = pending.get(msg.id); if (p) { pending.delete(msg.id); p(msg); } return; }
+    const params = msg.params ?? {};
+    const run = runOf(params.threadId);
+    if (msg.id !== undefined && msg.method) { serverRequest(msg, run); return; }
+    if (!run) return;
+    switch (msg.method) {
+      case 'item/agentMessage/delta':
+        run.text += String(params.delta ?? '');
+        run.emit({ type: 'message_update', assistantMessageEvent: { type: 'text_delta', delta: String(params.delta ?? '') } });
+        break;
+      case 'item/reasoning/textDelta':
+      case 'item/reasoning/summaryTextDelta':
+        run.emit({ type: 'message_update', assistantMessageEvent: { type: 'thinking_delta', delta: String(params.delta ?? '') } });
+        break;
+      case 'item/started': {
+        const it = params.item ?? {};
+        const t = toolOf(it);
+        if (t) run.emit({ type: 'tool_execution_start', toolCallId: it.id, toolName: t.name, args: t.args });
+        break;
+      }
+      case 'item/completed': {
+        const it = params.item ?? {};
+        if (it.type === 'agentMessage' && typeof it.text === 'string') run.final = it.text;
+        const t = toolOf(it);
+        if (t) run.emit({ type: 'tool_execution_end', toolCallId: it.id, toolName: t.name, result: t.result, isError: t.isError });
+        break;
+      }
+      case 'turn/completed': {
+        const turn = params.turn ?? {};
+        if (turn.status === 'failed') run.emit({ type: 'run_error', message: turn.error?.message ?? 'the turn failed' });
+        run.end(turn.status === 'interrupted' ? 'aborted' : turn.status === 'failed' ? 'error' : 'end');
+        break;
+      }
+      default: break;
+    }
+  }
+
+  /** A thread item as a tool call, for the trace and the record. */
+  function toolOf(it) {
+    switch (it.type) {
+      case 'commandExecution': return { name: 'bash', args: { command: it.command, cwd: it.cwd }, result: it.aggregatedOutput ?? null, isError: it.status === 'failed' || (typeof it.exitCode === 'number' && it.exitCode !== 0) };
+      case 'fileChange': return { name: 'edit', args: { path: (it.changes ?? []).map((c) => c.path).join(', ') }, result: it.status ?? null, isError: it.status === 'failed' || it.status === 'declined' };
+      case 'mcpToolCall': return { name: `${it.server}/${it.tool}`, args: it.arguments ?? {}, result: it.result ?? it.error ?? null, isError: !!it.error };
+      case 'dynamicToolCall': return { name: it.tool, args: it.arguments ?? {}, result: null, isError: it.status === 'failed' };
+      case 'webSearch': return { name: 'web_search', args: { query: it.query ?? '' }, result: null, isError: false };
+      default: return null;
+    }
+  }
+
+  // ── the server asks the person: approvals and user input ──
+  function serverRequest(msg, run) {
+    const reply = (result) => write({ jsonrpc: '2.0', id: msg.id, result });
+    const params = msg.params ?? {};
+    if (!run) {
+      // nobody at the canvas for this thread: fail closed
+      if (msg.method === 'item/tool/requestUserInput') return reply({ answers: {} });
+      if (msg.method === 'item/permissions/requestApproval') return reply({ permissions: {}, scope: 'turn' });
+      return reply({ decision: 'decline' });
+    }
+    const ask = (question, respond) => {
+      const id = `q-${msg.id}`;
+      serverAsks.set(id, { rpcId: msg.id, respond });
+      run.waiting = true;
+      run.emit({ type: 'question', id, ...question });
+    };
+    const decided = (id, outcome, value, extra) => { run.waiting = false; run.emit({ type: 'question_answered', id, outcome, value: value ?? null, ...(extra ?? {}) }); };
+    // a yes/no the conversation may have settled already: `rule` names what a
+    // standing allowance covers; a match is accepted for the session without asking
+    const settle = (rule, title, message, respondYes) => {
+      if (rule && run.allowRules?.has(rule)) { respondYes(true); run.emit({ type: 'question_answered', id: `auto-${msg.id}`, outcome: 'allowed-session', value: null, auto: true, title, message, rule }); return true; }
+      return false;
+    };
+    const yesNo = (rule, respondYes, respondNo) => (a, id) => {
+      const yes = !!a?.confirmed; const forSession = yes && a?.scope === 'session' && !!rule;
+      if (forSession) run.allowRules?.add(rule);
+      if (yes) respondYes(forSession); else respondNo();
+      decided(id, yes ? (forSession ? 'allowed-session' : 'allowed-once') : 'rejected', null, forSession ? { rule } : undefined);
+    };
+    switch (msg.method) {
+      case 'item/commandExecution/requestApproval': {
+        const cmd = Array.isArray(params.command) ? params.command.join(' ') : String(params.command ?? '');
+        const rule = cmd ? 'codex:cmd:' + cmd : null;
+        const title = 'command needs approval'; const message = [params.command, params.reason].filter(Boolean).join('\n');
+        const respondYes = (forSession) => reply({ decision: forSession ? 'acceptForSession' : 'accept' });
+        if (settle(rule, title, message, respondYes)) return;
+        return ask({ kind: 'confirm', title, message, rule, options: [], placeholder: null, prefill: null, paths: [], suggest: null },
+          yesNo(rule, respondYes, () => reply({ decision: 'decline' })));
+      }
+      case 'item/fileChange/requestApproval': {
+        const rule = 'codex:fileChange';
+        const title = 'file change needs approval'; const message = [params.reason, params.grantRoot].filter(Boolean).join('\n') || 'apply the proposed file changes';
+        const respondYes = (forSession) => reply({ decision: forSession ? 'acceptForSession' : 'accept' });
+        if (settle(rule, title, message, respondYes)) return;
+        return ask({ kind: 'confirm', title, message, rule, options: [], placeholder: null, prefill: null, paths: [], suggest: null },
+          yesNo(rule, respondYes, () => reply({ decision: 'decline' })));
+      }
+      case 'item/permissions/requestApproval':
+        return ask({ kind: 'confirm', title: 'more permissions requested', message: [params.reason, JSON.stringify(params.permissions ?? {})].filter(Boolean).join('\n'), options: [], placeholder: null, prefill: null, paths: [], suggest: null },
+          (a, id) => { const yes = !!a?.confirmed; reply({ permissions: yes ? (params.permissions ?? {}) : {}, scope: 'turn' }); decided(id, yes ? 'allowed-once' : 'rejected'); });
+      case 'item/tool/requestUserInput': {
+        // one question at a time; the answers go back together
+        const qs = Array.isArray(params.questions) ? params.questions : [];
+        const answers = {};
+        const next = (i) => {
+          if (i >= qs.length) { reply({ answers }); return; }
+          const q = qs[i];
+          const opts = (q.options ?? []).map((o) => o.label);
+          ask({ kind: opts.length ? 'select' : 'input', title: q.header || 'question', message: q.question || '', options: opts, placeholder: q.isOther ? 'other…' : null, prefill: null, paths: [], suggest: null },
+            (a, id) => { const v = typeof a?.value === 'string' ? a.value : ''; answers[q.id] = { answers: v ? [v] : [] }; decided(id, v ? 'answered' : 'cancelled', v || null); next(i + 1); });
+        };
+        return next(0);
+      }
+      default:
+        return write({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `unsupported request ${msg.method}` } });
+    }
+  }
+
+  const effortsIn = (m) => (m.supportedReasoningEfforts ?? []).map((e) => (e && typeof e === 'object' ? e.reasoningEffort : e)).filter((e) => typeof e === 'string');
+  const modelEntry = (m) => ({ provider: 'codex', id: m.model ?? m.id, name: m.displayName ?? m.model ?? m.id, reasoning: true, vision: true, efforts: effortsIn(m), defaultEffort: typeof m.defaultReasoningEffort === 'string' ? m.defaultReasoningEffort : null });
+  // model id → the reasoning efforts it advertises, from model/list
+  const effortsByModel = new Map();
+  const noteEfforts = (r) => { for (const m of r?.data ?? []) effortsByModel.set(m.model ?? m.id, effortsIn(m)); };
+  // only a level the model itself advertises, in Codex's own words; anything
+  // else means the model's default
+  const effortFor = (model, word) => { const offered = effortsByModel.get(model); return word && offered && offered.includes(word) ? word : null; };
+  // the model a run uses when the canvas named none: the server's own
+  // default from model/list, not the config file's — a config can name a
+  // model this CLI version cannot run, and the list only carries runnable ones
+  let defaultModel = null;
+  async function defaultModelId() {
+    if (defaultModel) return defaultModel;
+    try { const r = await send('model/list', {}); noteEfforts(r); const d = (r?.data ?? []).find((m) => m.isDefault) ?? (r?.data ?? [])[0]; defaultModel = d ? (d.model ?? d.id) : null; } catch { /* leave it to the config */ }
+    return defaultModel;
+  }
+
+  return {
+    available: () => bin(),
+
+    async models() {
+      const b = await bin();
+      if (!b) return { installed: false, models: [], default: null };
+      await ensureServer();
+      const r = await send('model/list', {});
+      noteEfforts(r);
+      const configured = await configuredEffort();
+      const models = (r?.data ?? []).filter((m) => !m.hidden).map(modelEntry).map((m) => (configured && m.efforts.includes(configured) ? { ...m, defaultEffort: configured } : m));
+      const def = (r?.data ?? []).find((m) => m.isDefault);
+      defaultModel = def ? (def.model ?? def.id) : defaultModel;
+      return { installed: true, models, default: def ? `codex/${def.model ?? def.id}` : (models[0] ? `codex/${models[0].id}` : null) };
+    },
+
+    async run(req, onEvent) {
+      const cwd = String(req.cwd || '');
+      if (!cwd || !path.isAbsolute(cwd)) throw new Error('run needs an absolute cwd');
+      await fsp.mkdir(cwd, { recursive: true });
+      await ensureServer();
+      const runId = randomUUID();
+      const emit = (event) => { try { onEvent({ runId, event }); } catch { /* renderer gone */ } };
+      const state = { runId, threadId: null, turnId: null, text: '', final: null, waiting: false, emit, end: null, done: null,
+        // what this conversation already allowed for good (see README: `rule`)
+        allowRules: new Set(Array.isArray(req.allowRules) ? req.allowRules.filter((s) => typeof s === 'string' && s.startsWith('codex:')) : []) };
+      state.done = new Promise((resolve) => { state.end = (how) => { if (state.ended) return; state.ended = true; resolve(how); }; });
+      runs.set(runId, state);
+      void (async () => {
+        const IDLE = Number(process.env.TD_AGENT_IDLE_MS) || 10 * 60 * 1000;
+        let lastEvent = Date.now();
+        const origEmit = state.emit;
+        state.emit = (event) => { lastEvent = Date.now(); if (event.type === 'question') state.waiting = true; if (event.type === 'question_answered') state.waiting = false; origEmit(event); };
+        const watchdog = setInterval(() => {
+          if (state.waiting || Date.now() - lastEvent < IDLE) return;
+          state.emit({ type: 'run_error', message: `no activity for ${IDLE >= 60000 ? Math.round(IDLE / 60000) + ' min' : Math.round(IDLE / 1000) + ' s'}; the turn was stopped` });
+          if (state.threadId && state.turnId) send('turn/interrupt', { threadId: state.threadId, turnId: state.turnId }).catch(() => {});
+          setTimeout(() => state.end('idle'), 5000);
+        }, 15000);
+        try {
+          const policy = await policyFor(cwd);
+          const model = (req.model && typeof req.model === 'object' && req.model.id ? req.model.id : null) ?? await defaultModelId();
+          let thread;
+          const resumeId = req.sessionPath ? threadIdOf(req.sessionPath) : null;
+          if (req.forkEntryId && resumeId) thread = (await send('thread/fork', { threadId: resumeId, cwd, ...policy, ...(model ? { model } : {}) })).thread;
+          else if (resumeId) thread = (await send('thread/resume', { threadId: resumeId, cwd, ...policy, ...(model ? { model } : {}) })).thread;
+          else thread = (await send('thread/start', { cwd, ...policy, ...(model ? { model } : {}) })).thread;
+          state.threadId = thread.id;
+          byThread.set(thread.id, runId);
+          state.emit({ type: 'session', sessionId: thread.id, sessionFile: thread.path ?? null, model: model ? { provider: 'codex', id: model, name: model } : null, cwd });
+          const before = await snapshotDir(cwd).catch(() => null);
+          const input = [{ type: 'text', text: String(req.prompt ?? ''), text_elements: [] }];
+          for (const img of Array.isArray(req.images) ? req.images : []) if (img && typeof img.data === 'string') input.push({ type: 'image', url: `data:${img.mimeType};base64,${img.data}` });
+          const effort = req.effort && model ? effortFor(model, req.effort) : null;
+          const started = await send('turn/start', { threadId: thread.id, input, ...(model ? { model } : {}), ...(effort ? { effort } : {}) }, 60 * 1000);
+          state.turnId = started?.turn?.id ?? null;
+          const how = await state.done;
+          const ran = await turnEffortOf(thread.path);
+          if (ran) state.emit({ type: 'session', sessionId: thread.id, sessionFile: thread.path ?? null, model: model ? { provider: 'codex', id: model, name: model } : null, cwd, effort: ran });
+          if (before) {
+            const after = await snapshotDir(cwd).catch(() => null);
+            if (after) { const d = diffSnapshots(before, after); if (d.changed.length || d.added.length || d.removed.length || d.truncated) state.emit({ type: 'fs_changes', ...d }); }
+          }
+          state.emit({ type: 'run_end', text: state.final ?? state.text, how });
+        } catch (e) {
+          state.emit({ type: 'run_error', message: e instanceof Error ? e.message : String(e) });
+          state.emit({ type: 'run_end', text: state.final ?? state.text, how: 'error' });
+        } finally {
+          clearInterval(watchdog);
+          if (state.threadId) byThread.delete(state.threadId);
+          runs.delete(runId);
+        }
+      })();
+      return runId;
+    },
+
+    abort(runId) {
+      const r = runs.get(runId);
+      if (!r) return false;
+      // withdraw any question still open for this run, then interrupt
+      for (const [id, ask] of serverAsks) { if (id.startsWith('q-')) { /* the server's own timeout covers it */ } void ask; }
+      if (r.threadId && r.turnId) send('turn/interrupt', { threadId: r.threadId, turnId: r.turnId }).catch(() => {});
+      return true;
+    },
+
+    answer(runId, requestId, response) {
+      const ask = serverAsks.get(String(requestId));
+      if (!ask || !runs.has(runId)) return false;
+      serverAsks.delete(String(requestId));
+      const a = response && typeof response === 'object' ? response : { confirmed: !!response };
+      if (a.cancelled) { ask.respond({ confirmed: false, value: '' }, String(requestId)); return true; }
+      ask.respond(a, String(requestId));
+      return true;
+    },
+
+    shutdown() { clearInterval(retire); try { proc?.kill(); } catch { /* gone */ } proc = null; ready = null; },
+  };
+}
+
+module.exports = { createCodexRuntime, findCodex };

package/lib/runtime/agents/fs-diff.cjs

@@ -0,0 +1,44 @@
+// What changed on disk during a turn, for any runtime: a snapshot of the
+// working directory before the prompt and after the turn; the difference is
+// what the turn changed, whatever tool did it. Bounded; bulk directories
+// are skipped.
+'use strict';
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.thoughtdag', 'dist', 'build', 'target', '.venv', 'venv', '__pycache__', '.cache', '.next', '.turbo', 'out', 'coverage']);
+const SNAPSHOT_MAX_FILES = 20000;
+const SNAPSHOT_MAX_DEPTH = 12;
+
+async function snapshotDir(root) {
+  const files = new Map();
+  let truncated = false;
+  const walk = async (dir, depth) => {
+    if (truncated || depth > SNAPSHOT_MAX_DEPTH) return;
+    let entries;
+    try { entries = await fsp.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (truncated) return;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) await walk(p, depth + 1); continue; }
+      if (!e.isFile()) continue;
+      try { const st = await fsp.stat(p); files.set(p, `${st.mtimeMs}:${st.size}`); } catch { /* vanished */ }
+      if (files.size >= SNAPSHOT_MAX_FILES) truncated = true;
+    }
+  };
+  await walk(root, 0);
+  return { files, truncated };
+}
+
+function diffSnapshots(before, after) {
+  const changed = []; const added = []; const removed = [];
+  for (const [p, sig] of after.files) {
+    const prev = before.files.get(p);
+    if (prev === undefined) added.push(p); else if (prev !== sig) changed.push(p);
+  }
+  for (const p of before.files.keys()) if (!after.files.has(p)) removed.push(p);
+  return { changed, added, removed, truncated: before.truncated || after.truncated };
+}
+
+
+module.exports = { snapshotDir, diffSnapshots };

package/lib/runtime/agents/http.cjs

@@ -0,0 +1,95 @@
+// The agents surface over HTTP, for hosts that are not the desktop shell:
+// the harness plugin's host and the local server. Same calls as
+// window.desktopAgents, one endpoint each, and one server-sent-events feed
+// carrying every run's events (the renderer's shim turns it back into
+// onEvent). Runtimes are created on first use, as in the shell.
+'use strict';
+const path = require('node:path');
+const os = require('node:os');
+const ops = require('./ops.cjs');
+const terminal = require('../terminal.cjs');
+
+const RUNTIME_FACTORIES = {
+  pi: (log) => require('./pi.cjs').createPiRuntime({ log }),
+  codex: (log) => require('./codex.cjs').createCodexRuntime({ log }),
+  'claude-code': (log) => require('./claude.cjs').createClaudeRuntime({ log }),
+};
+
+function createAgentsHttp({ workspaceRoot = path.join(os.homedir(), '.thoughtdag', 'workspaces'), log = () => {} } = {}) {
+  const runtimes = new Map();
+  const owners = new Map();      // runId → runtime name
+  const clients = new Set();     // SSE responses
+  const runtime = (name = 'pi') => {
+    const key = RUNTIME_FACTORIES[name] ? name : 'pi';
+    if (!runtimes.has(key)) runtimes.set(key, RUNTIME_FACTORIES[key](log));
+    return runtimes.get(key);
+  };
+  const broadcast = (payload) => {
+    const line = `data: ${JSON.stringify(payload)}\n\n`;
+    for (const res of clients) { try { res.write(line); } catch { clients.delete(res); } }
+  };
+  const heartbeat = setInterval(() => { for (const res of clients) { try { res.write(': hb\n\n'); } catch { clients.delete(res); } } }, 20000);
+  heartbeat.unref?.();
+
+  const json = (res, status, body) => {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(JSON.stringify(body));
+  };
+
+  /**
+   * Handle one request. `sub` is the path after the mount point, starting
+   * with `/agents`; `body` is the parsed JSON body (or null). Returns false
+   * when the path is not ours.
+   */
+  async function handle(req, res, sub, body) {
+    const url = new URL(req.url ?? '/', 'http://local');
+    const p = sub.replace(/\/+$/, '');
+    const method = req.method ?? 'GET';
+    try {
+      if (p === '/agents/available' && method === 'GET') {
+        const out = {};
+        for (const name of Object.keys(RUNTIME_FACTORIES)) out[name] = await runtime(name).available().catch(() => null);
+        return json(res, 200, out), true;
+      }
+      if (p === '/agents/models' && method === 'GET') {
+        try { return json(res, 200, await runtime(url.searchParams.get('runtime') ?? 'pi').models()), true; }
+        catch (e) { return json(res, 200, { installed: false, models: [], default: null, error: e instanceof Error ? e.message : String(e) }), true; }
+      }
+      if (p === '/agents/events' && method === 'GET') {
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+        res.write(': connected\n\n');
+        clients.add(res);
+        req.on('close', () => clients.delete(res));
+        return true;
+      }
+      if (p === '/agents/run' && method === 'POST') {
+        const r = body && typeof body === 'object' ? body : {};
+        const name = RUNTIME_FACTORIES[r.runtime] ? r.runtime : 'pi';
+        const runId = await runtime(name).run(r, broadcast);
+        owners.set(runId, name);
+        return json(res, 200, { runId }), true;
+      }
+      if (p === '/agents/abort' && method === 'POST') {
+        const id = String(body?.runId ?? '');
+        return json(res, 200, { ok: runtime(owners.get(id)).abort(id) }), true;
+      }
+      if (p === '/agents/answer' && method === 'POST') {
+        const id = String(body?.runId ?? '');
+        return json(res, 200, { ok: runtime(owners.get(id)).answer(id, String(body?.requestId ?? ''), body?.response) }), true;
+      }
+      if (p === '/agents/workspace' && method === 'POST') return json(res, 200, { dir: await ops.workspaceFor(workspaceRoot, String(body?.canvasId ?? 'default')) }), true;
+      if (p === '/agents/guard' && method === 'POST') return json(res, 200, { ok: await ops.writeGuard(String(body?.cwd ?? ''), body?.config) }), true;
+      if (p === '/agents/materials' && method === 'POST') return json(res, 200, await ops.writeMaterials(String(body?.cwd ?? ''), body?.files)), true;
+      if (p === '/agents/open-in-cli' && method === 'POST') return json(res, 200, await terminal.openInTerminal(String(body?.runner ?? ''), body?.cwd ?? null, String(body?.sessionId ?? ''))), true;
+      return false;
+    } catch (e) {
+      json(res, 500, { error: e instanceof Error ? e.message : String(e) });
+      return true;
+    }
+  }
+
+  const shutdown = () => { clearInterval(heartbeat); for (const r of runtimes.values()) r.shutdown(); for (const res of clients) { try { res.end(); } catch { /* gone */ } } };
+  return { handle, shutdown };
+}
+
+module.exports = { createAgentsHttp };

package/lib/runtime/agents/ops.cjs

@@ -0,0 +1,54 @@
+// What every host does around a run, in plain Node: the per-canvas
+// workspace directory, the canvas's materials written where the agent can
+// read them, the boundary guard's tuning file. Used by the desktop shell,
+// the harness plugin host and the local server alike.
+'use strict';
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+
+const WORKSPACE_ID = /^[\w.-]{1,80}$/;
+const fileExists = (p) => fsp.access(p).then(() => true, () => false);
+
+/** The shell-managed working directory of a canvas, created on demand. */
+async function workspaceFor(root, canvasId) {
+  if (!WORKSPACE_ID.test(String(canvasId))) throw new Error('bad canvas id');
+  const dir = path.join(root, String(canvasId));
+  await fsp.mkdir(dir, { recursive: true });
+  const readme = path.join(dir, 'README.md');
+  if (!(await fileExists(readme))) {
+    await fsp.writeFile(readme, `# ThoughtDAG workspace\n\nThis folder is the working directory of one ThoughtDAG canvas (id ${canvasId}).\nAgents launched from that canvas read, write and run commands here unless the\ncanvas mirrors a session that already has a working directory of its own.\n`);
+  }
+  return dir;
+}
+
+/** The canvas's materials under <cwd>/.thoughtdag/materials/<name>:
+ *  text as-is, binaries from base64. */
+async function writeMaterials(cwd, files) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || !Array.isArray(files)) return { dir: null, written: [] };
+  const dir = path.join(cwd, '.thoughtdag', 'materials');
+  await fsp.mkdir(dir, { recursive: true });
+  const written = [];
+  for (const f of files.slice(0, 40)) {
+    const name = String(f?.name ?? '').replace(/[/\\:*?"<>|]/g, '_').slice(0, 120);
+    if (!name || typeof f.content !== 'string') continue;
+    const target = path.join(dir, name);
+    try {
+      await fsp.writeFile(target, f.encoding === 'base64' ? Buffer.from(f.content, 'base64') : f.content);
+      written.push(target);
+    } catch { /* one bad file does not stop the rest */ }
+  }
+  return { dir, written };
+}
+
+/** The guard's tuning for a working directory: <cwd>/.thoughtdag/guard.json */
+async function writeGuard(cwd, config) {
+  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return false;
+  const dir = path.join(cwd, '.thoughtdag');
+  await fsp.mkdir(dir, { recursive: true });
+  const mode = config?.mode === 'allow' ? 'allow' : 'ask';
+  const allow = Array.isArray(config?.allow) ? config.allow.filter((x) => typeof x === 'string' && path.isAbsolute(x)).slice(0, 100) : [];
+  await fsp.writeFile(path.join(dir, 'guard.json'), JSON.stringify({ mode, allow }, null, 2));
+  return true;
+}
+
+module.exports = { workspaceFor, writeMaterials, writeGuard };

package/lib/runtime/agents/pi-guard.mjs

@@ -0,0 +1,81 @@
+// A Pi extension the desktop shell loads into every run it starts
+// (`pi -e <this file>`). One rule: the working directory is the boundary.
+// A tool call that reaches outside it — a read, write or edit by path, a
+// bash command naming a path elsewhere — asks the person first; in rpc
+// mode that question travels to the canvas and comes back as an
+// approval. Denied means the call is blocked with a reason the model
+// sees. Paths the system owns (/usr, /bin, /dev, /tmp…) pass: a command
+// that runs /usr/bin/env is not an excursion.
+//
+// The canvas tunes the rule through <cwd>/.thoughtdag/guard.json, read on
+// every call so a change takes effect mid-run:
+//   { "mode": "ask" | "allow", "allow": ["/a/directory", …] }
+// `allow` mode asks nothing; a path under an allowed directory passes.
+import { resolve, sep, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { readFileSync, statSync } from 'node:fs';
+
+const SYSTEM_PREFIXES = ['/dev/', '/usr/', '/bin/', '/sbin/', '/opt/', '/etc/', '/tmp/', '/private/tmp/', '/private/var/', '/var/', '/System/', '/Library/', '/Applications/', '/proc/'];
+/** the separator between the human message and the structured tail of a confirm */
+const TAIL = '␟';
+
+function expand(p, cwd) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return resolve(homedir(), p.slice(2));
+  return resolve(cwd, p);
+}
+
+const inside = (abs, root) => abs === root || abs.startsWith(root + sep);
+const systemOwned = (abs) => SYSTEM_PREFIXES.some((pre) => abs.startsWith(pre));
+
+/** Paths a bash command names: absolute ones, ~ ones, and cd targets. */
+function pathsInCommand(command, cwd) {
+  const out = new Set();
+  const text = String(command ?? '');
+  for (const m of text.matchAll(/(?:^|[\s=:'"(])((?:~|\/)[^\s'"`;|&)<>]*)/g)) out.add(expand(m[1], cwd));
+  for (const m of text.matchAll(/(?:^|[;&|]\s*|\s)cd\s+([^\s;|&]+)/g)) out.add(expand(m[1].replace(/^['"]|['"]$/g, ''), cwd));
+  return [...out];
+}
+
+function pathsOf(event, cwd) {
+  const input = event.input ?? {};
+  switch (event.toolName) {
+    case 'bash': return pathsInCommand(input.command, cwd);
+    case 'read': case 'write': case 'edit': case 'ls': case 'grep': case 'find':
+      return typeof input.path === 'string' && input.path ? [expand(input.path, cwd)] : [];
+    default: return [];
+  }
+}
+
+function config(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(join(cwd, '.thoughtdag', 'guard.json'), 'utf8'));
+    return { mode: raw?.mode === 'allow' ? 'allow' : 'ask', allow: Array.isArray(raw?.allow) ? raw.allow.filter((x) => typeof x === 'string' && x.startsWith('/')).map((x) => resolve(x)) : [] };
+  } catch { return { mode: 'ask', allow: [] }; }
+}
+
+/** The directory to offer as "allow this location": the path itself when
+ *  it is a directory, else its parent; several paths → their common parent. */
+function suggestion(paths) {
+  const dirs = paths.map((p) => { try { return statSync(p).isDirectory() ? p : dirname(p); } catch { return dirname(p); } });
+  let common = dirs[0].split(sep);
+  for (const d of dirs.slice(1)) { const parts = d.split(sep); let i = 0; while (i < common.length && i < parts.length && common[i] === parts[i]) i++; common = common.slice(0, i); }
+  const dir = common.join(sep) || sep;
+  return dir === sep ? dirs[0] : dir;
+}
+
+export default function (pi) {
+  pi.on('tool_call', async (event, ctx) => {
+    const root = resolve(ctx.cwd);
+    const cfg = config(root);
+    if (cfg.mode === 'allow') return;
+    const outside = pathsOf(event, root).filter((p) => !inside(p, root) && !systemOwned(p) && !cfg.allow.some((a) => inside(p, a)));
+    if (outside.length === 0) return;
+    const where = outside.slice(0, 3).join(', ') + (outside.length > 3 ? ` (+${outside.length - 3})` : '');
+    if (!ctx.hasUI) return { block: true, reason: `outside the working directory (${where}); nobody to ask` };
+    const detail = event.toolName === 'bash' ? String(event.input?.command ?? '') : where;
+    const tail = TAIL + JSON.stringify({ paths: outside, suggest: suggestion(outside) });
+    const ok = await ctx.ui.confirm(`${event.toolName} outside the working directory`, detail + tail);
+    if (!ok) return { block: true, reason: `the person did not allow ${event.toolName} outside the working directory (${where})` };
+  });
+}