nomoremeatproxy 0.0.0-stage → 0.1.0

package/src/adapters/claude.mjs

@@ -0,0 +1,158 @@
+// Claude adapter. Uses `claude -p` for the turn and the official `--desktop` opener to list
+// the session in the Claude desktop app.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
+import { claudeProjectsDir } from '../history/claude.mjs';
+import { claudeUsage } from '../usage.mjs';
+import { canWrite } from '../writable.mjs';
+import { runOpener } from './opener.mjs';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TOKEN = /^[A-Za-z0-9._:-]+$/;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+// A call without write access gets the reading tools only. That makes "read-only" hold
+// whatever the owner's own permission settings are, and it cuts the fixed load of a call:
+// measured here, a one-word answer took 58,193 input tokens with every tool defined and
+// 23,218 with these three.
+const READ_ONLY_TOOLS = 'Read,Grep,Glob';
+
+function requireMatch(value, pattern, name) {
+  if (!pattern.test(String(value))) throw new Error(`invalid ${name}: ${JSON.stringify(value)}`);
+  return String(value);
+}
+
+// Without a model (null or undefined) the vendor's own default applies.
+export function buildClaudeArgs({ sessionId, resume, title, model, effort, write = false }) {
+  const id = requireMatch(sessionId, UUID, 'Claude session id');
+  return [
+    '-p',
+    '--output-format',
+    'json',
+    ...(model == null ? [] : ['--model', requireMatch(model, TOKEN, 'model')]),
+    ...(effort ? ['--effort', requireMatch(effort, TOKEN, 'effort')] : []),
+    ...(write ? [] : ['--tools', READ_ONLY_TOOLS]),
+    ...(resume ? ['--resume', id] : ['--session-id', id]),
+    ...(!resume && title ? ['--name', title] : []),
+    ...(write ? ['--permission-mode', 'acceptEdits'] : []),
+  ];
+}
+
+export function parseClaudeResult(stdout) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new Error(`Claude returned output that is not JSON: ${stdout.slice(0, 200)}`);
+  }
+  const result = Array.isArray(parsed) ? parsed.findLast((entry) => entry?.type === 'result') : parsed;
+  if (result?.type !== 'result') throw new Error('Claude output had no result entry');
+  if (result.is_error) {
+    throw new Error(`Claude turn failed: ${result.result ?? result.subtype ?? 'no detail'} (session ${result.session_id})`);
+  }
+  const usage = claudeUsage(result);
+  return { threadId: result.session_id, reply: result.result ?? '', ...(usage ? { usage } : {}) };
+}
+
+const notSent = (message) => Object.assign(new Error(message), { notSent: true });
+const WAY_OUT = 'nothing was sent. Run the call outside the sandbox, or have a Claude chat in this project listen as this peer (`nomeat listen`) so that the call is delivered to it';
+const NO_FOLDER = `Claude cannot run here: the folder it keeps its sessions in (under CLAUDE_CONFIG_DIR, or .claude in the home folder) is not writable; ${WAY_OUT}`;
+const NO_NETWORK = `Claude cannot run here: the host it talks to could not be looked up, so there is no network; ${WAY_OUT}`;
+// Includes starting the child below. Limit: a resolver slower than this fails the call.
+const LOOKUP_TIMEOUT_MS = 3000;
+const PROXY_VARIABLES = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy'];
+const LOOKUP_SCRIPT = "require('node:dns').lookup(process.argv[1], (error) => process.exit(error ? 1 : 0))";
+
+// The system's own lookup, so every name the system knows counts. dns.lookup cannot be
+// cancelled, so it runs in a child process that is ended at the limit and leaves nothing in
+// this one. Costs one short child process per headless Claude call. True only on exit code 0;
+// a child that does not start, fails or runs out of time means not looked up.
+export function lookupInChild(host, timeoutMs, start = spawn) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = start(process.execPath, ['-e', LOOKUP_SCRIPT, '--', host], { stdio: 'ignore', timeout: timeoutMs, windowsHide: true });
+    } catch {
+      resolve(false);
+      return;
+    }
+    child.once('error', () => resolve(false));
+    child.once('exit', (code) => resolve(code === 0));
+  });
+}
+
+// Run before `claude` starts, so that a call that cannot work fails at once, as not sent.
+// Inside Codex's sandbox on Linux and macOS there is no network and Claude's folder is
+// read-only; there the command line hung instead of failing.
+export async function checkClaudeCanRun({ env = process.env, resolve = lookupInChild, writable = canWrite, timeoutMs = LOOKUP_TIMEOUT_MS } = {}) {
+  if (!writable(claudeProjectsDir(env))) throw notSent(NO_FOLDER);
+  // Limit: behind a proxy a name lookup can fail while the command line still works, so the
+  // lookup is skipped there and a missing network is then not caught.
+  if (PROXY_VARIABLES.some((name) => env[name])) return;
+  // Limit: with Bedrock or Vertex the command line talks to other hosts; this one is still looked up.
+  const host = URL.parse(env.ANTHROPIC_BASE_URL ?? '')?.hostname || 'api.anthropic.com';
+  // An address or localhost needs no lookup.
+  if (isIP(host.replace(/[[\]]/g, '')) || host === 'localhost') return;
+  if (!(await resolve(host, timeoutMs))) throw notSent(NO_NETWORK);
+}
+
+// No shell: the arguments are passed as an array and the message goes in on stdin.
+function runClaude(args, { input, cwd, timeoutMs, start }) {
+  return new Promise((resolve, reject) => {
+    const child = start('claude', args, { cwd, stdio: 'pipe', windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', (chunk) => (stdout += chunk));
+    child.stderr.on('data', (chunk) => (stderr += chunk));
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ code, stdout, stderr });
+    });
+    child.stdin.end(input);
+  });
+}
+
+export async function callClaude({ threadId, message, title, model, effort, write = false, cwd = process.cwd(), onThread = () => {}, timeoutMs = DEFAULT_TIMEOUT_MS, canRun = checkClaudeCanRun, start = spawn }) {
+  const sessionId = threadId ?? randomUUID();
+  const args = buildClaudeArgs({ sessionId, resume: Boolean(threadId), title, model, effort, write });
+  await canRun();
+  // The id is chosen here, so it is known before anything is sent.
+  onThread(sessionId);
+  const { code, stdout, stderr } = await runClaude(args, { input: message, cwd, timeoutMs, start });
+  if (!stdout.trim()) {
+    throw new Error(`Claude exited with code ${code} and no output: ${stderr.trim().slice(0, 300)} (session ${sessionId})`);
+  }
+  return { ...parseClaudeResult(stdout), delivery: 'headless', access: write ? 'write' : 'read-only', ...(effort ? { effort } : {}) };
+}
+
+// On Linux the vendor's opener says that `--desktop` works on macOS and Windows only.
+const NO_OPENER = 'the vendor offers no opener for the Claude app on this platform, so nothing was attempted';
+// A Mac run listed the chat within 3 seconds; this leaves room for a slow start.
+const OPENER_TIMEOUT_MS = 20 * 1000;
+
+// The command that runs the official opener, or the reason it is not run. The opener refuses
+// to run without a terminal, so it is given one.
+function openerCommand(platform, id) {
+  const opener = ['claude', '--desktop', '--resume', id];
+  // On Windows it gets a console window of its own. Exit code 0 here only shows that this
+  // window was launched, not that the chat was listed: `start` does not wait for the opener.
+  if (platform === 'win32') return { command: ['cmd.exe', ['/c', 'start', '/min', ...opener]] };
+  // On macOS it runs under a pseudo-terminal with no window, and its own exit code comes back.
+  if (platform === 'darwin') return { command: ['script', ['-q', '/dev/null', ...opener]] };
+  return { reason: NO_OPENER };
+}
+
+// Runs the opener and waits for it to exit (see runOpener). A failure to start, another exit
+// code or running out of time is reported, never thrown.
+// `supported: false` only where no opener exists, so that callers can tell it from a failure.
+export function openInClaudeApp(sessionId, { cwd = process.cwd(), platform = process.platform, start = spawn, timeoutMs = OPENER_TIMEOUT_MS } = {}) {
+  const id = requireMatch(sessionId, UUID, 'Claude session id');
+  const { command, reason } = openerCommand(platform, id);
+  if (!command) return Promise.resolve({ opened: false, supported: false, reason });
+  return runOpener(command, { cwd, start, timeoutMs }).catch((error) => ({ opened: false, reason: `the opener did not start: ${error.message}` }));
+}

