dsh-thoughtdag 0.4.8 → 0.4.10

package/lib/index.js

@@ -70,6 +70,7 @@
 import { randomUUID } from 'node:crypto'
 import { open, readFile, readdir, stat } from 'node:fs/promises'
 import { extname, join, normalize, resolve, sep } from 'node:path'
+import { createRequire } from 'node:module'
 import os from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { zstdDecompressSync } from 'node:zlib'
@@ -78,8 +79,34 @@ export const name = 'thoughtdag'
 export const inject = ['webServer', 'sessions', 'sessionController', 'agents', 'llm', 'attachments', 'web', 'tools', 'commands', 'systemPrompt', 'approval']
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const require = createRequire(import.meta.url)
 const APP_DIR = resolve(__dirname, '../dist-app')
 
+// The plugin's own version travels into the canvas's URL (?dv=), so the
+// update dialog and the release history know which release runs here, as
+// they do in the desktop shell. The registry is asked for the newest
+// version at most once a day; a failed lookup is silence, not an error.
+const PLUGIN_VERSION = (() => { try { return require(resolve(__dirname, '..', 'package.json')).version ?? null } catch { return null } })()
+let latestLookup = { value: null, at: 0 }
+async function latestPluginVersion() {
+  if (Date.now() - latestLookup.at < 24 * 60 * 60 * 1000) return latestLookup.value
+  latestLookup = { value: latestLookup.value, at: Date.now() }
+  try {
+    const r = await fetch('https://registry.npmjs.org/dsh-thoughtdag/latest', { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } })
+    if (r.ok) { const j = await r.json(); if (typeof j?.version === 'string') latestLookup.value = j.version }
+  } catch { /* offline, or the registry is slow: keep what we had */ }
+  return latestLookup.value
+}
+// the shared runtime, copied under lib/runtime by the build (Node code, no harness dependency)
+let agentsHttpInstance = null
+function agentsHttp() {
+  if (!agentsHttpInstance) {
+    const { createAgentsHttp } = require(resolve(__dirname, 'runtime', 'agents', 'http.cjs'))
+    agentsHttpInstance = createAgentsHttp({ log: (line) => console.error(line) })
+  }
+  return agentsHttpInstance
+}
+
 const MAX_BODY_BYTES = 32 * 1024
 // a compiled canvas context can be long; the write endpoints take up to this
 const MAX_WRITE_BODY_BYTES = 4 * 1024 * 1024
