@tensor.chat/companion 0.4.6 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensor.chat/companion",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Lets your tensor.chat AI use this machine: files, shell and internet through your own connection.",
   "license": "MIT",
   "homepage": "https://tensor.chat",

package/src/daemon.js

@@ -17,6 +17,9 @@ const VERSION = require('../package.json').version;
 const RECONNECT_MIN_MS = 1000;
 const RECONNECT_MAX_MS = 60000;
 const MAX_CONCURRENT_CALLS = 4;
+// A Codex turn holds no call slot: it waits on the server most of the time, and the
+// tools its model calls may need the slots on this very computer.
+const MAX_CODEX_TURNS = 2;
 const SLOW_SPAWN_MS = 2000;
 
 // What a call works on, for the log: the command, the path or the address
@@ -62,6 +65,9 @@ function systemInfo(shell, localAuthority = false, approver = null) {
     cwd: process.cwd(),
     localAuthority: localAuthority ? 1 : null,
     approver: approver === 'app' || approver === 'terminal' ? approver : null,
+    // which version of the codex tool (tools/codex.js) this app answers; absent = none
+    // 2: also runs chat turns (action "turn")
+    codex: 2,
   };
 }
 
@@ -110,6 +116,7 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
   const localApprovals = typeof approvedRoots === 'function' ? approvedRoots : null;
   const localShellApproval = typeof approvedShell === 'function' ? approvedShell : null;
   const running = new Map(); // call id → AbortController
+  const turns = new Map(); // call id of a Codex turn → answer(key, value)
   const tools = new ToolRunner({ shell, slowSpawnMs, workerPath: toolWorkerPath });
   tools.on('log', say);
   const unsentExits = []; // job endings the server has not heard yet (offline at the time)
@@ -164,12 +171,14 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
       emitter.emit('result', { id, tool, ok: false });
       return;
     }
-    if (running.size >= MAX_CONCURRENT_CALLS) {
+    const turn = tool === 'codex' && msg.args && msg.args.action === 'turn';
+    if (turn ? turns.size >= MAX_CODEX_TURNS : running.size - turns.size >= MAX_CONCURRENT_CALLS) {
       send({ t: 'result', id, ok: false, text: '(the companion device is busy with other calls — try again in a moment)' });
       return;
     }
     const ctrl = new AbortController();
     running.set(id, ctrl);
+    if (turn) turns.set(id, null);
     const finished = stalls.started(tool, callSubject(tool, msg.args));
     emitter.emit('call', { id, tool: msg.tool, args: msg.args });
     let r;
@@ -180,12 +189,17 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
         const scoped = authorizeRequestedRoots(msg.roots, msg.labels, approved);
         callRoots = new Roots(scoped.roots, scoped.labels);
       }
-      r = await tools.run(tool, msg.args, ctrl.signal, Number(msg.timeoutMs) || undefined, callRoots);
+      const talk = turn ? {
+        onEvent: (ev) => send({ t: 'call_event', id, ev }),
+        ready: (answer) => turns.set(id, answer),
+      } : null;
+      r = await tools.run(tool, msg.args, ctrl.signal, Number(msg.timeoutMs) || undefined, callRoots, talk);
     } catch (e) {
       r = { ok: false, text: `(tool error on the companion device: ${e && e.message ? e.message : e})` };
     }
     finished();
     running.delete(id);
+    turns.delete(id);
     send({ t: 'result', id, ...r });
     emitter.emit('result', { id, tool: msg.tool, ok: r.ok });
   }
@@ -217,6 +231,7 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
       case 'config': applyConfig(msg); break;
       case 'call': onCall(msg); break;
       case 'cancel': { const c = running.get(String(msg.id)); if (c) c.abort(); break; }
+      case 'call_input': { const answer = turns.get(String(msg.id)); if (answer) answer(String(msg.key), msg.value); break; }
       case 'approval': emitter.emit('approval', msg); break;
       case 'approval_resolved': emitter.emit('approval_resolved', msg); break;
       case 'local_approval_request': confirmIfCovered(msg); break;