package/src/adapters/codex-app.mjs

@@ -0,0 +1,58 @@
+// Opens a Codex thread in the Codex desktop app by its link, `codex://threads/<id>`, which the
+// vendor documents as the link that opens an existing local chat. The running app does not list
+// a thread the bridge created until it re-reads its list (hiccup 40). Seen twice on Windows:
+// after the link was opened, the app showed and listed the chat without a relaunch, once after
+// a delay that was not timed and once within seconds. On macOS and Linux the same commands, run
+// by hand once each, made the app list the chat within seconds; see the usage notes.
+import { spawn } from 'node:child_process';
+import { SERVER_STILL_RUNNING } from './codex-transport.mjs';
+import { runOpener } from './opener.mjs';
+
+// Codex thread ids seen so far are UUIDs. Checked before anything starts, since cmd.exe reads
+// its own command line: an id of another shape is never put into a link.
+const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// These openers hand the link to the system and return; the limit is for one that does not.
+// Not measured.
+const OPENER_TIMEOUT_MS = 10 * 1000;
+const NO_OPENER = 'no opener for links is known on this platform, so nothing was attempted';
+
+function openerCommand(platform, link) {
+  // The empty argument reaches cmd.exe as "", which `start` takes as the window title, so the
+  // link is what it opens. `start` exits once the system has taken the link.
+  if (platform === 'win32') return ['cmd.exe', ['/c', 'start', '', link]];
+  if (platform === 'darwin') return ['open', [link]];
+  if (platform === 'linux') return ['xdg-open', [link]];
+  return null;
+}
+
+// `opened: true` means only that the opener exited with code 0, so the system took the link; it
+// does not show that the app listed the chat. Never throws: a failure to open must not fail a
+// call that was answered. `supported: false` where there is no opener: an unknown platform, or
+// an opener program that is not installed.
+export function openInCodexApp(threadId, { platform = process.platform, start = spawn, timeoutMs = OPENER_TIMEOUT_MS } = {}) {
+  if (!THREAD_ID.test(String(threadId))) {
+    return Promise.resolve({ opened: false, reason: 'the thread id is not a UUID, so nothing was opened' });
+  }
+  const command = openerCommand(platform, `codex://threads/${threadId}`);
+  if (!command) return Promise.resolve({ opened: false, supported: false, reason: NO_OPENER });
+  return runOpener(command, { start, timeoutMs }).catch((error) =>
+    error.code === 'ENOENT'
+      ? { opened: false, supported: false, reason: `${command[0]} was not found, so nothing was opened` }
+      : { opened: false, reason: `the opener did not start: ${error.message}` });
+}
+
+// After a call: opens only a thread the call created, never one it continued. While the bridge's
+// own server runs it holds the thread, and a call returns only once that server has ended
+// (withCodexServer), up to a limit. Past the limit the call carries SERVER_STILL_RUNNING as its
+// warning, and the link is opened anyway. A call sent without waiting, or through the app's
+// queue, never creates a thread. `optOut` is `--no-open`.
+export async function openNewCodexThread({ outcome, optOut, ...options }) {
+  if (optOut || outcome.state !== 'answered' || outcome.continued !== false) return;
+  const app = await openInCodexApp(outcome.threadId, options);
+  if (outcome.warning !== SERVER_STILL_RUNNING) {
+    outcome.app = app;
+    return;
+  }
+  const early = `${SERVER_STILL_RUNNING}, so the chat may not come up in the app until its link is opened again`;
+  outcome.app = { ...app, reason: app.reason ? `${early}; ${app.reason}` : early };
+}