@@ -449,6 +476,18 @@ function splitModelId(id) {
  *  seeing images: a model is marked vision when its adapter declares image
  *  input; those images then enter the attachment store and ride the call. */
 const AGENT_MODEL = 'harness/agent'
+/** One agent entry per catalog model: 'harness/agent/<provider>/<model>'.
+ *  The bare 'harness/agent' stays accepted (older canvases) and means the
+ *  session's current model. */
+const isAgentModelId = (id) => typeof id === 'string' && (id === AGENT_MODEL || id.startsWith(AGENT_MODEL + '/'))
+function agentTargetOf(id) {
+  if (!isAgentModelId(id) || id === AGENT_MODEL) return null
+  const rest = id.slice(AGENT_MODEL.length + 1)
+  const i = rest.indexOf('/')
+  return i > 0 && i < rest.length - 1 ? { provider: rest.slice(0, i), model: rest.slice(i + 1) } : null
+}
+// the picker groups every agent-run entry under this key (the SPA's AGENT_PROVIDER)
+const AGENT_GROUP = '__agent__'
 
 /** Which of a provider's models take images: the adapter's declared input
  *  modalities; a name that says "vision" only when the adapter says nothing. */
@@ -465,11 +504,18 @@ async function visionIdsOf(ctx, providerId, catalogModels) {
 async function modelsPayload(ctx) {
   const cat = await ctx.sessionController.modelCatalog()
   // the harness itself, as an entry: the agent loop with tools, not a bare model
-  const models = [{ id: AGENT_MODEL, name: 'DeepSeek Harness · Agent (tools)', provider: 'DeepSeek Harness', vision: true }]
+  // the harness's agent loop with tools, once per model it can run on —
+  // grouped with the other agent runtimes; the bare models follow by provider
+  const models = []
+  const agents = []
   for (const g of cat.groups ?? []) {
     const vision = await visionIdsOf(ctx, g.id, g.models ?? [])
-    for (const m of g.models ?? []) models.push({ id: `${g.id}/${m.id}`, name: m.name ?? m.id, provider: g.name ?? g.id, vision: vision.has(m.id) })
+    for (const m of g.models ?? []) {
+      models.push({ id: `${g.id}/${m.id}`, name: m.name ?? m.id, provider: g.name ?? g.id, vision: vision.has(m.id) })
+      agents.push({ id: `${AGENT_MODEL}/${g.id}/${m.id}`, name: `Harness · ${m.name ?? m.id}`, provider: AGENT_GROUP, vision: vision.has(m.id) })
+    }
   }
+  models.push(...agents)
   const def = cat.default ? `${cat.default.provider}/${cat.default.model}` : null
   return {
     models,
@@ -617,6 +663,10 @@ async function runAgentTurn(ctx, body, emit, isClosed, { answerApprovals = true
     const vm = await visionModel(ctx).catch(() => null)
     if (vm) await ctx.sessionController.selectModel({ sessionId, provider: vm.provider, model: vm.model }).catch(() => {})
   }
+  // the model the canvas picked for this agent turn, unless images already
+  // moved the session to a vision model
+  const picked = agentTargetOf(body?.model)
+  if (picked && !hasImages) await ctx.sessionController.selectModel({ sessionId, provider: picked.provider, model: picked.model }).catch(() => {})
   const agent = await agentOf(ctx, sessionId)
   let sawChunk = false
   let fullText = ''
@@ -834,6 +884,7 @@ export async function apply(ctx, config) {
         return sendJson(res, 200, { session: sessionSummary(session) })
       }
       if (path === '/why/status' && req.method === 'GET') return sendJson(res, 200, whyStatus)
+      if (path === '/version' && req.method === 'GET') return sendJson(res, 200, { version: PLUGIN_VERSION, latest: await latestPluginVersion(), checkedAt: latestLookup.at || null })
       // ── the other agents' session files ──
       if (path === '/roots' && req.method === 'GET') {
         const roots = []
@@ -870,6 +921,11 @@ export async function apply(ctx, config) {
           : String(r.body?.content ?? '')
         return sendJson(res, 200, { title, text, fetchedAt: new Date().toISOString(), ...(html ? { html } : {}), url: r.url ?? target, truncated: !!r.truncated })
       }
+      // ── agent runtimes on this machine (Pi today), the same surface the desktop shell has ──
+      if (path.startsWith('/agents/')) {
+        const body = req.method === 'POST' ? await readJson(req, MAX_WRITE_BODY_BYTES).catch(() => null) : null
+        if (await agentsHttp().handle(req, res, path, body)) return
+      }
       // ── model connection (the SPA's proxy protocol, on the harness's providers) ──
       if (path === '/models' && req.method === 'GET') return sendJson(res, 200, await modelsPayload(ctx))
       const approvalRoute = /^\/approvals\/([^/]+)$/.exec(path)
@@ -884,10 +940,10 @@ export async function apply(ctx, config) {
       }
       if ((path === '/stream' || path === '/claude') && req.method === 'POST') {
         const body = await readJson(req, MAX_CALL_BODY_BYTES)
-        if (body?.model === AGENT_MODEL) {
+        if (isAgentModelId(body?.model)) {
           if (path === '/claude') {
             const r = await runAgentTurn(ctx, body, () => {}, () => false, { answerApprovals: false })
-            return sendJson(res, 200, { text: r.text, model: AGENT_MODEL, harnessSession: r.sessionId })
+            return sendJson(res, 200, { text: r.text, model: body.model, harnessSession: r.sessionId })
           }
           res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' })
           let closed = false

package/lib/runtime/agents/README.md

@@ -0,0 +1,24 @@
+# Agent runtimes
+
+One file per runtime (CommonJS, `.cjs`, so it loads the same under any package type): `pi.cjs` over `pi --mode rpc`, `codex.cjs` over `codex app-server`. Each exports a factory returning the same surface:
+
+- `available()` → where the binary is, or null
+- `models()` → `{ installed, models: [{ provider, id, name, reasoning, vision }], default }`
+- `run(request, onEvent)` → run id at once; events follow, tagged with it
+- `abort(runId)`, `answer(runId, requestId, { confirmed } | { value } | { cancelled: true })`, `shutdown()`
+
+A run emits exactly these event kinds (the renderer reads nothing else):
+
+| kind | meaning |
+|---|---|
+| `session` | which session file this run writes to, and where (cwd) |
+| `message_update` with a text or thinking delta | the answer or the reasoning growing |
+| `tool_execution_start` / `tool_execution_end` | a tool call, for the live trace |
+| `question` | the agent asks the person: confirm / select / input / editor |
+| `question_answered` | the person's answer went back (record) |
+| `fs_changes` | what the shell saw change on disk (produced here, not by the agent) |
+| `run_end` / `run_error` | the turn is over |
+
+The finished turn is adopted from the session file by the atlas's adapter for that
+runtime; the stream is for showing, the file is the truth. Anything a runtime does
+beyond these kinds stays inside its own file.

package/lib/runtime/agents/codex.cjs

@@ -0,0 +1,302 @@
+// 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' };
+}
+
+const threadIdOf = (sessionPath) => {
+  const m = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i.exec(String(sessionPath ?? ''));
+  return m ? m[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'));
+    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')); }
+  });
+
+  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;
+  }
+
+  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) {
+    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) => { run.waiting = false; run.emit({ type: 'question_answered', id, outcome, value: value ?? null }); };
+    switch (msg.method) {
+      case 'item/commandExecution/requestApproval':
+        return ask({ kind: 'confirm', title: 'command needs approval', message: [params.command, params.reason].filter(Boolean).join('\n'), options: [], placeholder: null, prefill: null, paths: [], suggest: null },
+          (a, id) => { const yes = !!a?.confirmed; reply({ decision: yes ? 'accept' : 'decline' }); decided(id, yes ? 'allowed-once' : 'rejected'); });
+      case 'item/fileChange/requestApproval':
+        return ask({ kind: 'confirm', title: 'file change needs approval', message: [params.reason, params.grantRoot].filter(Boolean).join('\n') || 'apply the proposed file changes', options: [], placeholder: null, prefill: null, paths: [], suggest: null },
+          (a, id) => { const yes = !!a?.confirmed; reply({ decision: yes ? 'accept' : 'decline' }); decided(id, yes ? 'allowed-once' : 'rejected'); });
+      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 modelEntry = (m) => ({ provider: 'codex', id: m.model ?? m.id, name: m.displayName ?? m.model ?? m.id, reasoning: true, vision: true });
+  // 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', {}); 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', {});
+      const models = (r?.data ?? []).filter((m) => !m.hidden).map(modelEntry);
+      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 };
+      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 started = await send('turn/start', { threadId: thread.id, input, ...(model ? { model } : {}) }, 60 * 1000);
+          state.turnId = started?.turn?.id ?? null;
+          const how = await state.done;
+          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() { 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,94 @@
+// 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 }),
+};
+
+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 };