@ckanner/flywheel 0.32.1 → 0.33.1

package/node_modules/dsh-subagent-codex-pro/lib/run.js

@@ -0,0 +1,842 @@
+/**
+ * One-shot Codex child lifecycle over the real app-server.
+ *
+ * The run has one deadline from before startup through the terminal turn. Every
+ * startup RPC (initialize, thread/start, thread/resume, thread/name/set) and the
+ * turn use the same derived abort signal, so a server that stops answering
+ * cannot keep a delegation alive past its budget. Cleanup is a separate, finite
+ * grace: the deadline ends work, the grace ends the process range.
+ *
+ * The child is spawned as the leader of its own POSIX process group. Termination
+ * targets the group and then proves it is gone; a descendant that ignores
+ * SIGTERM or outlives its parent is reported instead of being silently assumed
+ * dead.
+ *
+ * @module dsh-subagent-codex-pro/run
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { LineTransport } from "./jsonrpc.js";
+import { verifyStructuredOutput } from "./structured.js";
+import { CodexAppServerWire, DEFAULT_ORIGINATOR, raceAbort, } from "./wire.js";
+/** Default grace between termination tiers. */
+const DEFAULT_DISPOSE_GRACE_MS = 3_000;
+/** Hard upper bound on observing a process group disappear after SIGKILL. */
+const GROUP_REAP_TIMEOUT_MS = 2_000;
+/** A dead leader cannot lend an infinite stdout lease to a descendant. */
+const EXIT_DRAIN_TIMEOUT_MS = 1_000;
+/** Bound protocol and diagnostic output retained/forwarded by this adapter. */
+const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * How long one delegation may take before it is cancelled.
+ *
+ * A delegation that hangs is invisible: the job stays `running`, nothing is
+ * logged, and the session waits. The deadline turns that into a failure with a
+ * reason. Ten minutes is generous against a package whose own README says a
+ * delegation takes "a minute or more", and `0` disables it.
+ */
+export const DEFAULT_RUN_TIMEOUT_MS = 600_000;
+/** A run failure, kept for its structured facts and any cleanup it observed. */
+export class CodexRunFailure extends Error {
+    facts;
+    cleanup;
+    execution;
+    configuration;
+    usage;
+    rateLimits;
+    turnConfiguration;
+    constructor(facts, cause, cleanup, observations) {
+        const cleanupDetail = cleanup?.confirmed === false
+            ? `; process cleanup unconfirmed${cleanup.detail === undefined ? '' : `: ${cleanup.detail}`}`
+            : '';
+        super(`codex-pro: product subagent failure (${describeFacts(facts)})${cleanupDetail}`, cause === undefined ? undefined : { cause });
+        this.facts = facts;
+        this.cleanup = cleanup;
+        this.execution = observations?.execution;
+        this.configuration = observations?.configuration;
+        this.usage = observations?.usage;
+        this.rateLimits = observations?.rateLimits;
+        this.turnConfiguration = observations?.turnConfiguration;
+        this.name = 'CodexRunFailure';
+    }
+}
+/** The diagnostic for a delegation the deadline stopped. */
+export function describeTimeout(timeoutMs) {
+    return `codex-pro: the delegation exceeded its ${String(timeoutMs)} ms deadline and was cancelled`;
+}
+/** Render failure facts for a diagnostic string. */
+function describeFacts(facts) {
+    const fields = ['product: Codex', `stage: ${facts.stage}`, `category: ${facts.category}`];
+    if (facts.httpStatus !== undefined)
+        fields.push(`HTTP status: ${facts.httpStatus}`);
+    return fields.join('; ');
+}
+/** Normalise an unknown throwable. */
+function thrown(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/** Append a bounded reason to an optional diagnostic. */
+function appendDiagnostic(diagnostic, detail) {
+    return diagnostic === undefined ? detail : `${diagnostic}; ${detail}`;
+}
+/** A valid snapshot before interruption is a known lower bound, not a final bill. */
+function partialUsage(usage, reason) {
+    if (usage.status !== 'complete')
+        return usage;
+    return { ...usage, status: 'partial', reason: usage.reason === undefined ? reason : `${usage.reason}; ${reason}` };
+}
+/** A short non-throwing delay. */
+function delay(ms) {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+/**
+ * Validate and preserve the one-shot task before crossing the process boundary.
+ *
+ * @param prompt - the delegation's content blocks.
+ * @returns the exact non-empty text block sequence.
+ */
+export function textTask(prompt) {
+    if (prompt.length === 0)
+        throw new Error('codex-pro: a delegation prompt must be text; images reach Codex through the '
+            + '`images` parameter, which takes absolute paths');
+    const texts = [];
+    for (const block of prompt) {
+        if (block.type !== 'text' || typeof block.text !== 'string') {
+            throw new Error('codex-pro: a delegation prompt must be text; images reach Codex through the '
+                + '`images` parameter, which takes absolute paths');
+        }
+        texts.push(block.text);
+    }
+    if (texts.every((text) => text.trim().length === 0)) {
+        throw new Error('codex-pro: the one-shot task must not be empty');
+    }
+    return texts;
+}
+/**
+ * Spawn the app-server and wrap its lifecycle.
+ *
+ * The child is detached into its own process group on POSIX so termination can
+ * target everything the delegation owns without a global `killall`. Termination
+ * is idempotent and resolves with a confirmation report rather than assuming
+ * that a signal is the same thing as a dead process.
+ *
+ * @param spec - the executable, working directory, and environment.
+ * @returns the managed child.
+ */
+function spawnAppServer(spec) {
+    const posix = process.platform !== 'win32';
+    const graceMs = spec.disposeGraceMs ?? DEFAULT_DISPOSE_GRACE_MS;
+    // tsc rewrites import specifiers, not new URL strings. Native TS tests and
+    // the built npm package must each start their matching guardian artifact.
+    const extension = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+    const guardian = fileURLToPath(new URL(`./process-guardian${extension}`, import.meta.url));
+    const proc = spawn(posix ? process.execPath : spec.command, posix ? [guardian, spec.command, String(graceMs)] : ['app-server', '--stdio'], {
+        cwd: spec.cwd,
+        env: { ...process.env, ...spec.env },
+        stdio: posix ? ['pipe', 'pipe', 'pipe', 'ipc'] : ['pipe', 'pipe', 'pipe'],
+        detached: posix,
+        windowsHide: true,
+    });
+    let actualPid = posix ? null : proc.pid ?? null;
+    let actualExit;
+    let stdoutEnded = false;
+    let drainTimer;
+    let outputIncomplete = false;
+    let supervisorFailed = false;
+    let supervisorExit;
+    let spawnError = null;
+    let terminationRequested = false;
+    let completeActual;
+    let failActual;
+    const done = new Promise((resolve, reject) => {
+        completeActual = resolve;
+        failActual = reject;
+    });
+    done.catch(() => { });
+    proc.stdout.once('end', () => {
+        stdoutEnded = true;
+        if (drainTimer !== undefined)
+            clearTimeout(drainTimer);
+        drainTimer = undefined;
+        if (actualExit !== undefined)
+            completeActual(actualExit);
+        else if (supervisorFailed || supervisorExit !== undefined) {
+            failActual(new CodexRunFailure({ stage: 'supervisor', category: 'process' }));
+        }
+    });
+    proc.on('message', (message) => {
+        if (message === null || typeof message !== 'object')
+            return;
+        const value = message;
+        if (value.type === 'started' && Number.isSafeInteger(value.pid) && Number(value.pid) > 0) {
+            actualPid = Number(value.pid);
+        }
+        else if (value.type === 'exit') {
+            actualExit = {
+                exitCode: typeof value.exitCode === 'number' ? value.exitCode : null,
+                signal: typeof value.signal === 'string' ? value.signal : null,
+            };
+            if (stdoutEnded)
+                completeActual(actualExit);
+            else if (drainTimer === undefined) {
+                // IPC and stdout use different pipes. Drain already-written final
+                // frames before declaring an early exit, but never wait indefinitely
+                // for a descendant that inherited stdout (even with runTimeoutMs=0).
+                drainTimer = setTimeout(() => {
+                    outputIncomplete = true;
+                    failActual(new Error('app-server exited but its output did not drain within 1000 ms'));
+                }, EXIT_DRAIN_TIMEOUT_MS);
+                drainTimer.unref?.();
+            }
+        }
+        else if (value.type === 'spawn-error') {
+            spawnError = typeof value.message === 'string' ? value.message : 'app-server spawn failed';
+            failActual(new Error(spawnError));
+        }
+    });
+    const supervisorDone = new Promise((resolve) => {
+        proc.once('error', (error) => {
+            spawnError = error.message;
+            failActual(error);
+            resolve();
+        });
+        proc.once('exit', (exitCode, signal) => {
+            if (posix) {
+                supervisorExit = { exitCode, signal };
+                supervisorFailed ||= !terminationRequested;
+                // Guardian liveness cannot depend on stdio close: its Codex child may
+                // still hold the inherited pipe. Allow queued final IPC/stdout frames
+                // a bounded drain, then fail and let the caller terminate the group.
+                if (actualExit === undefined && drainTimer === undefined) {
+                    drainTimer = setTimeout(() => {
+                        outputIncomplete = !stdoutEnded;
+                        failActual(new CodexRunFailure({ stage: 'supervisor', category: 'process' }));
+                    }, EXIT_DRAIN_TIMEOUT_MS);
+                    drainTimer.unref?.();
+                }
+            }
+            else {
+                actualExit = { exitCode, signal };
+                if (stdoutEnded)
+                    completeActual(actualExit);
+                else if (drainTimer === undefined) {
+                    drainTimer = setTimeout(() => {
+                        outputIncomplete = true;
+                        failActual(new CodexRunFailure({ stage: 'process', category: 'output-incomplete' }));
+                    }, EXIT_DRAIN_TIMEOUT_MS);
+                    drainTimer.unref?.();
+                }
+            }
+            resolve();
+        });
+        proc.once('disconnect', () => {
+            if (!posix || terminationRequested)
+                return;
+            supervisorFailed = true;
+            if (actualExit !== undefined && stdoutEnded)
+                completeActual(actualExit);
+            else if (stdoutEnded)
+                failActual(new CodexRunFailure({ stage: 'supervisor', category: 'process' }));
+            else if (drainTimer === undefined) {
+                drainTimer = setTimeout(() => {
+                    outputIncomplete = !stdoutEnded;
+                    failActual(new CodexRunFailure({ stage: 'supervisor', category: 'process' }));
+                }, EXIT_DRAIN_TIMEOUT_MS);
+                drainTimer.unref?.();
+            }
+        });
+        proc.once('close', (exitCode, signal) => {
+            if (drainTimer !== undefined)
+                clearTimeout(drainTimer);
+            if (posix)
+                supervisorExit = { exitCode, signal };
+            else {
+                actualExit = { exitCode, signal };
+                completeActual(actualExit);
+            }
+            // A guardian exit is not an app-server exit. In particular, a group KILL
+            // can prevent the guardian from sending the actual child's final facts.
+            if (actualExit === undefined)
+                failActual(new Error('Codex guardian exited before an app-server exit receipt'));
+            resolve();
+        });
+    });
+    const groupPid = posix ? proc.pid : undefined;
+    let termination;
+    const signalErrors = [];
+    const groupState = () => {
+        if (groupPid !== undefined) {
+            try {
+                process.kill(-groupPid, 0);
+                return { alive: true };
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    return { alive: false };
+                return { alive: undefined, detail: `cannot inspect the owned process group: ${thrown(error).message}` };
+            }
+        }
+        return { alive: proc.exitCode === null && proc.signalCode === null };
+    };
+    const sendSignal = (signal) => {
+        terminationRequested = true;
+        try {
+            if (groupPid !== undefined)
+                process.kill(-groupPid, signal);
+            else
+                proc.kill(signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH') {
+                signalErrors.push(`${signal}: ${thrown(error).message}`);
+            }
+        }
+    };
+    const waitForExit = (timeoutMs) => new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+        supervisorDone.then(() => { clearTimeout(timer); resolve(true); });
+    });
+    const terminate = (grace) => {
+        if (termination !== undefined)
+            return termination;
+        termination = (async () => {
+            if (proc.pid === undefined)
+                return { confirmed: true };
+            sendSignal('SIGTERM');
+            await waitForExit(grace);
+            // A caller-requested guardian exit can happen before a descendant that
+            // inherited stdout has let the stream drain. Give the existing drain
+            // timer its bounded window before killing the group, so a held pipe is
+            // still reported as output-incomplete instead of being silently closed.
+            if (actualExit !== undefined && !stdoutEnded && !outputIncomplete) {
+                await delay(EXIT_DRAIN_TIMEOUT_MS);
+            }
+            if (groupState().alive !== false) {
+                sendSignal('SIGKILL');
+                await waitForExit(Math.min(Math.max(grace, 250), GROUP_REAP_TIMEOUT_MS));
+            }
+            const until = performance.now() + GROUP_REAP_TIMEOUT_MS;
+            let state = groupState();
+            while (state.alive !== false && performance.now() < until) {
+                await delay(25);
+                state = groupState();
+            }
+            // A signal can race the guardian's own group KILL. In particular, Darwin
+            // can return EPERM while a group contains only exiting/zombie members.
+            // That error is not proof of disappearance, but a later independent
+            // ESRCH is. Do not let a historical signal error override that proof.
+            if (state.alive === false)
+                return { confirmed: true };
+            return {
+                confirmed: false,
+                detail: [...signalErrors, state.detail ?? 'the owned process group was still alive after SIGKILL'].join('; '),
+            };
+        })();
+        return termination;
+    };
+    return {
+        proc, done, terminate, waitForExit,
+        outputIncomplete: () => outputIncomplete,
+        supervisorFailed: () => supervisorFailed,
+        releaseUnconfirmed: () => {
+            // A failed signal must not keep the caller alive forever through its
+            // own pipe/IPC references. Closing the lease lets the guardian make an
+            // independent cleanup attempt. This is not confirmation: the already
+            // failed receipt stays failed even if that later attempt succeeds.
+            try {
+                if (proc.connected)
+                    proc.disconnect();
+            }
+            catch { /* lease already closed */ }
+            for (const stream of [proc.stdin, proc.stdout, proc.stderr]) {
+                try {
+                    stream.destroy();
+                }
+                catch { /* already closed */ }
+            }
+            proc.unref();
+        },
+        facts: () => ({
+            pid: actualPid,
+            supervisorPid: posix ? proc.pid ?? null : null,
+            exitCode: actualExit?.exitCode ?? null,
+            signal: actualExit?.signal ?? null,
+            supervisorExitCode: supervisorExit?.exitCode ?? null,
+            supervisorSignal: supervisorExit?.signal ?? null,
+            terminationRequested,
+            spawnError,
+        }),
+    };
+}
+/** Build the argv, for diagnostics and tests. */
+export function codexAppServerArgv(command) {
+    return [command, 'app-server', '--stdio'];
+}
+/** Build one failure for an unpublished startup. */
+function startupFailure(stage, error, flags, cleanup) {
+    if (error instanceof CodexRunFailure) {
+        return new CodexRunFailure(error.facts, error.cause, cleanup);
+    }
+    const category = flags.timedOut
+        ? 'timeout'
+        : flags.callerAborted
+            ? 'aborted'
+            : stage === 'process'
+                ? 'process'
+                : 'protocol';
+    return new CodexRunFailure({ stage, category }, error, cleanup);
+}
+/**
+ * Start the app-server child and publish its one-shot run.
+ *
+ * Resolves only after initialization and thread creation/resume, so a failure
+ * before that point rejects with no run published. After publication the result
+ * never rejects; even a failed run carries its observed usage, images, thread,
+ * configuration, and cleanup report.
+ *
+ * @param prompt - the delegation's content blocks.
+ * @param spec - working directory, executable, permission mode, and choices.
+ * @param signal - caller cancellation.
+ * @returns the published run.
+ */
+export async function startCodexRun(prompt, spec, signal) {
+    const id = spec.runId ?? randomUUID();
+    const startedAt = Date.now();
+    const startedMonotonic = performance.now();
+    let timedOut = false;
+    let callerAborted = false;
+    let truncated = false;
+    let initialSpawnError = null;
+    let observedChild;
+    let observedWire;
+    const execution = (failure) => ({
+        runId: id,
+        dispatch: observedWire?.dispatch ?? 'not-dispatched',
+        startedAt: new Date(startedAt).toISOString(),
+        finishedAt: new Date().toISOString(),
+        durationMs: Math.max(0, performance.now() - startedMonotonic),
+        threadId: observedWire?.threadId ?? null,
+        turnId: observedWire?.turnId ?? null,
+        ...(observedChild?.facts() ?? {
+            pid: null, supervisorPid: null, exitCode: null, signal: null,
+            supervisorExitCode: null, supervisorSignal: null,
+            terminationRequested: false, spawnError: initialSpawnError,
+        }),
+        timedOut, cancelled: callerAborted || signal.aborted,
+        truncated: truncated || observedChild?.outputIncomplete() === true, failure,
+        ownership: process.platform === 'win32' ? 'owned-process' : 'supervised-group',
+    });
+    const graceMs = spec.disposeGraceMs ?? DEFAULT_DISPOSE_GRACE_MS;
+    const requestedTimeout = spec.runTimeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    const maxOutputBytes = spec.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    let texts;
+    try {
+        texts = textTask(prompt);
+        if (!Number.isSafeInteger(graceMs) || graceMs < 0 || graceMs > 30_000) {
+            throw new Error('disposeGraceMs must be an integer between 0 and 30000');
+        }
+        if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
+            throw new Error('maxOutputBytes must be a positive safe integer');
+        }
+        if (!Number.isSafeInteger(requestedTimeout) || requestedTimeout < 0 || requestedTimeout > MAX_TIMER_MS) {
+            throw new Error('runTimeoutMs must be an integer between 0 and 2147483647');
+        }
+        if (spec.deadlineAt !== undefined && (!Number.isSafeInteger(spec.deadlineAt) || spec.deadlineAt <= 0
+            || spec.deadlineAt - startedAt > MAX_TIMER_MS)) {
+            throw new Error('deadlineAt must be a positive safe timestamp within the supported timer range');
+        }
+    }
+    catch (error) {
+        const facts = { stage: 'request', category: 'invalid-request' };
+        throw new CodexRunFailure(facts, error, { confirmed: true }, { execution: execution(facts) });
+    }
+    if (signal.aborted) {
+        callerAborted = true;
+        const facts = { stage: 'initialize', category: 'aborted' };
+        throw new CodexRunFailure(facts, undefined, { confirmed: true }, { execution: execution(facts) });
+    }
+    const deadlineAt = spec.deadlineAt
+        ?? (requestedTimeout > 0 ? startedAt + requestedTimeout : undefined);
+    const timeoutDescriptionMs = deadlineAt === undefined ? requestedTimeout : Math.max(1, deadlineAt - startedAt);
+    let child;
+    try {
+        child = spawnAppServer(spec);
+        observedChild = child;
+    }
+    catch (error) {
+        initialSpawnError = thrown(error).message;
+        const facts = { stage: 'initialize', category: 'process' };
+        throw new CodexRunFailure(facts, error, { confirmed: true }, { execution: execution(facts) });
+    }
+    const runAbort = new AbortController();
+    let outputBytes = 0;
+    const limitOutput = (chunk) => {
+        outputBytes += typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.byteLength;
+        if (outputBytes <= maxOutputBytes || truncated)
+            return;
+        truncated = true;
+        runAbort.abort(new Error(`codex-pro: output exceeded ${String(maxOutputBytes)} bytes`));
+        child.proc.stdout.destroy();
+        child.proc.stderr.destroy();
+    };
+    child.proc.stdout.on('data', limitOutput);
+    child.proc.stderr.on('data', limitOutput);
+    const transport = new LineTransport(child.proc.stdin, child.proc.stdout);
+    const wire = new CodexAppServerWire(child.proc.stdout, child.proc.stdin, transport, {
+        permissionMode: spec.permissionMode,
+        model: spec.model,
+        threadMode: spec.threadMode,
+        originator: spec.originator ?? DEFAULT_ORIGINATOR,
+    });
+    observedWire = wire;
+    if (spec.onProgress !== undefined)
+        wire.setProgressReporter(spec.onProgress);
+    const forwardStderr = (chunk) => {
+        if (truncated)
+            return;
+        try {
+            process.stderr.write(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+        }
+        catch {
+            // Diagnostics must never take the run down.
+        }
+    };
+    child.proc.stderr.on('data', forwardStderr);
+    let timer;
+    const abortRun = () => {
+        if (runAbort.signal.aborted)
+            return;
+        runAbort.abort(new Error('codex-pro: run cancelled locally'));
+        wire.interrupt();
+    };
+    const requestCancel = () => {
+        callerAborted = true;
+        abortRun();
+    };
+    const onCallerAbort = () => {
+        requestCancel();
+    };
+    if (deadlineAt !== undefined) {
+        timer = setTimeout(() => {
+            timedOut = true;
+            abortRun();
+        }, Math.max(0, deadlineAt - Date.now()));
+        timer.unref?.();
+    }
+    signal.addEventListener('abort', onCallerAbort, { once: true });
+    // A signal that aborted between the pre-spawn check and this listener would
+    // otherwise never deliver its event; the run must still observe it.
+    if (signal.aborted)
+        onCallerAbort();
+    const teardown = async () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        wire.close();
+        try {
+            child.proc.stdin.end();
+        }
+        catch { /* already closed */ }
+        const cleanup = await child.terminate(graceMs);
+        if (!cleanup.confirmed)
+            child.releaseUnconfirmed();
+        signal.removeEventListener('abort', onCallerAbort);
+        child.proc.stderr.off('data', forwardStderr);
+        child.proc.stdout.off('data', limitOutput);
+        child.proc.stderr.off('data', limitOutput);
+        return cleanup;
+    };
+    let tornDown;
+    const teardownOnce = () => (tornDown ??= teardown());
+    let processFailureFacts;
+    const processFailure = child.done.then(() => {
+        processFailureFacts = { stage: 'process', category: 'process' };
+        throw new CodexRunFailure(processFailureFacts);
+    }, (error) => {
+        processFailureFacts = error instanceof CodexRunFailure ? error.facts : { stage: 'process', category: 'process' };
+        throw new CodexRunFailure(processFailureFacts, error);
+    });
+    processFailure.catch(() => { });
+    const lifecycle = spec.onLifecycle === undefined ? undefined : async (event) => {
+        await raceAbort(Promise.race([Promise.resolve().then(() => spec.onLifecycle({ event, runId: id,
+                threadId: wire.threadId ?? null, turnId: wire.turnId ?? null, configuration: wire.configuration ?? null })),
+            processFailure]), runAbort.signal);
+    };
+    let startupStage = 'initialize';
+    try {
+        await Promise.race([wire.initialize(runAbort.signal), processFailure]);
+        if (spec.resumeThreadId === undefined) {
+            startupStage = 'thread-start';
+            await Promise.race([wire.startThread(spec.cwd, runAbort.signal), processFailure]);
+        }
+        else {
+            startupStage = 'thread-resume';
+            const overrides = {
+                cwd: spec.cwd,
+                ...(spec.model === undefined ? {} : { model: spec.model }),
+                permission: spec.permissionMode,
+            };
+            await Promise.race([wire.resumeThread(spec.resumeThreadId, overrides, runAbort.signal), processFailure]);
+        }
+        // A persistent thread is named so the Codex application's list says where it
+        // came from; the id alone cannot, because the originator has to be the value
+        // that client filters on.
+        if (spec.threadMode === 'persistent' && spec.threadName !== undefined) {
+            startupStage = 'thread-name';
+            await Promise.race([wire.setThreadName(spec.threadName, runAbort.signal), processFailure]);
+        }
+        if (lifecycle !== undefined)
+            await lifecycle('thread-ready');
+    }
+    catch (error) {
+        const failureStage = processFailureFacts === undefined ? startupStage : 'process';
+        const cleanup = await teardownOnce();
+        const failure = startupFailure(failureStage, error, { timedOut, callerAborted }, cleanup);
+        const facts = truncated ? { stage: startupStage, category: 'output-limit' }
+            : child.outputIncomplete() ? { stage: startupStage, category: 'output-incomplete' }
+                : failure.facts;
+        throw new CodexRunFailure(facts, error, cleanup, {
+            execution: execution(facts), configuration: wire.configuration,
+            usage: partialUsage(wire.usageReport, 'startup ended without a completed turn'), rateLimits: wire.rateLimitsReport,
+            turnConfiguration: wire.turnConfiguration,
+        });
+    }
+    const finish = async (turn, error) => {
+        let failure = error instanceof CodexRunFailure
+            ? error.facts
+            : error === undefined ? null : { stage: 'turn', category: 'protocol' };
+        const cleanup = await teardownOnce();
+        callerAborted ||= signal.aborted;
+        const effectiveTruncated = truncated || child.outputIncomplete();
+        const usage = turn === undefined || timedOut || callerAborted || effectiveTruncated || !cleanup.confirmed
+            ? partialUsage(wire.usageReport, 'run ended without a reliable terminal usage boundary')
+            : wire.usageReport;
+        const rateLimits = wire.rateLimitsReport;
+        const configuration = wire.configuration;
+        const observedImages = turn?.images ?? wire.images;
+        let output = turn?.output ?? wire.partialOutput;
+        let stopReason = effectiveTruncated ? 'error'
+            : timedOut ? 'timeout'
+                : callerAborted ? 'aborted'
+                    : turn?.stopReason ?? 'error';
+        const approvalDiagnostic = wire.collectDiagnostic();
+        let diagnostic = approvalDiagnostic;
+        let structured;
+        let schemaError;
+        const processFacts = child.facts();
+        if (child.supervisorFailed()) {
+            if (stopReason === 'completed')
+                stopReason = 'error';
+            failure = { stage: 'supervisor', category: 'process' };
+            diagnostic = appendDiagnostic(diagnostic, 'Codex guardian exited before cleanup was requested');
+        }
+        if ((processFacts.exitCode !== null && processFacts.exitCode !== 0)
+            || (processFacts.signal !== null && !['SIGTERM', 'SIGKILL'].includes(processFacts.signal))) {
+            if (stopReason === 'completed')
+                stopReason = 'error';
+            failure = { stage: 'process', category: 'process' };
+            diagnostic = appendDiagnostic(diagnostic, `app-server exited unexpectedly (code=${String(processFacts.exitCode)}, signal=${String(processFacts.signal)})`);
+        }
+        if (spec.outputSchema !== undefined && stopReason === 'completed') {
+            const text = output.map((block) => block.text).join('\n\n');
+            const verification = verifyStructuredOutput(text, spec.outputSchema);
+            if (verification.ok) {
+                structured = verification.value;
+            }
+            else {
+                schemaError = verification.error;
+                // A schema was requested: an unparseable or invalid answer is not a
+                // structured success. Preserve the raw output and say why it failed.
+                if (stopReason === 'completed')
+                    stopReason = 'error';
+                failure = { stage: 'output', category: 'schema' };
+                diagnostic = diagnostic === undefined ? schemaError : `${diagnostic}; ${schemaError}`;
+            }
+        }
+        if (!cleanup.confirmed) {
+            if (stopReason === 'completed')
+                stopReason = 'error';
+            failure ??= { stage: 'cleanup', category: 'cleanup' };
+            const cleanupDetail = `process cleanup could not be confirmed${cleanup.detail === undefined ? '' : `: ${cleanup.detail}`}`;
+            diagnostic = diagnostic === undefined ? cleanupDetail : `${diagnostic}; ${cleanupDetail}`;
+        }
+        if (effectiveTruncated) {
+            if (truncated)
+                failure = { stage: 'output', category: 'output-limit' };
+            else
+                failure ??= { stage: 'output', category: 'output-incomplete' };
+            const detail = truncated
+                ? `codex-pro: output exceeded ${String(maxOutputBytes)} bytes and was truncated`
+                : 'codex-pro: app-server output could not be completely drained';
+            diagnostic = diagnostic === undefined ? detail : `${diagnostic}; ${detail}`;
+        }
+        else if (timedOut) {
+            failure = { stage: 'turn', category: 'timeout' };
+            const timeoutDetail = describeTimeout(timeoutDescriptionMs);
+            diagnostic = diagnostic === undefined ? timeoutDetail : `${diagnostic}; ${timeoutDetail}`;
+        }
+        else if (callerAborted) {
+            failure = { stage: 'turn', category: 'aborted' };
+            const abortDetail = 'codex-pro: the delegation was cancelled by its caller';
+            diagnostic = diagnostic === undefined ? abortDetail : `${diagnostic}; ${abortDetail}`;
+        }
+        else if (error !== undefined && diagnostic === undefined) {
+            diagnostic = error instanceof Error ? error.message : String(error);
+        }
+        else if (error !== undefined && !(error instanceof CodexRunFailure)) {
+            diagnostic = `${diagnostic}; ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (stopReason !== 'completed' && failure === null) {
+            failure = { stage: 'turn', category: stopReason };
+        }
+        return {
+            output,
+            stopReason,
+            ...(diagnostic === undefined ? {} : { diagnostic }),
+            ...(approvalDiagnostic === undefined ? {} : { approvalDiagnostic }),
+            threadId: wire.threadId,
+            images: observedImages,
+            usage,
+            rateLimits,
+            ...(configuration === undefined ? {} : { configuration }),
+            cleanup,
+            execution: execution(failure),
+            ...(wire.turnConfiguration === undefined ? {} : { turnConfiguration: wire.turnConfiguration }),
+            ...(structured === undefined ? {} : { structured }),
+            ...(schemaError === undefined ? {} : { schemaError }),
+        };
+    };
+    const result = (async () => {
+        try {
+            const turn = await Promise.race([
+                wire.runTurn(texts, runAbort.signal, spec.effort ?? spec.reasoningEffort, spec.images ?? [], spec.outputSchema, lifecycle),
+                processFailure,
+            ]);
+            return await finish(turn, undefined);
+        }
+        catch (error) {
+            return await finish(undefined, error);
+        }
+    })();
+    return {
+        id,
+        result,
+        requestCancel,
+        teardown: teardownOnce,
+    };
+}
+/**
+ * Decide which thread one call continues.
+ *
+ * `session` mode has one thread per Agent session, but a thread carries one turn
+ * at a time: two delegations sent together would otherwise both reach for it and
+ * the second would fail. A remembered thread that another delegation is already
+ * using is therefore skipped, and this call gets a thread of its own — which is
+ * what `persistent` does anyway, so parallel work degrades to the mode that
+ * supports it instead of failing and retrying.
+ *
+ * An id the caller passed explicitly is never skipped: continuing *that* thread
+ * was the request, and silently running somewhere else would answer a different
+ * question.
+ *
+ * @param input - the call's explicit id, the configured mode, the session's
+ * remembered thread, and the threads currently in flight.
+ * @returns the thread to continue and the remembered one that was busy.
+ */
+export function chooseThread(input) {
+    if (input.explicit !== undefined)
+        return { reuse: input.explicit, skippedBusy: undefined };
+    if (input.configured !== 'session' || input.remembered === undefined) {
+        return { reuse: undefined, skippedBusy: undefined };
+    }
+    if (input.inFlight.has(input.remembered)) {
+        return { reuse: undefined, skippedBusy: input.remembered };
+    }
+    return { reuse: input.remembered, skippedBusy: undefined };
+}
+/**
+ * A delegation that did not complete.
+ *
+ * Carries the thread, images, and (when publication reached the run) the whole
+ * outcome, so a caller can report observed usage even though the run failed.
+ */
+export class CodexDelegationFailure extends Error {
+    /** The thread the failed run used, when the app-server had got that far. */
+    threadId;
+    /** Images the failed run produced before it failed. */
+    images;
+    /** Everything observed about the failed run, when one was published. */
+    outcome;
+    constructor(message, threadId, images = [], outcome) {
+        super(message);
+        this.name = 'CodexDelegationFailure';
+        this.threadId = threadId;
+        this.images = images;
+        this.outcome = outcome;
+    }
+}
+/** Run one delegation and return its settled outcome. */
+export async function runCodexOnce(options) {
+    const run = await startCodexRun([{ type: 'text', text: options.prompt }], {
+        cwd: options.cwd,
+        command: options.command,
+        permissionMode: options.permissionMode,
+        model: options.model,
+        effort: options.reasoningEffort,
+        threadMode: options.threadMode,
+        resumeThreadId: options.threadId,
+        originator: options.originator,
+        runTimeoutMs: options.runTimeoutMs,
+        ...(options.deadlineAt === undefined ? {} : { deadlineAt: options.deadlineAt }),
+        images: options.images,
+        outputSchema: options.outputSchema,
+        threadName: options.threadName,
+        env: options.env,
+        disposeGraceMs: options.disposeGraceMs,
+        maxOutputBytes: options.maxOutputBytes,
+        onProgress: options.onProgress,
+    }, options.signal);
+    options.onStart?.(run.id);
+    try {
+        return await run.result;
+    }
+    finally {
+        await run.teardown();
+    }
+}
+/**
+ * Run one delegation to completion and return its final text.
+ *
+ * The result keeps the thread, images, usage, configuration and cleanup report
+ * available to callers that need to report more than the answer. A run that
+ * does not complete rejects with the whole outcome attached.
+ *
+ * @param options - the task, its working directory, and the choices.
+ * @returns the child's final message and its observability fields.
+ * @throws `CodexDelegationFailure` when the run does not complete.
+ */
+export async function delegateOnce(options) {
+    const outcome = await runCodexOnce(options);
+    const text = outcome.output.map((block) => block.text).join('\n\n');
+    if (outcome.stopReason !== 'completed'
+        || text === ''
+        || outcome.schemaError !== undefined
+        || !outcome.cleanup.confirmed) {
+        throw new CodexDelegationFailure(outcome.diagnostic ?? `codex-pro: the run ended as ${outcome.stopReason}`, outcome.threadId, outcome.images ?? [], outcome);
+    }
+    return {
+        text,
+        threadId: outcome.threadId,
+        images: outcome.images ?? [],
+        usage: outcome.usage,
+        rateLimits: outcome.rateLimits,
+        ...(outcome.configuration === undefined ? {} : { configuration: outcome.configuration }),
+        cleanup: outcome.cleanup,
+        execution: outcome.execution,
+        ...(outcome.turnConfiguration === undefined ? {} : { turnConfiguration: outcome.turnConfiguration }),
+        ...(outcome.structured === undefined ? {} : { structured: outcome.structured }),
+    };
+}
+//# sourceMappingURL=run.js.map