package/src/adapters/codex-cli.mjs

@@ -0,0 +1,38 @@
+// Runs the Codex CLI without a shell, so free text can be passed as an argument safely.
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+const whereCodex = () => execFileSync('where.exe', ['codex'], { encoding: 'utf8' }).split(/\r?\n/).filter(Boolean);
+
+// npm installs Codex on Windows as a .cmd shim, which only a shell can start. The shim's
+// Node entry point is run directly instead. Windows path rules apply whatever the host is.
+export function resolveCodexCommand({ platform = process.platform, where = whereCodex, exists = existsSync, node = process.execPath } = {}) {
+  if (platform !== 'win32') return { file: 'codex', prefix: [] };
+  const found = where();
+  const executable = found.find((candidate) => candidate.toLowerCase().endsWith('.exe'));
+  if (executable) return { file: executable, prefix: [] };
+  for (const shim of found) {
+    const entry = path.win32.join(path.win32.dirname(shim), 'node_modules', '@openai', 'codex', 'bin', 'codex.js');
+    if (exists(entry)) return { file: node, prefix: [entry] };
+  }
+  throw new Error('could not find a Codex executable that runs without a shell');
+}
+
+// A failure carries `notStarted: true` only when the command never ran: no executable was
+// found, or it could not be spawned. After that, a failure or time-out may have done its work.
+export async function runCodexCli(args, { timeoutMs = 60000 } = {}) {
+  let command;
+  try {
+    command = resolveCodexCommand();
+  } catch (error) {
+    throw Object.assign(error, { notStarted: true });
+  }
+  return new Promise((resolve, reject) => {
+    execFile(command.file, [...command.prefix, ...args], { timeout: timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+      if (!error) return resolve({ stdout, stderr });
+      const notStarted = typeof error.syscall === 'string' && error.syscall.startsWith('spawn');
+      reject(Object.assign(new Error(`codex ${args[0]} failed: ${stderr.trim().split('\n').at(-1) || error.message}`), { notStarted }));
+    });
+  });
+}

