@excitedjs/agent-runtime-codex 0.2.0-alpha.g0ddd418597ca

package/dist/config.js

@@ -0,0 +1,106 @@
+/**
+ * Builtin `builtin:codex` runtime config: schema type, defaults, reader, and
+ * the typed accessor.
+ *
+ * Codex runtime config is owned by this package (the `builtin:codex` provider),
+ * not by the Dreamux host config module. It depends only on the shared neutral
+ * validation primitives (`@excitedjs/dreamux-utils`) and the package-local
+ * provider ref, never on `@excitedjs/dreamux` core. The Dreamux host config
+ * module re-exports these so
+ * the non-builtin callers (doctor, daemon, tests) keep their import paths.
+ */
+import { BUILTIN_CODEX_PROVIDER_REF } from './provider-ref.js';
+import { readOptionalString, rejectUnknownKeys, requirePositiveInt, requireStringArray, requireStringRecord, } from '@excitedjs/dreamux-utils';
+/**
+ * Default `dispatchers[].runtime.config.bin`. The Codex binary path is
+ * dispatcher-local; `CODEX_HOST_CODEX_BIN` is a host-level override above it,
+ * not the source.
+ */
+export const DEFAULT_CODEX_BIN = 'codex';
+/** Default `dispatchers[].runtime.config.initialize_timeout_ms` (handshake timeout, ms). */
+export const DEFAULT_INITIALIZE_TIMEOUT_MS = 10_000;
+/**
+ * Default per-turn deadline for a `builtin:codex` TeamMate worker (ms).
+ * Generous enough not to interrupt a legitimately long tool-using turn, but
+ * finite so a worker whose turn stalls after start cannot sit `running` with no
+ * visible outcome (issue #126). Operators override via
+ * `dispatchers[].runtime.config.turn_timeout_ms`.
+ */
+export const DEFAULT_CODEX_TURN_TIMEOUT_MS = 600_000;
+/** Default `dispatchers[].runtime.config.approval_policy` when omitted. */
+export const DEFAULT_APPROVAL_POLICY = 'never';
+/** Default `dispatchers[].runtime.config.sandbox_mode` when omitted. */
+export const DEFAULT_SANDBOX_MODE = 'workspace-write';
+export const ALLOWED_APPROVAL_POLICIES = new Set([
+    'never',
+    'auto',
+    'auto-approve',
+    'on-failure',
+]);
+export const ALLOWED_SANDBOX_MODES = new Set([
+    'read-only',
+    'workspace-write',
+    'danger-full-access',
+]);
+export function defaultDispatcherCodexConfig() {
+    return {
+        bin: DEFAULT_CODEX_BIN,
+        approval_policy: DEFAULT_APPROVAL_POLICY,
+        sandbox_mode: DEFAULT_SANDBOX_MODE,
+        extra_args: [],
+        extra_env: {},
+        initialize_timeout_ms: DEFAULT_INITIALIZE_TIMEOUT_MS,
+        turn_timeout_ms: DEFAULT_CODEX_TURN_TIMEOUT_MS,
+    };
+}
+export function readDispatcherCodexConfig(rawCodex, file, prefix) {
+    rejectUnknownKeys(rawCodex, new Set([
+        'bin',
+        'approval_policy',
+        'sandbox_mode',
+        'extra_args',
+        'extra_env',
+        'initialize_timeout_ms',
+        'turn_timeout_ms',
+    ]), file, prefix);
+    // An omitted (or explicitly null) field falls back to the dispatcher-local
+    // default. Before the top-level block was removed, `null` meant "inherit the
+    // global default"; with no global, it simply means "use the built-in".
+    const defaults = defaultDispatcherCodexConfig();
+    const bin = readOptionalString(rawCodex, 'bin', file, prefix) ?? defaults.bin;
+    if (bin.trim() === '') {
+        throw new Error(`dreamux config error in ${file}: ${prefix}bin must be a non-empty string`);
+    }
+    const approvalPolicy = readOptionalString(rawCodex, 'approval_policy', file, prefix) ??
+        defaults.approval_policy;
+    if (!ALLOWED_APPROVAL_POLICIES.has(approvalPolicy)) {
+        throw new Error(`dreamux config error in ${file}: ${prefix}approval_policy='${approvalPolicy}' is not one of ${Array.from(ALLOWED_APPROVAL_POLICIES).join(' | ')}`);
+    }
+    const sandboxMode = readOptionalString(rawCodex, 'sandbox_mode', file, prefix) ??
+        defaults.sandbox_mode;
+    if (!ALLOWED_SANDBOX_MODES.has(sandboxMode)) {
+        throw new Error(`dreamux config error in ${file}: ${prefix}sandbox_mode='${sandboxMode}' is not one of ${Array.from(ALLOWED_SANDBOX_MODES).join(' | ')}`);
+    }
+    return {
+        bin,
+        approval_policy: approvalPolicy,
+        sandbox_mode: sandboxMode,
+        extra_args: requireStringArray(rawCodex, 'extra_args', defaults.extra_args, file, prefix),
+        extra_env: requireStringRecord(rawCodex, 'extra_env', defaults.extra_env, file, prefix),
+        initialize_timeout_ms: requirePositiveInt(rawCodex, 'initialize_timeout_ms', defaults.initialize_timeout_ms, file, prefix),
+        turn_timeout_ms: requirePositiveInt(rawCodex, 'turn_timeout_ms', defaults.turn_timeout_ms, file, prefix),
+    };
+}
+/**
+ * Typed accessor for a dispatcher's resolved codex runtime config. Typed
+ * structurally (not against `DispatcherConfig`) so this module never imports
+ * the host config type — a full `DispatcherConfig` still satisfies it at the
+ * call sites.
+ */
+export function dispatcherCodexConfig(dispatcher) {
+    if (dispatcher.runtime.provider !== BUILTIN_CODEX_PROVIDER_REF) {
+        throw new Error(`dispatcher '${dispatcher.id}' runtime provider ${JSON.stringify(dispatcher.runtime.provider)} is not wired to Codex`);
+    }
+    return dispatcher.runtime.config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/diagnostic.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `builtin:codex` self-reported doctor surface (issue #146 fold; relocated
+ * into the owning package by the issue #209 cleanup).
+ *
+ * Declares the codex bin check (deduped + executed by Dreamux core's doctor) and
+ * runs the codex-home validation plus the codex version gate (#147) itself,
+ * entirely against the neutral `@excitedjs/dreamux-types` diagnostic context. The
+ * representative app-server socket sample is derived from the neutral path
+ * context's `runtimeSocketDirs()`, so the package never names `~/.dreamux`.
+ */
+import type { AgentRuntimeDiagnostic } from '@excitedjs/dreamux-types';
+import { type DispatcherCodexConfig } from './config.js';
+export declare const codexAgentRuntimeDiagnostic: AgentRuntimeDiagnostic<DispatcherCodexConfig>;
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.d.ts","sourceRoot":"","sources":["../src/diagnostic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAEV,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAkCzD,eAAO,MAAM,2BAA2B,EAAE,sBAAsB,CAAC,qBAAqB,CAiCnF,CAAC"}

package/dist/diagnostic.js

@@ -0,0 +1,58 @@
+import { codexArgsFromConfig, codexArgsToCli } from './args.js';
+import { dispatcherCodexHomeDoctorContext, validateDispatcherCodexHome, } from './codex-home.js';
+import { representativeCodexSocketPath } from './internal/socket.js';
+import { resolveCodexBinPath } from './bin.js';
+import { MIN_CODEX_VERSION, codexVersionSatisfies } from './version.js';
+function codexBinCheckName(scope) {
+    return scope === 'managedService' ? 'managed service Codex binary' : 'codex binary';
+}
+async function checkCodexVersion(context, runner) {
+    const bin = resolveCodexBinPath(context.config.bin, context.env);
+    let raw;
+    try {
+        raw = await runner.capture(bin, ['--version'], { env: context.env });
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        return `could not determine Codex version from ${bin}: ${cause}; requires codex >= ${MIN_CODEX_VERSION}`;
+    }
+    if (codexVersionSatisfies(raw))
+        return null;
+    return (`Codex at ${bin} reported ${raw.trim() || '<empty>'}; requires codex >= ` +
+        `${MIN_CODEX_VERSION} for teammate completion delivery (thread/inject_items)`);
+}
+export const codexAgentRuntimeDiagnostic = {
+    binChecks(context) {
+        return [
+            {
+                name: codexBinCheckName(context.scope),
+                bin: resolveCodexBinPath(context.config.bin, context.env),
+                args: ['--help'],
+            },
+        ];
+    },
+    async runDiagnostic(context, runner) {
+        const cliArgs = codexArgsToCli(codexArgsFromConfig(context.config));
+        const socketDirs = context.paths?.runtimeSocketDirs() ?? [];
+        const homeContext = dispatcherCodexHomeDoctorContext(context.runtime_id, {
+            codexCliArgs: cliArgs,
+            socketPath: representativeCodexSocketPath(socketDirs, context.runtime_id),
+        });
+        const home = await validateDispatcherCodexHome(homeContext, {
+            env: context.env,
+            codexCliArgs: cliArgs,
+        });
+        const errors = [...home.errors];
+        const versionError = await checkCodexVersion(context, runner);
+        if (versionError !== null)
+            errors.push(versionError);
+        // Detail mirrors the old printCodexHomeDoctor line (the codex home path);
+        // per-problem lines live in `errors`.
+        return {
+            ok: errors.length === 0,
+            detail: homeContext.codexHome,
+            errors,
+        };
+    },
+};
+//# sourceMappingURL=diagnostic.js.map

package/dist/diagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.js","sourceRoot":"","sources":["../src/diagnostic.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Collects a Codex turn from the JSON-RPC notification stream.
+ *
+ * Adapted from claudemux's `plugins/claudemux/core/src/engines/codex/events.ts`.
+ * We drop token-usage bookkeeping and `notLoaded` item merging. Feishu
+ * outbound delivery is MCP reply-only, so collected assistant text is for
+ * diagnostics and tests rather than channel forwarding.
+ */
+import type { CodexWsClient } from './rpc.js';
+import type { ThreadItem, TurnStartResponse } from './types.js';
+export interface CollectedTurn {
+    threadId: string;
+    turnId: string;
+    items: ThreadItem[];
+}
+export interface TurnCollector {
+    awaitTurn(turnId?: string): Promise<CollectedTurn>;
+}
+/**
+ * One observed Codex notification, redacted to method + ids + item type — never
+ * prompt/assistant text. Emitted to {@link TurnSubscriptionOptions.onTrace} for
+ * every notification so a caller can see what Codex emitted after `turn/start`
+ * (issue #126 PR8): the dispatcher never awaits completion, so the worker is the
+ * only consumer of this stream, and an empty/abnormal trace is the diagnostic
+ * that distinguishes an environment stall (auth/network/quota) from a missed
+ * terminal event.
+ */
+export interface TurnTraceEvent {
+    method: string;
+    /** `params.threadId` if present, else null (reveals a field-shape mismatch). */
+    threadId: string | null;
+    turnId: string | null;
+    /** `item.type` for `item/completed`; never the item text. */
+    itemType: string | null;
+    /** Whether this notification counted toward THIS subscription's thread. */
+    matched: boolean;
+}
+export interface TurnSubscriptionOptions {
+    /**
+     * Accept `turn/completed` / `item/completed` even when the notification's
+     * `threadId` field does not match. A per-task worker app-server hosts exactly
+     * one thread, so any completion on its socket IS this task's completion;
+     * leniency makes the worker robust to a `threadId` field-shape drift in the
+     * Codex protocol that the strict dispatcher path never exercises. Default
+     * false preserves the strict, thread-scoped dispatcher behaviour.
+     */
+    acceptAnyThread?: boolean;
+    /** Diagnostic hook fired for EVERY notification, before any filtering. */
+    onTrace?: (event: TurnTraceEvent) => void;
+}
+/**
+ * Subscribe to turn notifications for one thread. Returns a collector whose
+ * `awaitTurn()` resolves on `turn/completed` and REJECTS on a terminal turn
+ * failure — either an `error` notification with `willRetry === false` (a fatal
+ * error that interrupts the turn; codex emits no `turn/completed` after it, so a
+ * resolve-only collector would hang forever) or a `turn/completed` carrying a
+ * `turn.error`. Items arriving on the parallel `item/completed` stream are
+ * buffered and merged into the resolved turn.
+ */
+export declare function subscribeTurnCollection(client: CodexWsClient, threadId: string, options?: TurnSubscriptionOptions): TurnCollector;
+/**
+ * Append raw Responses API items to a thread's model-visible history without
+ * starting a turn (`thread/inject_items`, codex 0.137+). codex folds the items
+ * onto the active turn when one is running and otherwise records them against a
+ * default turn context (codex_thread.rs `inject_response_items` →
+ * `inject_no_new_turn`); either way it never rejects on a busy thread, so a
+ * rejection here is a genuine RPC error. Persisted to the rollout, so injected
+ * items survive resume.
+ */
+export declare function injectThreadItems(client: CodexWsClient, threadId: string, items: ReadonlyArray<Record<string, unknown>>): Promise<void>;
+/**
+ * Send a `turn/start` request and resolve once Codex accepts the submission.
+ * This is the production Feishu inbound primitive: it intentionally does not
+ * wait for `turn/completed`.
+ */
+export declare function submitTurnStart(client: CodexWsClient, threadId: string, prompt: string, cwd: string | null): Promise<TurnStartResponse>;
+/**
+ * Send a `turn/start` request and await `turn/completed`.
+ * Returns the collected turn, or throws on RPC failure.
+ */
+export declare function runTurn(client: CodexWsClient, threadId: string, prompt: string, cwd: string | null): Promise<CollectedTurn>;
+/**
+ * Extract the final assistant message text from a collected turn.
+ * Returns null if the turn had no assistant message — caller decides
+ * what to surface to the user (see issue #2 §"开放问题 Q4").
+ */
+export declare function extractAssistantText(turn: CollectedTurn): string | null;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAEV,UAAU,EAGV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,GACpC,aAAa,CAyJf;AAaD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAQ5B;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,OAAO,CAAC,aAAa,CAAC,CAIxB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAOvE"}

package/dist/events.js

@@ -0,0 +1,225 @@
+/**
+ * Collects a Codex turn from the JSON-RPC notification stream.
+ *
+ * Adapted from claudemux's `plugins/claudemux/core/src/engines/codex/events.ts`.
+ * We drop token-usage bookkeeping and `notLoaded` item merging. Feishu
+ * outbound delivery is MCP reply-only, so collected assistant text is for
+ * diagnostics and tests rather than channel forwarding.
+ */
+/**
+ * Subscribe to turn notifications for one thread. Returns a collector whose
+ * `awaitTurn()` resolves on `turn/completed` and REJECTS on a terminal turn
+ * failure — either an `error` notification with `willRetry === false` (a fatal
+ * error that interrupts the turn; codex emits no `turn/completed` after it, so a
+ * resolve-only collector would hang forever) or a `turn/completed` carrying a
+ * `turn.error`. Items arriving on the parallel `item/completed` stream are
+ * buffered and merged into the resolved turn.
+ */
+export function subscribeTurnCollection(client, threadId, options = {}) {
+    const acceptAnyThread = options.acceptAnyThread === true;
+    const itemsByTurn = new Map();
+    const completedByTurn = new Map();
+    const failuresByTurn = new Map();
+    let firstCompleted = null;
+    let firstFailure = null;
+    let unscopedFailure = null;
+    let closed = false;
+    let awaiting = null;
+    const closeCollector = () => {
+        closed = true;
+        itemsByTurn.clear();
+    };
+    const resolveAwaiting = () => {
+        if (awaiting === null)
+            return;
+        const expectedTurnId = awaiting.turnId;
+        if (unscopedFailure !== null) {
+            awaiting.reject(unscopedFailure);
+            awaiting = null;
+            closeCollector();
+            return;
+        }
+        if (expectedTurnId !== null) {
+            const failure = failuresByTurn.get(expectedTurnId);
+            if (failure !== undefined) {
+                awaiting.reject(failure);
+                awaiting = null;
+                closeCollector();
+                return;
+            }
+            const completed = completedByTurn.get(expectedTurnId);
+            if (completed !== undefined) {
+                awaiting.resolve(completed);
+                awaiting = null;
+                closeCollector();
+            }
+            return;
+        }
+        if (firstFailure !== null) {
+            awaiting.reject(firstFailure);
+            awaiting = null;
+            closeCollector();
+            return;
+        }
+        if (firstCompleted !== null) {
+            awaiting.resolve(firstCompleted);
+            awaiting = null;
+            closeCollector();
+        }
+    };
+    client.onNotification((notif) => {
+        const p = (notif.params ?? {});
+        const nThreadId = typeof p['threadId'] === 'string' ? p['threadId'] : null;
+        const matches = acceptAnyThread || nThreadId === threadId;
+        if (options.onTrace !== undefined) {
+            options.onTrace({
+                method: notif.method,
+                threadId: nThreadId,
+                turnId: traceTurnId(p),
+                itemType: traceItemType(p),
+                matched: matches,
+            });
+        }
+        if (closed || !matches)
+            return;
+        if (notif.method === 'item/completed') {
+            const params = notif.params;
+            const bucket = itemsByTurn.get(params.turnId) ?? [];
+            bucket.push(params.item);
+            itemsByTurn.set(params.turnId, bucket);
+        }
+        else if (notif.method === 'turn/completed') {
+            const params = notif.params;
+            if (params.turn.error != null) {
+                const failure = new Error(params.turn.error.message || 'codex turn failed');
+                failuresByTurn.set(params.turn.id, failure);
+                firstFailure ??= failure;
+                resolveAwaiting();
+                return;
+            }
+            const items = itemsByTurn.get(params.turn.id) ?? params.turn.items ?? [];
+            const completed = { threadId, turnId: params.turn.id, items };
+            completedByTurn.set(params.turn.id, completed);
+            firstCompleted ??= completed;
+            resolveAwaiting();
+        }
+        else if (notif.method === 'error') {
+            const params = notif.params;
+            // Only a fatal (non-retried) error terminates the turn. A transient
+            // `willRetry: true` error is followed by codex's own retry and an
+            // eventual `turn/completed`, so we ignore it here.
+            if (params.willRetry === false) {
+                const failure = new Error(params.error?.message ?? 'codex turn error');
+                if (typeof params.turnId === 'string')
+                    failuresByTurn.set(params.turnId, failure);
+                else
+                    unscopedFailure = failure;
+                firstFailure ??= failure;
+                resolveAwaiting();
+            }
+        }
+    });
+    return {
+        awaitTurn(turnId) {
+            const expectedTurnId = turnId ?? null;
+            if (unscopedFailure !== null) {
+                closeCollector();
+                return Promise.reject(unscopedFailure);
+            }
+            if (expectedTurnId !== null) {
+                const failure = failuresByTurn.get(expectedTurnId);
+                if (failure !== undefined) {
+                    closeCollector();
+                    return Promise.reject(failure);
+                }
+                const completed = completedByTurn.get(expectedTurnId);
+                if (completed !== undefined) {
+                    closeCollector();
+                    return Promise.resolve(completed);
+                }
+            }
+            else {
+                if (firstFailure !== null) {
+                    closeCollector();
+                    return Promise.reject(firstFailure);
+                }
+                if (firstCompleted !== null) {
+                    closeCollector();
+                    return Promise.resolve(firstCompleted);
+                }
+            }
+            if (awaiting !== null)
+                return awaiting.promise;
+            let resolveTurn;
+            let rejectTurn;
+            const promise = new Promise((res, rej) => {
+                resolveTurn = res;
+                rejectTurn = rej;
+            });
+            awaiting = {
+                turnId: expectedTurnId,
+                promise,
+                resolve: resolveTurn,
+                reject: rejectTurn,
+            };
+            return promise;
+        },
+    };
+}
+function traceTurnId(params) {
+    if (typeof params['turnId'] === 'string')
+        return params['turnId'];
+    const turn = params['turn'];
+    return turn !== undefined && typeof turn.id === 'string' ? turn.id : null;
+}
+function traceItemType(params) {
+    const item = params['item'];
+    return item !== undefined && typeof item.type === 'string' ? item.type : null;
+}
+/**
+ * Append raw Responses API items to a thread's model-visible history without
+ * starting a turn (`thread/inject_items`, codex 0.137+). codex folds the items
+ * onto the active turn when one is running and otherwise records them against a
+ * default turn context (codex_thread.rs `inject_response_items` →
+ * `inject_no_new_turn`); either way it never rejects on a busy thread, so a
+ * rejection here is a genuine RPC error. Persisted to the rollout, so injected
+ * items survive resume.
+ */
+export async function injectThreadItems(client, threadId, items) {
+    await client.request('thread/inject_items', { threadId, items });
+}
+/**
+ * Send a `turn/start` request and resolve once Codex accepts the submission.
+ * This is the production Feishu inbound primitive: it intentionally does not
+ * wait for `turn/completed`.
+ */
+export async function submitTurnStart(client, threadId, prompt, cwd) {
+    const input = [
+        { type: 'text', text: prompt, text_elements: [] },
+    ];
+    return client.request('turn/start', cwd === null ? { threadId, input } : { threadId, input, cwd });
+}
+/**
+ * Send a `turn/start` request and await `turn/completed`.
+ * Returns the collected turn, or throws on RPC failure.
+ */
+export async function runTurn(client, threadId, prompt, cwd) {
+    const collector = subscribeTurnCollection(client, threadId);
+    const res = await submitTurnStart(client, threadId, prompt, cwd);
+    return collector.awaitTurn(res.turn.id);
+}
+/**
+ * Extract the final assistant message text from a collected turn.
+ * Returns null if the turn had no assistant message — caller decides
+ * what to surface to the user (see issue #2 §"开放问题 Q4").
+ */
+export function extractAssistantText(turn) {
+    const messages = turn.items.filter((it) => it.type === 'agentMessage');
+    if (messages.length === 0)
+        return null;
+    const last = messages[messages.length - 1];
+    return typeof last?.text === 'string' && last.text.length > 0
+        ? last.text
+        : null;
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/handshake.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Codex app-server LSP-style init handshake (required by codex 0.134+).
+ *
+ * Without this, every business RPC (`thread/start`, `turn/start`, …) is
+ * answered with `Not initialized` and the daemon never moves. The sequence
+ * is the canonical LSP one:
+ *
+ *   1. client → `initialize` request with ClientInfo + capabilities
+ *   2. server → InitializeResponse (userAgent, codexHome, platform info)
+ *   3. client → `initialized` notification (no params)
+ *
+ * Steps 1 + 3 are both required: codex's `Not initialized` guard is cleared
+ * only once the notification arrives. Capabilities can be omitted (the spec
+ * accepts `null`) — we pass an explicit default so the negotiation choices
+ * are visible in the source.
+ */
+import type { CodexWsClient } from './rpc.js';
+import type { ClientInfo, InitializeCapabilities, InitializeResponse } from './types.js';
+export interface HandshakeOptions {
+    clientInfo?: ClientInfo;
+    capabilities?: InitializeCapabilities | null;
+    /**
+     * Hard ceiling on how long to wait for the daemon's InitializeResponse
+     * before failing the handshake. Without this, a codex that accepts the
+     * WebSocket upgrade but never replies (hang, crash mid-response, wrong
+     * protocol version, …) would deadlock dispatcher startup indefinitely,
+     * blocking both server boot and any retry path. Default: 10_000 ms,
+     * which matches the spawn-readiness budget in CodexProcess.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Drive the full `initialize` + `initialized` exchange. Returns the
+ * server's InitializeResponse (userAgent, codexHome, platform) so callers
+ * can log it or surface it via admin.
+ *
+ * Times out (rejects) if the daemon does not reply within
+ * `options.timeoutMs`. The pending request stays in the client's `pending`
+ * map after timeout — callers that recover by tearing down the client
+ * (e.g. CodexRuntime's cleanupOnFailure) will then drop those
+ * pending entries when the WS connection closes.
+ */
+export declare function performInitializeHandshake(client: CodexWsClient, options?: HandshakeOptions): Promise<InitializeResponse>;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EACV,UAAU,EACV,sBAAsB,EAEtB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAuBpB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAmB7B"}