elanous 0.2.42 → 0.2.44

package/src/acp/codex-app-server-client.ts

@@ -7,15 +7,14 @@
 //   - server-originated request handling (server → client with id)
 //   - lifecycle (close · exit)
 //
-// Deliberately NOT wired into agent-manager yet — 3.B.2 is the arc
-// that connects this client to `EmbodiedAgentSession` and flips the
-// CodexApprovalAdapter from logOnly to real approval routing.
-//
 // The stream interface is abstract so tests can drive the client with
 // synthetic Duplex streams. `spawnCodexAppServer()` is the production
-// factory that shells out to `codex app-server`.
+// factory that shells out to `codex app-server`; an explicit remoteSocketPath
+// opts the ACP agent into the shadow side-tab socket without changing stdio defaults.
 
-import { spawn as spawnChild, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { spawn as spawnChild, type ChildProcess, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { PassThrough } from 'node:stream';
 import { resolvePreferredCodexBinary } from './codex-auth.js';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import type { Readable, Writable } from 'node:stream';
@@ -444,6 +443,16 @@ export class CodexAppServerClient {
     }
     this.closed = true;
   }
+
+  /** Reject only requests sent over a disconnected transport; the socket
+   *  factory may reconnect, so the client itself remains usable. */
+  _markDisconnected(error: Error): void {
+    for (const entry of this.pending.values()) {
+      if (entry.timeoutHandle) clearTimeout(entry.timeoutHandle);
+      entry.reject(error);
+    }
+    this.pending.clear();
+  }
 }
 
 // ─── Factory · spawn real codex binary ──────────────────────────────