package/src/adapters/codex-daemon.mjs

@@ -0,0 +1,47 @@
+// Makes sure Codex's local daemon runs before a message is queued that nothing else may run.
+// A queued message is only stored; the daemon loads the chat and runs it. Only `--help`,
+// `version` and `start` are ever issued: nothing here stops, restarts, updates or configures it.
+const VERSION_TIMEOUT_MS = 10_000;
+const START_TIMEOUT_MS = 30_000;
+
+export const DAEMON_NOT_STARTED =
+  'queued, but the daemon could not be started, so the message may not run until the chat is opened in the Codex app';
+
+const daemon = (command) => ['app-server', 'daemon', command];
+
+// Whether `codex app-server daemon` offers `start` and `version`, asked once per runner.
+const offered = new WeakMap();
+function offersDaemon(runCli) {
+  if (!offered.has(runCli)) {
+    const listed = ({ stdout = '' } = {}) => /^\s+start\s/m.test(stdout) && /^\s+version\s/m.test(stdout);
+    offered.set(runCli, runCli(daemon('--help')).then(listed, () => false));
+  }
+  return offered.get(runCli);
+}
+
+// Seen live: a running daemon answers one JSON object with `"status":"running"`; a stopped one
+// makes the command fail with a connection error. Anything else counts as not running, which
+// only costs a `start`, and that leaves a running daemon alone.
+async function isRunning(runCli) {
+  try {
+    const { stdout = '' } = (await runCli(daemon('version'), { timeoutMs: VERSION_TIMEOUT_MS })) ?? {};
+    return JSON.parse(stdout)?.status === 'running';
+  } catch {
+    return false;
+  }
+}
+
+// True when the daemon runs, or was started, or a concurrent sender started it first.
+// Never throws: nothing is queued yet, so a failure here must not count as a delivery.
+// A failed start is checked again with `version`: the wording of a lost race was not seen,
+// and a start that hands its output pipes to the daemon may only end at its time limit.
+export async function ensureDaemon(runCli) {
+  if (!(await offersDaemon(runCli))) return false;
+  if (await isRunning(runCli)) return true;
+  try {
+    await runCli(daemon('start'), { timeoutMs: START_TIMEOUT_MS });
+    return true;
+  } catch (error) {
+    return /already.?running/i.test(error?.message ?? '') || isRunning(runCli);
+  }
+}

package/src/adapters/codex-transport.mjs

