@khorsheed/dsh-local-agent-codex 0.1.0-rc.6

package/lib/types/codex-cli-provider.d.ts

@@ -0,0 +1,347 @@
+/**
+ * One-shot Codex CLI subagent lifecycle: spawn `codex exec "<task>"` through
+ * the subprocess seam under the harness's scoped home, capture its printed
+ * response as the run output, and dispose to whole-tree quiescence. Mirrors
+ * the kimi-cli provider: every accepted run is a fresh process and a fresh
+ * codex session; there is no continuation across runs.
+ *
+ * The provider name `codex-local` avoids colliding with the official
+ * `subagent-codex` package's provider name `codex` — a composition that
+ * mounts both would fail loud with DUPLICATE_PROVIDER. The tool row in this
+ * bundle's patch takes the official model-facing name `subagent_codex`
+ * instead: the official preset row ships disabled, and the patch disables
+ * it too (a deliberate user re-enable conflicts loud, by design).
+ * @module @khorsheed/dsh-local-agent-codex/codex-cli-provider
+ */
+import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import { type ResolvedSubagentStartRequest, type SubagentCapabilities, type SubagentProvider, type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { DelegationExecTarget, LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
+import type { CodexLiveDriver } from './live-driver.ts';
+/** Default POSIX grace between subprocess termination tiers. */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/**
+ * Auth-shaped failure signatures in codex's stderr or event stream: the
+ * endpoint rejected the credential. Narrow on purpose — matched against
+ * provider-controlled error output only.
+ */
+export declare const CODEX_AUTH_FAILURE: RegExp;
+/** Codex sandbox policy values accepted by `codex exec --sandbox`. */
+export type CodexSandbox = 'read-only' | 'workspace-write' | 'danger-full-access';
+/**
+ * Member channel registration for one codex process lifetime: mint the
+ * per-run token and build the bridge MCP declaration as a per-process `-c`
+ * config override (codex takes inline TOML — spike-verified end-to-end
+ * against the real CLI on 2026-08-20, including the model-call leg).
+ * `default_tools_approval_mode="approve"` is required: codex's stable MCP
+ * elicitation gate auto-cancels tools lacking a readOnlyHint in
+ * non-interactive mode ("user cancelled MCP tool call"), and the bridge's
+ * member_message is a write tool. Nothing is written to the scoped home, so
+ * there is nothing to prune at settle; `release` only invalidates the token.
+ * Returns undefined when the mounted core predates the member channel
+ * (declare-and-degrade: the run proceeds unchanged). Token-only auth: host
+ * 0.1.5 removed the child pid the parentage cross-check used; the per-run
+ * token is the sole credential (see the package README's threat model). The
+ * exec driver registers per round; the live driver registers per resident
+ * process and releases on reclaim.
+ */
+export interface CodexMemberRunHandle {
+    readonly token: string;
+    readonly configOverride: string;
+    release(): void;
+}
+/** Register one member run with the channel; see {@link CodexMemberRunHandle}. */
+export declare function registerCodexMemberRun(ctx: Context, childSessionId: string, parentSessionId: string): CodexMemberRunHandle | undefined;
+/**
+ * The codex build `codex --version` reports, probed through the shared
+ * subprocess seam inside the SCOPED home (never the user's own installation)
+ * and cached by the family probe against the executable's identity. Both the
+ * effective-settings snapshot and a settled round's read-back use it — the
+ * round prefers its own rollout head, which names the build that actually ran.
+ * @param ctx - host context carrying the subprocess seam.
+ * @param homeDir - the harness's scoped home.
+ * @returns the version, or undefined when the CLI cannot be asked.
+ */
+export declare function codexCliVersion(ctx: Context, homeDir: string): Promise<string | undefined>;
+export declare class CodexCliProvider implements SubagentProvider {
+    private readonly ctx;
+    private readonly sandbox;
+    private readonly live?;
+    private readonly model?;
+    private readonly overrides?;
+    readonly name = "codex-local";
+    readonly capabilities: SubagentCapabilities;
+    readonly inheritsParentContext = false;
+    /**
+     * @param live - the live driver, or a resolver returning the current
+     *   generation's driver per member (the settings toggle swaps generations;
+     *   a resolver may return undefined to steer one member's round to exec
+     *   while a retiring generation still hosts it).
+     * @param model - resolver for the configured model, read PER ROUND so a
+     *   settings-card write takes effect on the next delegation without a
+     *   reload. Undefined (the resolver absent, or returning undefined) leaves
+     *   the argv exactly as it was before the key existed — the scoped
+     *   config.toml's own `model` then decides, as it always did.
+     * @param overrides - resolver for the member's session-level model override
+     *   (the composer picker, owned by the model broker). It outranks BOTH the
+     *   delegation's recorded model and the configured one: on the exec path it
+     *   re-points the next round's `-m`, and on the live path it is the member's
+     *   start model — a resident runtime bound to a different model is retired
+     *   so the round respawns onto the override.
+     */
+    constructor(ctx: Context, sandbox?: CodexSandbox, live?: CodexLiveDriver | ((childSessionId: string) => CodexLiveDriver | undefined) | undefined, model?: (() => string | undefined) | undefined, overrides?: ((childSessionId: string) => string | undefined) | undefined);
+    /** Resolve the live driver for one round's member, if live is on for it. */
+    private liveDriver;
+    /** Per-round member-channel registration for the exec path (see {@link registerCodexMemberRun}). */
+    private memberRun;
+    start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;
+    /** Fresh round: record the child session, spawn `codex exec`, append after settle. */
+    private startCodexFresh;
+    /** Resume round: continue the recorded thread inside the existing child session. */
+    private startCodexResume;
+}
+/** Fully resolved inputs for one Codex CLI run. */
+export interface CodexCliRunSpec {
+    /** Parent Session workspace; also the codex process cwd. */
+    readonly cwd: string;
+    /** Explicit environment layered after the shared credential scrub. */
+    readonly env: Readonly<NodeJS.ProcessEnv>;
+    /**
+     * Run the CLI inside this container instead of on the host: the argv below
+     * is wrapped in `docker exec` and {@link env} is forwarded through NAME-only
+     * `-e` flags. Absent means the host spawn, unchanged.
+     */
+    readonly exec?: DelegationExecTarget | undefined;
+    /** Resolved endpoint label for diagnostics; absent means the CLI default. */
+    readonly endpointLabel?: string | undefined;
+    /** Sandbox policy passed to `codex exec --sandbox`. */
+    readonly sandbox: CodexSandbox;
+    /**
+     * Model this round runs with, passed as `codex exec -m <model>`. Absent
+     * means no `-m` on the argv at all: the scoped `config.toml`'s own `model`
+     * (or, with none, codex's built-in default) decides, exactly as before the
+     * key existed.
+     */
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+    /** Subprocess termination grace passed to the shared process-tree owner. */
+    readonly disposeGraceMs: number;
+    /** Shared subprocess service spawn operation. */
+    readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
+    /** Diagnostic sink for a post-publication error flattened into a result. */
+    readonly onError?: (error: Error, stopReason: SubagentStopReason) => void;
+    /**
+     * Called when the settled failure is auth-shaped (the endpoint rejected the
+     * credential — a 401 a presence probe cannot see). The provider wires this
+     * to the family registry's auth-failure mark.
+     */
+    readonly onAuthFailure?: ((detail: string) => void) | undefined;
+    /**
+     * Called when the round SETTLED COMPLETED — the CLI reached its endpoint and
+     * produced an answer, which is the only evidence a host has that the scoped
+     * credential is live. The provider wires this to the family registry's
+     * auth-success mark (the `verified` credential grade).
+     */
+    readonly onAuthSuccess?: (() => void) | undefined;
+    /**
+     * The codex build the executable reports, resolved lazily and cached by the
+     * family probe. Only consulted when the round's own rollout head named none.
+     */
+    readonly cliVersion?: (() => Promise<string | undefined>) | undefined;
+    /**
+     * Member channel: the bridge MCP declaration for this run as one `-c`
+     * inline-TOML config override (per-process; nothing lands in the scoped
+     * config.toml). Absent on a core that predates the member channel — the
+     * argv is then exactly the pre-channel shape.
+     */
+    readonly member?: {
+        readonly configOverride: string;
+    } | undefined;
+    /** dsh subagent session recording this delegation; its response is appended after settle. */
+    readonly childSession?: Session | undefined;
+    /** Host context carrying session persistence. */
+    readonly ctx?: Context | undefined;
+    /**
+     * Resume round: continue the thread named by `cliSessionId` with
+     * `codex exec --json resume <thread_id>` instead of a fresh exec, appending
+     * this round into the same child session under the given turn number.
+     */
+    readonly resume?: {
+        readonly cliSessionId: string;
+        readonly turn: number;
+    } | undefined;
+    /**
+     * Called after the run settles with the thread id parsed from the NDJSON
+     * stream (absent when none was reported). The fresh path uses it to record
+     * the delegation so a later resume round can continue the thread.
+     */
+    readonly onThreadId?: ((threadId: string | undefined) => void) | undefined;
+    /**
+     * Called once per settled round, after the output stream has been fully
+     * parsed and mirrored: the round's observed model identifier and token
+     * usage, each absent when the stream (and the rollout fallback) yielded
+     * none. The provider wires this to the registry's observation channel
+     * (`recordRoundSettled` — the delegation record's `observedModel` merge and
+     * the `settled` run-progress event). Fires for fresh and resume rounds
+     * alike, on every terminal state.
+     */
+    readonly onRoundSettled?: ((round: {
+        readonly observedModel?: string;
+        readonly usage?: TokenUsage;
+        readonly toolCalls?: LocalAgentToolCalls;
+    }) => void) | undefined;
+}
+/**
+ * Validate and join the one-shot task before crossing the process boundary.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the joined non-empty text.
+ */
+export declare function textTask(prompt: readonly ContentBlock[]): string;
+/** One ordered transcript line from a `codex exec --json` event stream. */
+export type CodexTranscriptLine = 
+/**
+ * Reasoning or reply text. `itemId` (live app-server rounds only) pairs the
+ * line with its delta stream, so the completed item folds at the step its
+ * snapshots reserved.
+ */
+{
+    kind: 'think';
+    text: string;
+    itemId?: string;
+} | {
+    kind: 'text';
+    text: string;
+    itemId?: string;
+}
+/**
+ * Tool activity: one call with its (possibly absent) result. `id` is the
+ * stream item's id when present, else a synthesized position-based id —
+ * stable within a run either way, so the child session's
+ * `tool/call`/`tool/result` events pair by it.
+ */
+ | {
+    kind: 'tool';
+    id: string;
+    name: string;
+    args?: string;
+    result?: string;
+};
+/** Mutable fold state shared by the batch parse and the incremental parser. */
+interface CodexStreamFoldState {
+    readonly lines: CodexTranscriptLine[];
+    text: string | undefined;
+    usage: TokenUsage | undefined;
+    threadId: string | undefined;
+    /**
+     * The model identifier the stream itself named (a `model` field on
+     * `thread.started` or `turn.completed`), when the CLI emits one. codex
+     * 0.144.0's exec stream carries none — the model then comes from the
+     * rollout's turn_context at settle — but the fold accepts it so a CLI that
+     * starts naming the model in the stream needs no parser change.
+     */
+    model: string | undefined;
+    /** Whether the stream's terminal `turn.completed` event was folded. */
+    completed: boolean;
+    /**
+     * Tool calls this stream made, keyed by codex's OWN item type
+     * (`command_execution`, `web_search_call`) — not the display names the
+     * transcript lines carry (`Bash`, `WebSearch`), because the accounting
+     * reports what the CLI called the thing. Counted in the same branches that
+     * already fold the item, so no event is parsed twice and none is parsed
+     * that was not parsed before. `function_call_output` is a RESULT and never
+     * counts: it merges into the call that preceded it.
+     */
+    readonly toolCalls: Map<string, number>;
+}
+/**
+ * Fold a tool-call counter into the settled shape: `{count, byName}` with the
+ * per-name values summing to `count`. An empty map yields undefined — a
+ * stream that named no tool call reports nothing rather than a zero it did
+ * not observe.
+ * @param counts - the fold's per-name tally.
+ * @returns the settled accounting, or undefined when nothing was counted.
+ */
+export declare function toolCallsOf(counts: ReadonlyMap<string, number>): LocalAgentToolCalls | undefined;
+/**
+ * Incremental `codex exec --json` parser: feed stdout chunks as they arrive
+ * and the folded transcript accumulates line by line. The last line is
+ * volatile until the terminal `turn.completed` — a `function_call_output`
+ * merges into a pending tool line — so live consumers hold it back (see the
+ * run's live mirror).
+ */
+export declare class CodexStreamParser implements CodexStreamFoldState {
+    private buffer;
+    readonly lines: CodexTranscriptLine[];
+    text: string | undefined;
+    usage: TokenUsage | undefined;
+    threadId: string | undefined;
+    model: string | undefined;
+    completed: boolean;
+    readonly toolCalls: Map<string, number>;
+    /** Fold every complete NDJSON line in the chunk; the tail stays buffered. */
+    push(chunk: string): void;
+}
+/**
+ * Parse a `codex exec --json` NDJSON event stream into an ordered transcript
+ * (thinking, agent text, tool/command activity in event order), plus the final
+ * answer text, token usage, the thread id a later resume round continues, and
+ * the model identifier the stream named (usually absent — codex 0.144.0 does
+ * not put one on the wire; the settle path then reads the rollout's
+ * turn_context). Item types covered: `reasoning` (thinking), `agent_message`
+ * (reply text), `command_execution` (shell command with aggregated output),
+ * `web_search_call`, and `function_call_output`. The last `agent_message`
+ * wins as the run output (the final answer), and `turn.completed` carries the
+ * turn's usage. Malformed lines are skipped.
+ * @param stream - the collected stdout NDJSON text.
+ * @returns the ordered transcript, final answer text, usage, thread id, and
+ *   any stream-named model.
+ */
+export declare function parseCodexJsonStream(stream: string): {
+    lines: readonly CodexTranscriptLine[];
+    text?: string;
+    usage?: TokenUsage;
+    threadId?: string;
+    model?: string;
+    toolCalls?: LocalAgentToolCalls;
+};
+/**
+ * Start the real `codex exec` child and publish its run. The codex
+ * reply arrives as an NDJSON event stream on stdout (`--json`): the final
+ * `agent_message` item is the run output and the `turn.completed` usage is
+ * the token accounting. stderr is piped for diagnostics and never folded
+ * into the run output. A resume round spawns `codex exec --json resume
+ * <thread_id>` instead, continuing the same thread. The run id is the child
+ * session id for a session-backed run.
+ * @param request - resolved shared subagent request.
+ * @param spec - workspace, environment, process service, and diagnostic policy.
+ * @returns the published run after the child starts.
+ */
+export declare function startCodexCliRun(request: SubagentStartRequest, spec: CodexCliRunSpec): Promise<SubagentRun>;
+/** One assistant-role message event, attributed to the codex route. */
+export declare function codexAssistantEvent(blocks: readonly ContentBlock[]): import("@deepseek-ai/dsh-llm").AssistantMessage;
+/**
+ * Fold one transcript line into the child session as one assistant step,
+ * wrapped in the step/start–step/end boundary pair the live conversation
+ * assembler requires: without a boundary the step never enters the location
+ * index, the line's assistant message resolves to a turn-level location, and
+ * the real-time view renders nothing (only a full rebuild, which mints step
+ * drafts from the explicit coordinates, recovers it). Tool cards escape that
+ * fate only because their definition does not consult the step location.
+ * @returns whether the line folded (false when the options skipped it).
+ */
+export declare function appendCodexTranscriptLine(childSession: Session, turn: number, step: number, line: CodexTranscriptLine, usage: TokenUsage | undefined): boolean;
+/** The delta-progress text for one transcript line. */
+export declare function codexLineText(line: CodexTranscriptLine): string;
+/**
+ * Persist the child session's mirrored events. Thin wrapper over the core's
+ * {@link persistChildSession}: a live session syncs through the core's cached
+ * per-child write handle (host 0.1.5's live write-behind never checkpoints a
+ * mirror session — it has no agent loop — so production child logs stayed
+ * header-only until the explicit sync), a standalone one through a one-shot
+ * handle flow. Kept under the historical name for the live driver.
+ */
+export declare function persistIfStandalone(ctx: Context, childSession: Session): Promise<void>;
+export {};
+//# sourceMappingURL=codex-cli-provider.d.ts.map