@@ -453,6 +462,8 @@ export interface SpawnCodexAppServerOpts {
   codexBinary?: string;
   /** Subcommand args · default `['app-server']`. */
   codexArgs?: readonly string[];
+  /** Explicit opt-in endpoint for Codex remote side-tab mode. */
+  remoteSocketPath?: string;
   /** Env vars merged onto current env · e.g. `CODEX_API_KEY`.
    *  ⛔⭐ 계약: 넘긴 값이 «이기고» 나머지 부모 env 는 «보존»된다. 그리고 이 병합은
    *  `process.env` 를 «안 바꾼다» — 계정별 쿼터 측정(`usage --account`)이 여기에 걸려 있다. */
@@ -470,6 +481,80 @@ export interface SpawnedCodexAppServer {
   readonly child: ChildProcessWithoutNullStreams;
 }
 
+function createUnixSocketStreams(socketPath: string, onDisconnect: (error: Error) => void): {
+  stdin: PassThrough;
+  stdout: PassThrough;
+} {
+  const stdin = new PassThrough();
+  const stdout = new PassThrough();
+  let closed = false;
+  let activeSocket: ReturnType<typeof createConnection> | undefined;
+  let activeSocketError: ((error: Error) => void) | undefined;
+  let activeSocketClose: (() => void) | undefined;
+  let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  let connect: () => void = () => {};
+  const scheduleReconnect = (): void => {
+    if (closed || reconnectTimer) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = undefined;
+      connect();
+    }, 100);
+    reconnectTimer.unref();
+  };
+  const retireSocket = (
+    socket: ReturnType<typeof createConnection>,
+    error: Error | undefined,
+    notifyClient: boolean,
+  ): void => {
+    if (activeSocket !== socket) return;
+    activeSocket = undefined;
+    // A destroyed destination stays registered with PassThrough.pipe unless
+    // explicitly detached. Leaving it there makes the next request write to
+    // the dead socket as well as the replacement socket.
+    stdin.unpipe(socket);
+    socket.unpipe(stdout);
+    if (activeSocketError) socket.removeListener('error', activeSocketError);
+    if (activeSocketClose) socket.removeListener('close', activeSocketClose);
+    activeSocketError = undefined;
+    activeSocketClose = undefined;
+    socket.destroy();
+    if (notifyClient) onDisconnect(error ?? new Error('codex app-server socket disconnected'));
+    else scheduleReconnect(); // Initial late startup retries; reconnect after a live transport is deferred.
+  };
+  connect = (): void => {
+    if (closed) return;
+    const socket = createConnection(socketPath);
+    let didConnect = false;
+    activeSocket = socket;
+    const onSocketError = (error: Error): void => retireSocket(socket, error, didConnect);
+    const onSocketClose = (): void => retireSocket(socket, undefined, didConnect);
+    activeSocketError = onSocketError;
+    activeSocketClose = onSocketClose;
+    socket.on('error', onSocketError);
+    socket.once('close', onSocketClose);
+    socket.once('connect', () => {
+      if (closed || activeSocket !== socket) {
+        socket.destroy();
+        return;
+      }
+      didConnect = true;
+      stdin.pipe(socket);
+      // Keep the client-facing readable open across reconnects.
+      socket.pipe(stdout, { end: false });
+    });
+  };
+  stdin.once('close', () => {
+    closed = true;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    reconnectTimer = undefined;
+    if (activeSocket) retireSocket(activeSocket, undefined, false);
+    stdout.end();
+  });
+  connect();
+  return { stdin, stdout };
+}
+
+
 /** Build the argv for `codex app-server`, always FORCING codex's
  *  `code_mode_host` feature OFF.
  *
@@ -493,11 +578,53 @@ export function buildCodexAppServerArgs(codexArgs?: readonly string[]): string[]
   return args;
 }
 
-/** Spawn the `codex app-server` binary and wrap its stdio in a client.
- *
- *  3.B.1 ships this as a plain factory · no agent-manager integration.
- *  3.B.2 will wrap it behind `EmbodiedAgentSession` and flip the
- *  backend-registry `codex-app-server` transport on. */
+/** Build both command lines for the opt-in Codex remote shadow surface.
+ *  The default app-server factory remains stdio-backed; callers must
+ *  explicitly select these arguments to expose a Unix-domain endpoint. */
+export function buildCodexRemoteSideTabArgs(socketPath: string): {
+  appServerArgs: string[];
+  remoteTuiArgs: string[];
+} {
+  if (!socketPath.trim()) throw new Error('socket path is required');
+  const endpoint = `unix://${socketPath}`;
+  return {
+    appServerArgs: ['app-server', '--listen', endpoint, '-c', 'features.code_mode_host=false'],
+    remoteTuiArgs: ['--remote', endpoint],
+  };
+}
+
+/** Spawn options for the shadow mode; absent socketPath preserves stdio. */
+export function buildCodexAppServerSpawnArgs(opts: {
+  codexArgs?: readonly string[];
+  remoteSocketPath?: string;
+}): string[] {
+  const args = buildCodexAppServerArgs(opts.codexArgs);
+  if (!opts.remoteSocketPath) return args;
+  if (args.some((arg) => arg === '--listen' || arg.startsWith('--listen='))) {
+    throw new Error('remote socket path conflicts with codexArgs --listen');
+  }
+  const endpoint = `unix://${opts.remoteSocketPath}`;
+  return [...args.slice(0, -2), '--listen', endpoint, ...args.slice(-2)];
+}
+
+export function spawnCodexRemoteTui(opts: {
+  codexBinary: string;
+  socketPath: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  spawnImpl?: typeof spawnChild;
+}): ChildProcess {
+  const spawnFn = opts.spawnImpl ?? spawnChild;
+  return spawnFn(opts.codexBinary, buildCodexRemoteSideTabArgs(opts.socketPath).remoteTuiArgs, {
+    cwd: opts.cwd,
+    env: { ...process.env, ...(opts.env ?? {}) },
+    stdio: 'inherit',
+  });
+}
+
+/** Spawn the `codex app-server` binary and wrap its stdio or explicit
+ *  Unix-socket connection in a client. The ACP agent manager selects the
+ *  socket form only when the Codex remote side-tab opt-in is configured. */
 export function spawnCodexAppServer(
   opts: SpawnCodexAppServerOpts = {},
 ): SpawnedCodexAppServer {
@@ -507,7 +634,10 @@ export function spawnCodexAppServer(
   // models ("requires a newer version of Codex"). See
   // resolvePreferredCodexBinary.
   const binary = opts.codexBinary ?? resolvePreferredCodexBinary();
-  const args = buildCodexAppServerArgs(opts.codexArgs);
+  const args = buildCodexAppServerSpawnArgs({
+    codexArgs: opts.codexArgs,
+    remoteSocketPath: opts.remoteSocketPath,
+  });
   // ⛔⭐ 테스트 심 — env 병합 «계약»(넘긴 값이 이기고 나머지 부모 env 는 보존)을 무는 유일한 방법이다.
   //   계정별 쿼터 측정이 이 병합에 걸려 있고, 여기가 틀리면 「B 를 재려다 A 를 잰다」가 된다.
   const spawnFn = opts.spawnImpl ?? spawnChild;
@@ -516,9 +646,16 @@ export function spawnCodexAppServer(
     env: { ...process.env, ...(opts.env ?? {}) },
     stdio: ['pipe', 'pipe', 'pipe'],
   });
-  const client = new CodexAppServerClient({
-    stdin: child.stdin,
-    stdout: child.stdout,
+  // Remote mode speaks over the Unix socket, leaving the app-server child's
+  // stdout disconnected. Drain it so a verbose child cannot fill the pipe.
+  if (opts.remoteSocketPath) child.stdout.resume();
+  let client: CodexAppServerClient | undefined;
+  const socketStreams = opts.remoteSocketPath
+    ? createUnixSocketStreams(opts.remoteSocketPath, (error) => client?._markDisconnected(error))
+    : undefined;
+  client = new CodexAppServerClient({
+    stdin: socketStreams?.stdin ?? child.stdin,
+    stdout: socketStreams?.stdout ?? child.stdout,
     stderr: child.stderr,
     requestTimeoutMs: opts.requestTimeoutMs,
   });
@@ -537,5 +674,5 @@ export function spawnCodexAppServer(
       }
     }
   });