@@ -0,0 +1,90 @@
+// Client for `codex app-server` over stdio: one JSON object per line. Requests carry an id;
+// notifications do not. This is the entry point the Codex desktop app itself uses.
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+
+const CLIENT_INFO = Object.freeze({ name: 'nomoremeatproxy', title: 'NOMOREMEATPROXY', version: '0.1.0' });
+// Seen on Windows: the server was gone 15 to 25 ms after it was told to stop.
+const EXIT_TIMEOUT_MS = 5000;
+
+export const SERVER_STILL_RUNNING = `the bridge's own Codex server had not exited ${EXIT_TIMEOUT_MS / 1000} seconds after it was told to stop`;
+
+function connect({ onNotification, onClosed, start }) {
+  // Constant command line: payloads travel as JSON on stdin, never through the shell.
+  const server = start('codex app-server', { shell: true, stdio: ['pipe', 'pipe', 'ignore'] });
+  // 'close', not 'exit': the server runs under a shell, which exits at the stop signal while the
+  // server itself is still running. Its output closes only when every process holding it has
+  // ended. Seen on Windows: shell, then Codex's Node launcher, then the server.
+  const ended = new Promise((resolve) => server.once('close', resolve));
+  const pending = new Map();
+  let nextId = 1;
+  const write = (message) => server.stdin.write(`${JSON.stringify(message)}\n`);
+  const closed = (error) => {
+    for (const waiter of pending.values()) waiter.reject(error);
+    pending.clear();
+    onClosed(error);
+  };
+  server.on('error', closed);
+  server.on('exit', () => closed(new Error('codex app-server exited before the work completed')));
+
+  readline.createInterface({ input: server.stdout }).on('line', (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (message.method === undefined) {
+      const waiter = pending.get(message.id);
+      if (!waiter) return;
+      pending.delete(message.id);
+      if (message.error) waiter.reject(new Error(`Codex rejected the request: ${JSON.stringify(message.error)}`));
+      else waiter.resolve(message.result);
+    } else if (message.id === undefined) {
+      onNotification(message.method, message.params ?? {});
+    } else {
+      // An approval or question for a human. Nobody is there, so decline instead of hanging.
+      write({ id: message.id, error: { code: -32601, message: 'nomeat cannot answer interactive requests' } });
+    }
+  });
+
+  return {
+    request: (method, params) =>
+      new Promise((resolve, reject) => {
+        const id = nextId;
+        nextId += 1;
+        pending.set(id, { resolve, reject });
+        write({ id, method, params });
+      }),
+    notify: (method) => write({ method }),
+    // Stops the server and waits for it to end, up to the limit. True when it ended in time.
+    // Never throws, so that it cannot replace the result of the work.
+    close: async (timeoutMs) => {
+      try {
+        server.stdin.end();
+        server.kill();
+      } catch {
+        // Waited for below like any other stop.
+      }
+      let timer;
+      const limit = new Promise((resolve) => (timer = setTimeout(resolve, timeoutMs, false)));
+      const exited = await Promise.race([ended.then(() => true), limit]);
+      clearTimeout(timer);
+      return exited;
+    },
+  };
+}
+
+// Starts a server, completes the handshake, runs `work(client)` and always shuts the server down.
+// It returns once the server has ended, so that nothing holds a thread the work used; a server
+// that has not ended at the limit is left and reported to `onStillRunning`.
+export async function withCodexServer(work, { onNotification = () => {}, onClosed = () => {}, onStillRunning = () => {}, start = spawn, exitTimeoutMs = EXIT_TIMEOUT_MS } = {}) {
+  const client = connect({ onNotification, onClosed, start });
+  try {
+    await client.request('initialize', { clientInfo: CLIENT_INFO });
+    client.notify('initialized');
+    return await work(client);
+  } finally {
+    if (!(await client.close(exitTimeoutMs))) onStillRunning();
+  }
+}

package/src/adapters/codex.mjs