package/src/toolExecutor.js

@@ -6,6 +6,8 @@ const { fetchUrl } = require('./tools/fetch');
 const { extractTouched } = require('./tools/touched');
 const { outsideFolders } = require('./tools/outside');
 const { Jobs } = require('./tools/jobs');
+const codex = require('./tools/codex');
+const codexTurn = require('./tools/codexTurn');
 
 const BACKGROUND_FIRST_LOOK_MS = 1500;
 const FOREGROUND_DEFAULT_MS = 600000;
@@ -13,7 +15,9 @@ const FOREGROUND_DEFAULT_MS = 600000;
 function createToolExecutor({ shell, say = () => {}, slowSpawnMs = 2000 } = {}) {
   const jobs = new Jobs();
 
-  async function runTool(tool, args, signal, timeoutMs, callRoots, requestedAt = Date.now(), cancelled = () => false) {
+  // io: what a call that talks with the server while it runs (a Codex turn) needs -
+  // emit(ev) sends an event, input(key) waits for the server's answer to one.
+  async function runTool(tool, args, signal, timeoutMs, callRoots, requestedAt = Date.now(), cancelled = () => false, io = null) {
     const a = args && typeof args === 'object' ? args : {};
     if (signal.aborted || cancelled()) throw new Error('call cancelled before execution');
     switch (tool) {
@@ -75,6 +79,12 @@ function createToolExecutor({ shell, say = () => {}, slowSpawnMs = 2000 } = {})
       case 'renamepath': return files.renamepath(callRoots, a.from, a.to);
       case 'statpath': return files.statpath(callRoots, a.path);
       case 'fetch': return fetchUrl(a.url, { signal, raw: a.raw === true });
+      case 'codex':
+        if (a.action === 'turn') {
+          if (!io) return { ok: false, text: '(a Codex turn needs a connection to the server)' };
+          return codexTurn.runTurn(a, { emit: io.emit, toolResult: io.input, signal });
+        }
+        return codex.run(a, { signal, timeoutMs });
       default: return { ok: false, text: `(unknown tool "${tool}" on the companion device)` };
     }
   }

package/src/toolRunner.js

@@ -23,7 +23,9 @@ class ToolRunner extends EventEmitter {
     if (this.failure) throw this.failure;
     if (Atomics.load(this.stopping, 0)) throw new Error('tool worker is stopped');
     if (this.worker) return;
-    const worker = new Worker(this.workerPath, { workerData: { ...this.options, stopping: this.stopping.buffer } });
+    // The worker's env is named for the same reason as in tools/codex.js: by default it
+    // copies the env of the Node process, which under jest is not this module's.
+    const worker = new Worker(this.workerPath, { env: process.env, workerData: { ...this.options, stopping: this.stopping.buffer } });
     this.worker = worker;
     this.closed = new Promise((resolve) => worker.once('exit', resolve));
     const fail = (error) => {
@@ -34,6 +36,10 @@ class ToolRunner extends EventEmitter {
     worker.on('message', (msg) => {
       if (msg.t === 'log') this.emit('log', msg.line);
       else if (msg.t === 'job_exit') this.emit('exit', msg.report);
+      else if (msg.t === 'event') {
+        const p = this.pending.get(msg.id);
+        if (p && p.onEvent) p.onEvent(msg.ev);
+      }
       else if (msg.t === 'result') {
         const p = this.pending.get(msg.id);
         if (!p) return;
@@ -48,7 +54,10 @@ class ToolRunner extends EventEmitter {
     });
   }
 
-  async run(tool, args, signal, timeoutMs, roots) {
+  // talk: for a call that talks with the server while it runs. onEvent(ev) gets what
+  // the call sends out; answer(key, value) - handed over through talk.ready - sends it
+  // what the server answered.
+  async run(tool, args, signal, timeoutMs, roots, talk = null) {
     this.start();
     const id = this.nextId++;
     const cancelled = new Int32Array(new SharedArrayBuffer(4));
@@ -63,9 +72,10 @@ class ToolRunner extends EventEmitter {
         throw new Error('call cancelled before execution');
       }
       return await new Promise((resolve, reject) => {
-        this.pending.set(id, { resolve, reject });
+        this.pending.set(id, { resolve, reject, onEvent: talk && talk.onEvent });
+        if (talk && talk.ready) talk.ready((key, value) => this.worker.postMessage({ t: 'input', id, key, value }));
         try {
-          this.worker.postMessage({ t: 'call', id, tool, args, timeoutMs, entries: roots.entries, requestedAt: Date.now(), cancelled: cancelled.buffer });
+          this.worker.postMessage({ t: 'call', id, tool, args, timeoutMs, entries: roots.entries, requestedAt: Date.now(), cancelled: cancelled.buffer, talks: !!talk });
         } catch (e) {
           this.pending.delete(id);
           reject(e);

package/src/toolWorker.js

@@ -11,6 +11,28 @@ const executor = createToolExecutor({
   say: (line) => parentPort.postMessage({ t: 'log', line }),
 });
 const running = new Map();
+// coverage:host-only this file runs only as the tool worker thread, which coverage does not see; _codexLocalTurn.js drives every Codex turn through this worker for real (daemon -> worker -> codexTurn) and runs the same executor call in its own process
+// A call that talks with the server while it runs (a Codex turn): the answers it
+// waits for, by key, and those that came before it asked.
+const inputs = new Map();
+
+function ioFor(id, signal) {
+  const box = { waiting: new Map(), early: new Map() };
+  inputs.set(id, box);
+  signal.addEventListener('abort', () => {
+    for (const done of box.waiting.values()) done({ ok: false, text: '(cancelled)' });
+    box.waiting.clear();
+  }, { once: true });
+  return {
+    emit: (ev) => parentPort.postMessage({ t: 'event', id, ev }),
+    input: (key) => new Promise((resolve) => {
+      if (box.early.has(key)) { resolve(box.early.get(key)); box.early.delete(key); return; }
+      if (signal.aborted) { resolve({ ok: false, text: '(cancelled)' }); return; }
+      box.waiting.set(key, resolve);
+    }),
+  };
+}
+// coverage:host-only-end
 executor.jobs.on('exit', (report) => parentPort.postMessage({ t: 'job_exit', report }));
 
 parentPort.on('message', async (msg) => {
@@ -19,6 +41,15 @@ parentPort.on('message', async (msg) => {
     if (ctrl) ctrl.abort();
     return;
   }
+  // coverage:host-only the tool worker thread (see above): the server's answers to a running Codex turn
+  if (msg.t === 'input') {
+    const box = inputs.get(msg.id);
+    if (!box) return;
+    const done = box.waiting.get(msg.key);
+    if (done) { box.waiting.delete(msg.key); done(msg.value); } else box.early.set(msg.key, msg.value);
+    return;
+  }
+  // coverage:host-only-end
   if (msg.t === 'stop') {
     for (const ctrl of running.values()) ctrl.abort();
     executor.jobs.killAll();
@@ -37,11 +68,16 @@ parentPort.on('message', async (msg) => {
     const roots = new Roots([]);
     // This is the authorized per-call snapshot, never the worker's previous roots.
     roots.entries = msg.entries;
-    result = await executor.runTool(msg.tool, msg.args, ctrl.signal, msg.timeoutMs, roots, msg.requestedAt, isCancelled);
+    // coverage:host-only the tool worker thread (see above): a Codex turn gets its line to the server
+    result = await executor.runTool(msg.tool, msg.args, ctrl.signal, msg.timeoutMs, roots, msg.requestedAt, isCancelled, msg.talks ? ioFor(msg.id, ctrl.signal) : null);
+    // coverage:host-only-end
   } catch (e) {
     result = { ok: false, text: `(tool error on the companion device: ${e.message})` };
   } finally {
     running.delete(msg.id);
+    // coverage:host-only the tool worker thread (see above)
+    inputs.delete(msg.id);
+    // coverage:host-only-end
   }
   parentPort.postMessage({ t: 'result', id: msg.id, result });
 });

package/src/tools/codex.js

@@ -0,0 +1,218 @@
+'use strict';
+// Codex on this computer: is it installed, is it signed in, and how much of the
+// ChatGPT plan's Codex usage is used. The answer comes from the Codex app-server, the
+// interface Codex offers its own clients (https://learn.chatgpt.com/docs/app-server).
+// This only reads: no thread, no turn, no login, no change to Codex's own settings.
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { killTree } = require('./bash');
+
+const VERSION = require('../../package.json').version;
+const WIN = process.platform === 'win32';
+const STATUS_TIMEOUT_MS = 20000;
+// How this client names itself to Codex and, through Codex, to OpenAI.
+const CLIENT_NAME = 'tensor.chat';
+
+// The codex command on PATH: the npm shim (codex.cmd) or a native codex.exe on
+// Windows, an executable `codex` elsewhere. TENSOR_CODEX_BIN names another one
+// (a .js file runs with this Node).
+function findCodex(env = process.env) {
+  if (env.TENSOR_CODEX_BIN) return fs.existsSync(env.TENSOR_CODEX_BIN) ? env.TENSOR_CODEX_BIN : null;
+  const names = WIN ? ['codex.exe', 'codex.cmd'] : ['codex'];
+  for (const dir of String(env.PATH || env.Path || '').split(path.delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const file = path.join(dir, name);
+      try {
+        fs.accessSync(file, WIN ? fs.constants.F_OK : fs.constants.X_OK);
+        if (fs.statSync(file).isFile()) return file;
+      } catch (_) {}
+    }
+  }
+  return null;
+}
+
+// How to start `<bin> app-server`. A .cmd shim needs cmd.exe; the arguments are fixed,
+// so nothing from the server reaches that command line.
+function commandFor(bin) {
+  if (/\.js$/i.test(bin)) return { cmd: process.execPath, args: [bin, 'app-server'] };
+  if (WIN && /\.cmd$/i.test(bin)) return { cmd: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${bin}" app-server`], verbatim: true };
+  return { cmd: bin, args: ['app-server'] };
+}
+
+const NOT_SUPPORTED = { code: -32601, message: 'not supported by this client' };
+
+/**
+ * One app-server process and its line protocol (JSON-RPC, one message per line).
+ * Throws when the process cannot be started.
+ * @param {string} bin
+ * @param {object} [o]
+ * @param {boolean} [o.experimental]  ask for Codex's experimental methods and fields;
+ *   a chat turn needs them for dynamicTools, the status does not
+ * @param {(m: object) => (object|undefined|Promise<object|undefined>)} [o.onRequest]
+ *   answers a request from Codex with a result; undefined answers "not supported"
+ * @param {(m: object) => void} [o.onNotification]
+ * @returns {{request: Function, ready: Promise<object>, ended: Promise<Error>, kill: Function}}
+ *   ready: the initialize result, once Codex took the client; ended: why the process stopped
+ */
+function openSession(bin, { experimental = false, onRequest, onNotification } = {}) {
+  const { cmd, args, verbatim } = commandFor(bin);
+  // env named, not inherited: a spawn without it takes the env of the Node process,
+  // and under jest that is not the one this module sees. The originator is set at
+  // start too: Codex fetches its model list before initialize, and that request
+  // would otherwise go out under the plain CLI's name.
+  const env = { CODEX_INTERNAL_ORIGINATOR_OVERRIDE: CLIENT_NAME, ...process.env };
+  const child = spawn(cmd, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, windowsVerbatimArguments: !!verbatim, detached: !WIN });
+  const waiting = new Map();
+  let nextId = 1;
+  let buf = '';
+  let stderr = '';
+  let endedWith = null;
+  let onEnd;
+  const ended = new Promise((resolve) => { onEnd = resolve; });
+  const end = (err) => {
+    if (endedWith) return;
+    endedWith = err;
+    for (const done of waiting.values()) done({ error: { code: -32000, message: err.message } });
+    waiting.clear();
+    onEnd(err);
+  };
+  const send = (m) => { try { child.stdin.write(JSON.stringify(m) + '\n'); } catch (_) {} };
+  const request = (method, params) => new Promise((done) => {
+    if (endedWith) { done({ error: { code: -32000, message: endedWith.message } }); return; }
+    const id = nextId++;
+    waiting.set(id, done);
+    send({ id, method, params });
+  });
+  const answer = async (m) => {
+    let result;
+    try { result = onRequest ? await onRequest(m) : undefined; } catch (e) {
+      send({ id: m.id, error: { code: -32000, message: String(e && e.message ? e.message : e) } });
+      return;
+    }
+    send(result === undefined ? { id: m.id, error: NOT_SUPPORTED } : { id: m.id, result });
+  };
+  // A write after Codex stopped reading fails on the stream (EPIPE), not in send():
+  // without a listener that error would take the whole worker down. 'close' says why.
+  child.stdin.on('error', () => {});
+  child.on('error', (e) => end(e));
+  child.on('close', (code) => end(new Error(`Codex app-server ended (exit ${code})${stderr.trim() ? `: ${stderr.trim().slice(-300)}` : ''}`)));
+  child.stderr.on('data', (d) => { stderr = (stderr + d).slice(-4000); });
+  child.stdout.on('data', (d) => {
+    buf += d;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!line) continue;
+      let m;
+      try { m = JSON.parse(line); } catch (_) { continue; }
+      if (m.id != null && m.method) { answer(m); continue; }
+      if (m.id != null) {
+        const done = waiting.get(m.id);
+        if (done) { waiting.delete(m.id); done(m); }
+        continue;
+      }
+      if (m.method && onNotification) onNotification(m);
+    }
+  });
+  const ready = (async () => {
+    const init = await request('initialize', {
+      clientInfo: { name: CLIENT_NAME, title: CLIENT_NAME, version: VERSION },
+      capabilities: { experimentalApi: !!experimental, requestAttestation: false },
+    });
+    if (init.error) throw new Error(`Codex refused the connection: ${init.error.message || 'unknown error'}`);
+    send({ method: 'initialized' });
+    return init.result || {};
+  })();
+  ready.catch(() => {});
+  return { request, ready, ended, kill: () => killTree(child) };
+}
+
+// One short conversation with the app-server: initialize, then the questions, then
+// the process ends. Resolves with the answers by method; rejects on a broken start.
+function ask(bin, questions, { signal, timeoutMs = STATUS_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    let session;
+    try { session = openSession(bin); } catch (e) { reject(e); return; }
+    let settled = false;
+    const finish = (err, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      session.kill();
+      if (err) reject(err); else resolve(value);
+    };
+    const timer = setTimeout(() => finish(new Error(`Codex did not answer within ${Math.round(timeoutMs / 1000)} s`)), timeoutMs);
+    const onAbort = () => finish(new Error('cancelled'));
+    if (signal) {
+      if (signal.aborted) { finish(new Error('cancelled')); return; }
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+    session.ended.then((e) => finish(e));
+    (async () => {
+      const answers = { initialize: await session.ready };
+      for (const [method, params] of questions) {
+        const r = await session.request(method, params);
+        answers[method] = r.error ? { error: r.error } : (r.result || {});
+      }
+      finish(null, answers);
+    })().catch((e) => finish(e));
+  });
+}
+
+const toWindow = (w) => (w && typeof w.usedPercent === 'number'
+  ? { usedPercent: w.usedPercent, windowMins: Number.isFinite(w.windowDurationMins) ? w.windowDurationMins : null, resetsAt: Number.isFinite(w.resetsAt) ? w.resetsAt : null }
+  : null);
+
+// The models this Codex offers its user, with the reasoning levels each takes: the
+// server sends a GPT turn here only for a model on this list.
+function modelsOf(list) {
+  const data = list && !list.error && Array.isArray(list.data) ? list.data : [];
+  return data.filter((m) => m && typeof m.id === 'string' && m.id).slice(0, 50).map((m) => ({
+    id: m.id,
+    efforts: (Array.isArray(m.supportedReasoningEfforts) ? m.supportedReasoningEfforts : [])
+      .map((e) => (e && typeof e === 'object' ? e.reasoningEffort : e)).filter((e) => typeof e === 'string'),
+    images: Array.isArray(m.inputModalities) ? m.inputModalities.includes('image') : true,
+  }));
+}
+
+// What the server is told. The account's e-mail stays on this computer.
+async function status({ signal, timeoutMs, env } = {}) {
+  const bin = findCodex(env);
+  if (!bin) return { ok: true, text: 'Codex is not installed on this computer', codex: { installed: false } };
+  let a;
+  try {
+    a = await ask(bin, [['account/read', {}], ['account/rateLimits/read', {}], ['model/list', { includeHidden: false }]], { signal, timeoutMs });
+  } catch (e) {
+    return { ok: false, text: `(Codex did not answer: ${e.message})`, codex: { installed: true, error: e.message } };
+  }
+  const ua = String(a.initialize.userAgent || '');
+  const version = (/\/(\d+\.\d+\.\d+[\w.-]*)/.exec(ua) || [])[1] || null;
+  const account = a['account/read'] && a['account/read'].account;
+  const signedIn = !!(account && account.type);
+  const rl = a['account/rateLimits/read'];
+  const snap = rl && !rl.error ? rl.rateLimits : null;
+  const codex = {
+    installed: true,
+    version,
+    signedIn,
+    authMode: signedIn ? String(account.type) : null,
+    planType: signedIn && account.planType ? String(account.planType) : null,
+    usageAllowed: rl && !rl.error && typeof rl.ordinaryUsageAllowed === 'boolean' ? rl.ordinaryUsageAllowed : null,
+    limits: snap ? { primary: toWindow(snap.primary), secondary: toWindow(snap.secondary) } : null,
+    models: modelsOf(a['model/list']),
+  };
+  return { ok: true, text: signedIn ? `Codex ${version || ''} is signed in (${codex.planType || codex.authMode})`.replace('  ', ' ') : 'Codex is installed but not signed in', codex };
+}
+
+async function run(args, opts = {}) {
+  const action = String((args && args.action) || 'status');
+  if (action === 'status') return status(opts);
+  return { ok: false, text: `(unknown codex action "${action}")` };
+}
+
+module.exports = { run, status, findCodex, commandFor, openSession };

package/src/tools/codexTurn.js

@@ -0,0 +1,171 @@
+'use strict';
+// One chat turn of tensor.chat through Codex on this computer, signed in with the
+// user's own ChatGPT account. tensor.chat sends the conversation and its tools; Codex
+// runs the model; every tool the model calls goes back to tensor.chat and runs there,
+// with the same executor as on every other route. Codex itself gets no tool of its
+// own: no shell, no file access, no web search, no sub-agents, nothing about this
+// computer. The settings for that are fixed here - the server cannot change them.
+//
+// Measured 02.11.2026 with Codex 0.164 against a local stand-in for the model API:
+// with LOCKED below the request carries our base instructions, the history we
+// inject and our tools, and nothing else. dynamicTools need experimentalApi
+// ("thread/start.dynamicTools requires experimentalApi capability").
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { findCodex, openSession } = require('./codex');
+
+// A folder with nothing in it, as Codex's working folder: it is never shown to the
+// model (include_environment_context is off), and nothing can be read in it anyway.
+function emptyDir() {
+  const dir = path.join(os.tmpdir(), 'tensor-codex-turn');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+const OFF = {
+  shell_tool: false, unified_exec: false, view_image: false, multi_agent: false, goals: false,
+  apps: false, plugins: false, image_generation: false, sleep_tool: false, skill_search: false,
+  tool_suggest: false, memories: false, hooks: false, computer_use: false, browser_use: false,
+  in_app_browser: false,
+};
+const LOCKED = {
+  ephemeral: true,
+  approvalPolicy: 'never',
+  sandbox: 'read-only',
+  config: {
+    features: OFF,
+    web_search: 'disabled',
+    include_environment_context: false,
+    include_permissions_instructions: false,
+    include_apps_instructions: false,
+    include_skills_usage_instructions: false,
+    include_plugin_usage_instructions: false,
+    skills: { include_instructions: false },
+    tools: { experimental_request_user_input: { enabled: false } },
+  },
+};
+
+const EFFORTS = new Set(['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra']);
+const ITEM_TYPES = new Set(['message', 'function_call', 'function_call_output']);
+const MAX_TOOLS = 200;
+const MAX_ITEMS = 5000;
+
+const str = (v, max) => (typeof v === 'string' ? v.slice(0, max) : '');
+
+// What the server sent, in the shapes Codex takes - anything else is dropped.
+function checkTurn(a) {
+  const model = str(a && a.model, 100);
+  if (!/^[\w.:-]+$/.test(model)) throw new Error('no valid model');
+  const tools = (Array.isArray(a.tools) ? a.tools : []).slice(0, MAX_TOOLS)
+    .filter((t) => t && /^[\w.-]{1,128}$/.test(String(t.name || '')))
+    .map((t) => ({ name: String(t.name), description: str(t.description, 20000), inputSchema: t.inputSchema && typeof t.inputSchema === 'object' ? t.inputSchema : { type: 'object', properties: {} } }));
+  const items = (Array.isArray(a.items) ? a.items : []).slice(-MAX_ITEMS)
+    .filter((i) => i && typeof i === 'object' && ITEM_TYPES.has(i.type));
+  if (!items.length) throw new Error('nothing to answer');
+  return {
+    model,
+    effort: EFFORTS.has(a.effort) ? a.effort : null,
+    instructions: str(a.instructions, 4 * 1024 * 1024),
+    tools,
+    items,
+  };
+}
+
+// A tool result from the server, as Codex wants it back.
+function contentItems(r) {
+  const out = [{ type: 'inputText', text: str(r && r.text, 4 * 1024 * 1024) || '(no output)' }];
+  for (const url of (r && Array.isArray(r.images) ? r.images : []).slice(0, 20)) {
+    if (typeof url === 'string' && /^data:image\//.test(url)) out.push({ type: 'inputImage', imageUrl: url });
+  }
+  return out;
+}
+
+/**
+ * Run the turn.
+ * @param {object} args            from the server: model, effort, instructions, tools, items
+ * @param {object} io
+ * @param {(ev: object) => void} io.emit  an event for the server: {k:'text'|'reasoning', d},
+ *   {k:'tool', callId, tool, args}, {k:'usage', usage}, {k:'error', message, willRetry}
+ * @param {(callId: string) => Promise<object>} io.toolResult  waits for the server's
+ *   answer to a tool call: {ok, text, images?}
+ * @param {AbortSignal} [io.signal]
+ * @param {object} [io.env]
+ * @returns {Promise<{ok: boolean, text: string, turn?: {status: string, usage: object}}>}
+ */
+async function runTurn(args, { emit, toolResult, signal, env } = {}) {
+  let turn;
+  try { turn = checkTurn(args || {}); } catch (e) { return { ok: false, text: `(${e.message})` }; }
+  const bin = findCodex(env);
+  if (!bin) return { ok: false, text: '(Codex is not installed on this computer)', codex: { installed: false } };
+  let threadId = null;
+  let turnId = null;
+  let usage = null;
+  let finished;
+  const done = new Promise((resolve) => { finished = resolve; });
+  const onNotification = (m) => {
+    const p = m.params || {};
+    if (threadId && p.threadId && p.threadId !== threadId) return;
+    switch (m.method) {
+      case 'turn/started': turnId = (p.turn && p.turn.id) || turnId; break;
+      case 'item/agentMessage/delta': if (p.delta) emit({ k: 'text', d: String(p.delta) }); break;
+      case 'item/reasoning/summaryTextDelta':
+      case 'item/reasoning/textDelta': if (p.delta) emit({ k: 'reasoning', d: String(p.delta) }); break;
+      case 'item/reasoning/summaryPartAdded': emit({ k: 'reasoning', d: '\n\n' }); break;
+      case 'thread/tokenUsage/updated': usage = p.tokenUsage || usage; if (usage) emit({ k: 'usage', usage }); break;
+      case 'error': emit({ k: 'error', message: str(p.error && p.error.message, 2000), willRetry: !!p.willRetry }); break;
+      case 'turn/completed': finished({ status: String((p.turn && p.turn.status) || 'completed'), error: p.turn && p.turn.error ? str(p.turn.error.message, 2000) : null }); break;
+      default: break;
+    }
+  };
+  // Codex asks the client only for what the model wants: our tools. Everything else
+  // - approvals, questions to the user, logins - this client never takes.
+  const onRequest = async (m) => {
+    if (m.method !== 'item/tool/call') return undefined;
+    const p = m.params || {};
+    const callId = String(p.callId || '');
+    emit({ k: 'tool', callId, tool: String(p.tool || ''), args: p.arguments == null ? {} : p.arguments });
+    const r = await toolResult(callId);
+    return { success: !!(r && r.ok), contentItems: contentItems(r) };
+  };
+  const session = openSession(bin, { experimental: true, onRequest, onNotification });
+  const onAbort = () => {
+    if (threadId && turnId) session.request('turn/interrupt', { threadId, turnId });
+    // Codex answers an interrupt with turn/completed; one that does not is not waited for.
+    setTimeout(() => finished({ status: 'interrupted' }), 3000).unref();
+  };
+  if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  try {
+    const stopped = session.ended.then((e) => ({ status: 'failed', error: e.message }));
+    const step = async (method, params) => {
+      const r = await Promise.race([session.request(method, params), stopped.then((s) => ({ error: { message: s.error } }))]);
+      if (r.error) throw new Error(`${method}: ${r.error.message || 'failed'}`);
+      return r.result || {};
+    };
+    await Promise.race([session.ready, stopped.then((s) => { throw new Error(s.error); })]);
+    if (signal && signal.aborted) return { ok: false, text: '(cancelled)', turn: { status: 'interrupted', usage } };
+    const thread = await step('thread/start', {
+      ...LOCKED,
+      cwd: emptyDir(),
+      model: turn.model,
+      baseInstructions: turn.instructions,
+      dynamicTools: turn.tools.map((t) => ({ type: 'function', ...t })),
+    });
+    threadId = thread.thread && thread.thread.id;
+    if (!threadId) throw new Error('thread/start: no thread');
+    await step('thread/inject_items', { threadId, items: turn.items });
+    // The question is the last injected item: the turn starts with nothing new.
+    const started = await step('turn/start', { threadId, input: [], ...(turn.effort ? { effort: turn.effort } : {}) });
+    turnId = (started.turn && started.turn.id) || turnId;
+    const end = await Promise.race([done, stopped]);
+    const ok = end.status === 'completed';
+    return { ok, text: ok ? 'Codex finished the turn' : `(Codex ${end.status}${end.error ? `: ${end.error}` : ''})`, turn: { status: end.status, usage } };
+  } catch (e) {
+    return { ok: false, text: `(Codex: ${e.message})`, turn: { status: 'failed', usage } };
+  } finally {
+    if (signal) signal.removeEventListener('abort', onAbort);
+    session.kill();
+  }
+}
+
+module.exports = { runTurn, checkTurn, contentItems, LOCKED };