-  return { client, child };
+  return { client: client!, child };
 }

package/src/acp/core-turn-bridge.ts

@@ -57,6 +57,8 @@ import { isFactQuestion } from './fact-question.js';
 import { resolveSessionSurfaceProfile } from '../session-runtime/index.js';
 import { classifyTuiChatIntent, formatTuiRouteLine, isSeatOpsDirective, type TuiChatRoute } from '../core-turn/short-question.js';
 import { HARNESS_ROLE_ENV } from '../harness/harness-space.js';
+import { RESEARCH_TOOL_ALLOWLIST, RESEARCH_TURN_MAX_TOOL_TURNS } from '../core-turn/research-policy.js';
+import { isResearchAgentIntent } from '../tool-hints/signals.js';
 import { createReasoningThoughtBuffer } from './reasoning-thought-buffer.js';
 import {
   REQUEST_SIZE_MAX_CHARS,
@@ -78,7 +80,7 @@ const QUICK_TOOLS: Record<QuickTuiRoute, readonly string[]> = {
   '조회': ['decisions_pending', 'ops_seats', 'ops_status', 'release_status', 'logs_query', 'context_now', 'memory_recall', 'Read'],
   '설정 변경': ['DashboardConfigGet', 'DashboardConfigSet', 'LlmListAvailableModels', 'prompt_getRuntimeConfig', 'prompt_setRuntimeConfig', 'view_getConfig', 'view_applyRuntimeConfig', 'view_saveConfig', 'memory_recall'],
   // MsgList is a read-only ledger listing (never acks); MsgPost · MsgAck · RunShell · Bash stay out (TUI-QUICK-ROUTE-EXPLICIT-CMD).
-  '조사': ['WebSearch', 'OmniSearch', 'Grep', 'Glob', 'Read', 'fact_check', 'memory_recall', 'MsgList', 'Agent'],
+  '조사': RESEARCH_TOOL_ALLOWLIST,
   // ScheduleWakeup (H5) wakes this TUI in-process; schedule_manage is OS cron — both belong to «상시 일».
   '상시 일': ['schedule_manage', 'schedule_list', 'schedule_create', 'schedule_update', 'ScheduleWakeup', 'session_manage', 'ops_status', 'memory_recall'],
 };
@@ -329,6 +331,7 @@ export function bridgeCoreTurnToAcp(
       // (10-14 13:48 운영 TUI OP: route short-question·goalLoop ⊕ factQuestion → 소진 뒤 헛호출 7회).
       const surfaceProfile = resolveSessionSurfaceProfile({ userText: turnCtx.userText });
       const factShaped = isFactQuestion(turnCtx.userText);
+      const researchTurn = isResearchAgentIntent(turnCtx.userText);
       // A quick research/turn lookup still keeps the fact budget. Only the
       // multi-source research/agent route needs enough rounds to compare axes.
       const factQuestion = factShaped && !armGoalLoop && surfaceProfile.id !== 'research/agent';
@@ -337,7 +340,12 @@ export function bridgeCoreTurnToAcp(
         catch { /* observation cannot interrupt a turn */ }
       }
       const explicitMaxToolTurns = deps.resolveMaxToolTurns?.({ sessionId: turnCtx.sessionId });
-      const maxToolTurns = explicitMaxToolTurns ?? (factQuestion ? getUserConfig().chat.factQuestion.maxToolTurns : undefined);
+      const resolvedMaxToolTurns = explicitMaxToolTurns ?? (factQuestion
+        ? getUserConfig().chat.factQuestion.maxToolTurns
+        : researchTurn ? RESEARCH_TURN_MAX_TOOL_TURNS : undefined);
+      const maxToolTurns = researchTurn && resolvedMaxToolTurns !== undefined
+        ? Math.min(resolvedMaxToolTurns, RESEARCH_TURN_MAX_TOOL_TURNS)
+        : resolvedMaxToolTurns;
       const withFactInstruction = (seed: LLMMessage[]): LLMMessage[] => factQuestion
         ? [{ role: 'system', content: FACT_QUESTION_INSTRUCTION }, ...seed]
         : seed;
@@ -552,9 +560,7 @@ export function bridgeCoreTurnToAcp(
           onReplaceText: (full) => {
             reasoningThoughts.flush();
             streamedTextSum = full;
-            // Match the existing ACP clear/replace convention used for final synthesis.
-            void turnCtx.push('');
-            void turnCtx.push(full);
+            void turnCtx.pushWithMeta(full, { elanous: { textOperation: 'replace' } });
           },
           // P2-bridge-ext — forward tool + usage events as ACP
           // sessionUpdate notifications so extension-aware clients
@@ -725,14 +731,13 @@ export function bridgeCoreTurnToAcp(
               }
             } else if (originalFinalStreamed) {
               void turnCtx.push(followupSuffix);
+            } else if (needsReSurface && needsFollowup) {
+              // A budget follow-up is an explicit replacement of the last assistant answer,
+              // not the legacy forced-synthesis boundary used by ordinary final answers.
+              void turnCtx.pushWithMeta(visibleFinalText!, { elanous: { textOperation: 'replace' } });
             } else if (needsReSurface) {
-              // Emit a clear-then-replace pair so clients that follow
-              // the empty-chunk-as-clear convention (dashboard plain
-              // chat) reset their per-round buffer before receiving
-              // the substantive answer. The empty signal does nothing
-              // for clients that just append (web / iphone — they
-              // would only have the new finalAssistantText delta to
-              // work with anyway).
+              // Forced synthesis without a validation supplement retains the legacy clear+final
+              // boundary. Clients that treat an empty chunk as a round reset rely on this pair.
               void turnCtx.push('');
               void turnCtx.push(visibleFinalText!);
             }

package/src/acp/event-router.ts

@@ -42,7 +42,7 @@ export interface AcpSessionUpdate {
   title?: string;
   toolCallId?: string;
   status?: string;
-  _meta?: { reasoning?: unknown };
+  _meta?: { reasoning?: unknown; elanous?: { textOperation?: unknown } };
   /** Plan event 가 ref 를 직접 들고 오는 경우 (현재 ACP spec 에 없으면
    *  router 가 turn-기반 fallback ref 사용). */
   planId?: string;
@@ -100,6 +100,9 @@ interface SessionState {
    *  body.text 를 update 로 누적. */
   activeAssistantBlockId: string | null;
   activeAssistantText: string;
+  /** Last assistant block for this turn, retained across thought/tool delimiters
+   *  so an authoritative synthesis can replace a provisional answer. */
+  replaceableAssistantBlockId: string | null;
   /** Same shape for thought chunks. */
   activeThoughtBlockId: string | null;
   activeThoughtText: string;
@@ -112,6 +115,7 @@ function freshSessionState(): SessionState {
     sysSeq: 0,
     activeAssistantBlockId: null,
     activeAssistantText: '',
+    replaceableAssistantBlockId: null,
     activeThoughtBlockId: null,
     activeThoughtText: '',
   };
@@ -168,6 +172,7 @@ export function createAcpEventRouter(): AcpEventRouter {
       flushActiveThought(state);
       state.turnSeq += 1;
       state.blockSeq = 0;
+      state.replaceableAssistantBlockId = null;
       const id = makeUserTurnBlockId(sessionId, state.turnSeq, state.blockSeq);
       const block: MessageBlock = {
         id,
@@ -199,6 +204,19 @@ export function createAcpEventRouter(): AcpEventRouter {
         case 'agent_message_chunk': {
           const c = u.content;
           if (c?.type !== 'text' || typeof c.text !== 'string') return;
+          const isReplace = u._meta?.elanous?.textOperation === 'replace';
+          const replaceTargetId = state.activeAssistantBlockId ?? state.replaceableAssistantBlockId;
+          if (isReplace && replaceTargetId !== null) {
+            flushActiveThought(state);
+            state.activeAssistantText = c.text;
+            const id = replaceTargetId;
+            stream.update(id, (cur) => ({
+              ...cur,
+              body: { ...cur.body, text: c.text } as MessageBlock['body'],
+            }));
+            state.activeAssistantBlockId = id;
+            return;
+          }
           if (state.activeAssistantBlockId === null) {
             // New assistant block — close any active thought first so
             // append/update events stay temporally ordered for
@@ -211,6 +229,7 @@ export function createAcpEventRouter(): AcpEventRouter {
               state.blockSeq,
             );
             state.activeAssistantBlockId = id;
+            state.replaceableAssistantBlockId = id;
             state.activeAssistantText = c.text;
             stream.push({
               id,

package/src/acp/server.ts

@@ -1679,6 +1679,12 @@ function wireAcpConnection(
           content: { type: 'text', text: chunk },
         };
         if (_meta) update._meta = _meta;
+        const elanousMeta = _meta?.elanous;
+        if (elanousMeta && typeof elanousMeta === 'object' && !Array.isArray(elanousMeta)
+          && (elanousMeta as Record<string, unknown>).textOperation === 'replace') {
+          aggregatorAgentText = chunk;
+          try { c5dProducer?.replaceText(chunk); } catch { /* fail-soft */ }
+        }
         await broadcast(
           req.sessionId,
           update as Parameters<typeof broadcast>[1],

package/src/agent-mission/browser-roundtrip-coordinator.ts

@@ -0,0 +1,85 @@
+import type { ToolRuntimeContext } from '../tool-runtime/types.js';
+import type { BrowserHandArgs, BrowserHandDeps, BrowserHandResult } from '../tool-runtime/browser-hand-runtime.js';
+
+export type BrowserHandRunner = (args: BrowserHandArgs, ctx?: ToolRuntimeContext, deps?: BrowserHandDeps) => Promise<BrowserHandResult>;
+
+export interface HumanBrowserSelection {
+  /** Linear subtask chosen by the person for this browser roundtrip. */
+  linearSubtaskId: string;
+  /** Whether the person also chose page content to reflect in that subtask. */
+  includeThisToo?: boolean;
+  /** Optional text/tab the person explicitly selected to reflect in that subtask. */
+  selection?: { text?: string; tab?: string };
+}
+
+export interface BrowserRoundtripRequest extends Omit<BrowserHandArgs, 'linearSubtaskId' | 'selection' | 'includeThisToo'> {
+  includeThisToo?: boolean;
+  humanSelection?: HumanBrowserSelection;
+}
+
+export interface BrowserRoundtripResult {
+  scene: 'browser-roundtrip';
+  selectedSubtaskId: string | null;
+  sourceUrl: string;
+  result: BrowserHandResult;
+}
+
+/**
+ * Coordinates the demo's human-selected browser handoff through the production
+ * BrowserHand safety path. BrowserHand owns approval, host checks, one safe
+ * alternate-source attempt, capture, and the optional Linear reflection.
+ */
+export async function coordinateBrowserRoundtrip(
+  request: BrowserRoundtripRequest,
+  deps: BrowserHandDeps,
+  runBrowserHand: BrowserHandRunner,
+  ctx?: ToolRuntimeContext,
+): Promise<BrowserRoundtripResult> {
+  const selection = request.humanSelection;
+  if (!selection) {
+    return {
+      scene: 'browser-roundtrip',
+      selectedSubtaskId: null,
+      sourceUrl: request.url,
+      result: {
+        ok: false,
+        reason: 'human-selection-required',
+        output: '사람이 Linear 서브태스크를 선택해야 브라우저 왕복을 시작합니다.',
+      },
+    };
+  }
+
+  const selectedSubtaskId = selection.linearSubtaskId.trim();
+  if (!selectedSubtaskId) {
+    return {
+      scene: 'browser-roundtrip',
+      selectedSubtaskId: null,
+      sourceUrl: request.url,
+      result: {
+        ok: false,
+        reason: 'invalid-input',
+        output: 'Linear 서브태스크 UUID가 필요합니다.',
+      },
+    };
+  }
+  const args: BrowserHandArgs = {
+    url: request.url,
+    target: request.target,
+    armed: request.armed,
+    linearSubtaskId: selectedSubtaskId,
+    ...(request.persona ? { persona: request.persona } : {}),
+    ...(request.alternateUrl ? { alternateUrl: request.alternateUrl } : {}),
+    ...(request.includeThisToo !== undefined
+      ? { includeThisToo: request.includeThisToo }
+      : selection.includeThisToo !== undefined ? { includeThisToo: selection.includeThisToo } : {}),
+    // Empty selection objects mean that no page text/tab was chosen; only explicit content is forwarded.
+    ...(selection.selection ? { selection: selection.selection } : {}),
+  };
+  const result = await runBrowserHand(args, ctx, deps);
+  return {
+    scene: 'browser-roundtrip',
+    selectedSubtaskId,
+    sourceUrl: result.repairNode?.detourUrl || request.url,
+    result,
+  };
+}

package/src/agent-mission/claude-headless.ts

@@ -30,10 +30,11 @@ const string = (value: unknown): string | null => typeof value === 'string' ? va
 const number = (value: unknown): number | null => typeof value === 'number' && Number.isFinite(value) ? value : null;
 
 /** Run the non-interactive Claude CLI with a pipe, never passing the prompt as an argv value. */
-export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, timeoutMs = 1_800_000, maxTurns, onSpawn }: {
+export async function runClaudeHeadless({ cwd, prompt, env, resumeSessionId, spawn = nodeSpawn, timeoutMs = 1_800_000, maxTurns, onSpawn }: {
   cwd: string;
   prompt: string;
   env: NodeJS.ProcessEnv;
+  resumeSessionId?: string;
   spawn?: Spawn;
   timeoutMs?: number;
   maxTurns?: number;
@@ -42,6 +43,7 @@ export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, t
   if (maxTurns !== undefined && (!Number.isSafeInteger(maxTurns) || maxTurns < 1)) {
     throw new Error('Claude headless maxTurns must be a positive integer');
   }
+  if (resumeSessionId !== undefined && !resumeSessionId.trim()) throw new Error('Claude resume session id must not be empty');
   let child: ChildProcessWithoutNullStreams;
   const base: ClaudeHeadlessResult = {
     ok: false, reason: 'no-result', exitCode: null, result: null, subtype: null,
@@ -51,6 +53,7 @@ export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, t
   try {
     child = spawn('claude', [
       '-p', '--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions',
+      ...(resumeSessionId === undefined ? [] : ['--resume', resumeSessionId]),
       ...(maxTurns === undefined ? [] : ['--max-turns', String(maxTurns)]),
     ], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
   } catch {

package/src/agent-mission/codex-exec.ts

@@ -0,0 +1,105 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+
+export type CodexExecResult = {
+  ok: boolean;
+  reason: 'success' | 'no-session' | 'no-result' | 'cli-error' | 'timeout' | 'spawn-error';
+  exitCode: number | null;
+  sessionId: string | null;
+  result: string | null;
+  numTurns: number;
+  malformedLines: number;
+};
+
+type Spawn = (command: string, args: string[], options: {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdio: ['pipe', 'pipe', 'pipe'];
+}) => ChildProcessWithoutNullStreams;
+
+type JsonObject = Record<string, unknown>;
+const object = (value: unknown): value is JsonObject => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Run one non-interactive Codex exec turn, optionally resuming the exact thread from a prior turn. */
+export async function runCodexExec({ cwd, prompt, env, resumeSessionId, spawn = nodeSpawn, timeoutMs = 1_800_000, onSpawn }: {
+  cwd: string;
+  prompt: string;
+  env: NodeJS.ProcessEnv;
+  resumeSessionId?: string;
+  spawn?: Spawn;
+  timeoutMs?: number;
+  onSpawn?: (pid: number, kill: () => void) => void;
+}): Promise<CodexExecResult> {
+  if (resumeSessionId !== undefined && !resumeSessionId.trim()) throw new Error('Codex resume session id must not be empty');
+  const args = resumeSessionId === undefined
+    ? ['exec', '--json', '--approve-for-me', '-']
+    : ['exec', 'resume', '--json', '-c', 'sandbox_mode="workspace-write"', '-c', 'approval_policy="never"', resumeSessionId, '-'];
+  const base: CodexExecResult = {
+    ok: false, reason: 'no-result', exitCode: null, sessionId: null, result: null, numTurns: 0, malformedLines: 0,
+  };
+  let child: ChildProcessWithoutNullStreams;
+  try { child = spawn('codex', args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }); }
+  catch { return { ...base, reason: 'spawn-error' }; }
+  if (typeof child.pid === 'number' && child.pid > 0) onSpawn?.(child.pid, () => { try { child.kill(); } catch { /* Already exited. */ } });
+
+  return new Promise((resolve) => {
+    const state = { ...base };
+    let pending = '';
+    let sawCompletedTurn = false;
+    let failedTurn = false;
+    let timedOut = false;
+    let spawnError = false;
+    let settled = false;
+    const parseLine = (line: string): void => {
+      if (!line.trim()) return;
+      let event: unknown;
+      try { event = JSON.parse(line); }
+      catch { state.malformedLines++; return; }
+      if (!object(event) || typeof event.type !== 'string') { state.malformedLines++; return; }
+      if (event.type === 'thread.started' && typeof event.thread_id === 'string') state.sessionId = event.thread_id;
+      else if (event.type === 'item.completed' && object(event.item) && event.item.type === 'agent_message' && typeof event.item.text === 'string') {
+        state.result = event.item.text;
+      } else if (event.type === 'turn.completed') {
+        sawCompletedTurn = true;
+        state.numTurns++;
+      } else if (event.type === 'turn.failed') failedTurn = true;
+    };
+    const finish = (exitCode: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout.off('data', onData);
+      const finalLine = pending;
+      pending = '';
+      parseLine(finalLine);
+      state.exitCode = exitCode;
+      state.reason = timedOut ? 'timeout' : spawnError ? 'spawn-error'
+        : exitCode !== 0 || failedTurn ? 'cli-error'
+          : !sawCompletedTurn || !state.result ? 'no-result'
+            : !state.sessionId ? 'no-session' : 'success';
+      state.ok = state.reason === 'success';
+      resolve(state);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch { /* Report timeout even when the process cannot be killed. */ }
+      finish(null);
+    }, timeoutMs);
+    child.stdout.setEncoding('utf8');
+    const onData = (chunk: string): void => {
+      if (settled) return;
+      pending += chunk;
+      let end: number;
+      while ((end = pending.indexOf('\n')) !== -1) {
+        parseLine(pending.slice(0, end));
+        pending = pending.slice(end + 1);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.resume();
+    child.on('error', () => { spawnError = true; finish(null); });
+    child.on('close', (code) => finish(code));
+    child.stdin.on('error', () => { /* A child that exits before reading stdin is classified on close. */ });
+    try { child.stdin.end(prompt); }
+    catch { spawnError = true; try { child.kill('SIGKILL'); } catch { /* Already exited. */ } finish(null); }
+  });
+}