@@ -0,0 +1,268 @@
+// Codex adapter for calls. Threads are created through `codex app-server`, so they are listed
+// in the Codex desktop app; threads from `codex exec` are not. A thread the app holds open
+// accepts only one writer, so messages for it go through Codex's queue and the app runs them.
+// Sections: turn state (pure) / direct turn / queued turn / callCodex.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { codexBaseline, codexUsage } from '../usage.mjs';
+import { runCodexCli } from './codex-cli.mjs';
+import { DAEMON_NOT_STARTED, ensureDaemon } from './codex-daemon.mjs';
+import { SERVER_STILL_RUNNING, withCodexServer } from './codex-transport.mjs';
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const POLL_MS = 3000;
+const ACTIVE_WRITER = /already has an active writer/;
+
+const notSent = (message) => Object.assign(new Error(message), { notSent: true });
+
+// --- turn state (pure) ---
+
+export const newTurnState = () => ({ threadId: null, turnId: null, replies: [], done: false, status: null, error: null, usageBefore: null, usageNow: null });
+
+// One server reports every thread it runs, a helper agent's threads included. An event names its
+// thread (`threadId`) and turn (`turnId`, or `turn.id` on turn/completed); it counts only when
+// those match this call's. The turn id is known once turn/start answers, so an event of this
+// thread that comes before that is still taken. An event that names neither counts, as before.
+function ownEvent(state, params) {
+  const turnId = params.turnId ?? params.turn?.id;
+  if (params.threadId == null && turnId == null) return true;
+  if (params.threadId != null && params.threadId !== state.threadId) return false;
+  return turnId == null || state.turnId == null || turnId === state.turnId;
+}
+
+export function foldTurnEvent(state, method, params) {
+  if (!ownEvent(state, params)) return state;
+  if (method === 'item/completed' && params.item?.type === 'agentMessage') {
+    return { ...state, replies: [...state.replies, params.item] };
+  }
+  if (method === 'thread/tokenUsage/updated' && params.tokenUsage?.total) {
+    return { ...state, usageBefore: state.usageBefore ?? codexBaseline(params.tokenUsage), usageNow: params.tokenUsage.total };
+  }
+  if (method === 'turn/completed') {
+    const turn = params.turn ?? {};
+    return { ...state, done: true, status: turn.status ?? 'completed', error: turn.error?.message ?? null };
+  }
+  return state;
+}
+
+const endTurn = (state, status, error) => (state.done ? state : { ...state, done: true, status, error });
+
+// A turn's answer, from its agent messages in order. Codex marks interim status lines with the
+// phase `commentary`, and answer text with `final_answer` or, by its schema, `partial_answer`
+// (not seen so far). Where no message is marked as answer, as in a turn that did not finish or
+// from a model that sets no phase, the last message stands.
+const ANSWER = new Set(['final_answer', 'partial_answer']);
+
+export function turnAnswer(messages) {
+  const answer = messages.filter((message) => ANSWER.has(message.phase));
+  return (answer.length ? answer : messages.slice(-1)).map((message) => message.text).join('\n\n');
+}
+
+const carries = (item, marker) =>
+  item.type === 'userMessage' && (item.content ?? []).some((part) => part.type === 'text' && part.text.includes(marker));
+
+// The turn that carries this request's marker, or null when the thread does not have it yet.
+// Read from outside, a turn the app is still running reports `interrupted`, so only
+// `completed` and `failed` are final.
+export function findRequestTurn(turns, marker) {
+  const turn = turns.findLast((candidate) => (candidate.items ?? []).some((item) => carries(item, marker)));
+  if (!turn) return null;
+  const reply = turnAnswer(turn.items.filter((item) => item.type === 'agentMessage'));
+  return { status: turn.status, reply, error: turn.error?.message ?? null };
+}
+
+async function readTurns(client, threadId) {
+  const { thread } = await client.request('thread/read', { threadId, includeTurns: true });
+  return thread.turns ?? [];
+}
+
+async function readRequestTurn(client, { threadId, marker }) {
+  return findRequestTurn(await readTurns(client, threadId), marker);
+}
+
+// For a retry after an uncertain delivery: the reply, if the thread already holds a finished one.
+export async function recoverCodexReply({ threadId, marker }) {
+  if (!threadId) return null;
+  const turn = await withCodexServer((client) => readRequestTurn(client, { threadId, marker }));
+  return turn?.status === 'completed' ? { reply: turn.reply } : null;
+}
+
+// Where a request stands in its thread, for following up on a message sent without waiting.
+// A request not in the thread yet is `waiting`. `idle` is true only when the thread's newest
+// turn is seen finished, so nothing is running there; without turns nothing is seen.
+export function describeRequestTurn(turns, marker) {
+  const turn = findRequestTurn(turns, marker);
+  if (!turn) return { state: 'waiting', idle: ['completed', 'failed'].includes(turns.at(-1)?.status) };
+  if (turn.status === 'completed') return { state: 'answered', reply: turn.reply };
+  if (turn.status === 'failed') return { state: 'failed', error: turn.error };
+  return { state: 'running' };
+}
+
+export async function checkCodexRequest({ threadId, marker }) {
+  return describeRequestTurn(await withCodexServer((client) => readTurns(client, threadId)), marker);
+}
+
+// --- direct turn ---
+
+// Without a model (null or undefined) none is sent, so Codex applies its own default.
+export const modelParam = (model) => (model == null ? {} : { model });
+
+// A new thread gets the bridge's policy and a title. An existing thread keeps its own
+// settings, which may belong to a thread the owner uses in the app; only `write` changes them.
+async function openThread(client, { threadId, title, model, write, cwd }) {
+  if (threadId) {
+    const resumed = await client.request('thread/resume', { threadId, ...(write ? { sandbox: 'workspace-write' } : {}) });
+    return resumed.thread.id;
+  }
+  const policy = { cwd, ...modelParam(model), sandbox: write ? 'workspace-write' : 'read-only', approvalPolicy: 'never' };
+  const started = await client.request('thread/start', policy);
+  // The title is cosmetic; a refusal must not fail the call.
+  if (title) await client.request('thread/name/set', { threadId: started.thread.id, name: title }).catch(() => {});
+  return started.thread.id;
+}
+
+// What a direct turn applied. A resumed thread keeps the access it had unless `write` raised it.
+export const appliedSettings = ({ threadId, write, effort }) => ({
+  ...(write ? { access: 'write' } : threadId ? {} : { access: 'read-only' }),
+  ...(effort ? { effort } : {}),
+});
+
+async function runTurn({ threadId, message, title, model, effort, write, cwd, onThread, timeoutMs, withServer }) {
+  let turn = newTurnState();
+  let settle;
+  const finished = new Promise((resolve) => {
+    settle = resolve;
+  });
+  const finish = (next) => {
+    turn = next;
+    if (turn.done) settle();
+  };
+  const timer = setTimeout(() => finish(endTurn(turn, 'timed-out', `no completed turn within ${timeoutMs} ms`)), timeoutMs);
+  let stillRunning = false;
+  try {
+    const result = await withServer(
+      async (client) => {
+        const id = await openThread(client, { threadId, title, model, write, cwd }).catch((error) => {
+          // Nothing has been sent yet, so a retry cannot duplicate anything.
+          error.notSent = true;
+          throw error;
+        });
+        turn = { ...turn, threadId: id };
+        onThread(id);
+        const started = await client.request('turn/start', {
+          threadId: id,
+          input: [{ type: 'text', text: message }],
+          ...modelParam(model),
+          ...(effort ? { effort } : {}),
+        });
+        turn = { ...turn, turnId: started?.turn?.id ?? null };
+        await finished;
+        if (turn.status !== 'completed') {
+          throw new Error(`Codex turn ${turn.status}: ${turn.error ?? 'no detail'} (thread ${id})`);
+        }
+        const usage = codexUsage(turn.usageBefore, turn.usageNow);
+        return { threadId: id, reply: turnAnswer(turn.replies), delivery: 'direct', ...appliedSettings({ threadId, write, effort }), ...(usage ? { usage } : {}) };
+      },
+      {
+        onNotification: (method, params) => finish(foldTurnEvent(turn, method, params)),
+        onClosed: (error) => finish(endTurn(turn, 'failed', error.message)),
+        onStillRunning: () => (stillRunning = true),
+      },
+    );
+    // The answer stands; the server may still hold the thread.
+    return stillRunning ? { ...result, warning: SERVER_STILL_RUNNING } : result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- queued turn ---
+
+// Whether `codex queue` offers `--resume`, asked once per runner: once per process for the real one.
+const resumeOffered = new WeakMap();
+function offersResume(runCli) {
+  if (!resumeOffered.has(runCli)) {
+    resumeOffered.set(runCli, runCli(['queue', '--help']).then(({ stdout = '' } = {}) => /--resume\b/.test(stdout), () => false));
+  }
+  return resumeOffered.get(runCli);
+}
+
+// Hands the message to Codex's queue, exactly once. A queued message is only stored; `--resume`
+// asks the local daemon to load the chat and run its queue. A failed resume warns on stderr
+// but succeeds, so the delivery stands and the warning goes back to the caller. Codex also
+// prints routine warnings on stderr (seen: one about PATH aliases), so only lines that mention
+// resuming count. Limit: the wording of a failed resume was not seen; one that does not
+// mention resuming is missed.
+const resumeWarning = (stderr) => stderr.split(/\r?\n/).filter((line) => /resum/i.test(line)).join('\n').trim();
+
+// A failure of the queue command counts as not sent only when it never ran (`notStarted`).
+// Otherwise the message may already be queued, for example when a resume hangs past the time
+// limit, so the error is left as possibly delivered and a retry of the request does not queue again.
+async function queueMessage({ threadId, message, runCli }) {
+  const resume = (await offersResume(runCli)) ? ['--resume'] : [];
+  const ran = await runCli(['queue', '--thread', threadId, '--message', message, ...resume]).catch((error) => {
+    error.notSent = error.notStarted === true;
+    throw error;
+  });
+  const { stderr = '' } = ran ?? {};
+  const warning = resume.length ? resumeWarning(stderr) : '';
+  return warning ? { warning } : {};
+}
+
+// The app that holds the thread runs the turn with the thread's own model and settings, so the
+// daemon is not started here. Seen live: Codex warns that it could not resume such a thread
+// although the app runs it, so the warning is left out of an answer and kept when none arrives.
+async function runQueuedTurn({ threadId, message, marker, onThread, timeoutMs, runCli, withServer }) {
+  const warned = await queueMessage({ threadId, message, runCli });
+  onThread(threadId);
+  const deadline = Date.now() + timeoutMs;
+  return withServer(async (client) => {
+    while (Date.now() < deadline) {
+      const turn = await readRequestTurn(client, { threadId, marker });
+      if (turn?.status === 'completed') return { threadId, reply: turn.reply, delivery: 'queued' };
+      if (turn?.status === 'failed') throw new Error(`Codex turn failed: ${turn.error ?? 'no detail'} (thread ${threadId})`);
+      await sleep(POLL_MS);
+    }
+    const warning = warned.warning ? `; codex warned: ${warned.warning}` : '';
+    throw new Error(`the message is queued for thread ${threadId} but no finished reply appeared within ${timeoutMs} ms; it has not finished, cause unknown${warning}`);
+  });
+}
+
+// --- callCodex ---
+
+// The app runs a queued message with the thread's own access, which `write` cannot raise.
+function refuseQueuedWrite({ write, threadAccess }) {
+  if (write && threadAccess !== 'write') {
+    throw notSent(
+      "the Codex app holds this thread and runs queued messages with the thread's own access, which the bridge did not set to write; send without --write if that chat already has write access in the app, or start a thread with --new --write",
+    );
+  }
+}
+
+// Hands the message to Codex's queue and returns, without knowing when it will run. Nothing may
+// have the chat loaded, so Codex's daemon is started first. Without `--resume` nothing asks the
+// daemon to run the message, so it is left alone and the message is queued as before.
+async function queueOnly({ threadId, message, onThread, write, threadAccess, runCli }) {
+  if (!threadId) throw notSent('sending without waiting needs an existing Codex thread; name it with --thread or call once with waiting first');
+  refuseQueuedWrite({ write, threadAccess });
+  const daemonUp = (await offersResume(runCli)) ? await ensureDaemon(runCli) : true;
+  const { warning = '' } = await queueMessage({ threadId, message, runCli });
+  onThread(threadId);
+  // Seen live: for a chat the app holds, Codex warns that the thread already has an active
+  // writer, and the app runs the message. That line is left out; any other is passed back.
+  const codexWarning = warning.split('\n').filter((line) => !ACTIVE_WRITER.test(line)).join('\n');
+  if (daemonUp) return { threadId, delivery: 'queued', ...(codexWarning ? { warning: codexWarning } : {}) };
+  const codexLine = codexWarning ? `; codex warned: ${codexWarning}` : '';
+  return { threadId, delivery: 'queued', warning: `${DAEMON_NOT_STARTED}${codexLine}` };
+}
+
+// `threadAccess` is what the ledger recorded for the thread, or null when unknown.
+export async function callCodex({ threadId, message, marker, title, model, effort, write = false, threadAccess = null, cwd = process.cwd(), onThread = () => {}, timeoutMs = DEFAULT_TIMEOUT_MS, noWait = false, runCli = runCodexCli, withServer = withCodexServer }) {
+  if (noWait) return queueOnly({ threadId, message, onThread, write, threadAccess, runCli });
+  try {
+    return await runTurn({ threadId, message, title, model, effort, write, cwd, onThread, timeoutMs, withServer });
+  } catch (error) {
+    if (!threadId || !ACTIVE_WRITER.test(error.message)) throw error;
+    refuseQueuedWrite({ write, threadAccess });
+    return runQueuedTurn({ threadId, message, marker, onThread, timeoutMs, runCli, withServer });
+  }
+}