@khorsheed/dsh-local-agent-codex 0.2.0-rc.1 → 0.2.0

package/lib/types/codex-cli-provider.js

@@ -16,12 +16,21 @@
 import { randomUUID } from 'node:crypto';
 import { createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { NO_START_CAPABILITIES, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
+import { NO_START_CAPABILITIES, SUBAGENT_DESCRIPTOR_VERSION, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel, containerExecSpawn, containerScopedHome, delegationEnv, establishSubagentCatalogChild, persistChildSession, probeCliVersion, resolveChildCwd, subagentDelegationLabel, } from '@khorsheed/dsh-local-agent';
 import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from '@khorsheed/dsh-local-agent/types';
 import { LiveChannelUnavailableError } from './live-driver.js';
+import { endpointAuthEnv, endpointConfigOverrides, hasEndpointCredential } from './endpoint-auth.js';
 import { readCodexBaseUrl } from './provision.js';
 import { codexRolloutRoundFacts, usageFromCodex } from './records.js';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a killed run, or a result-less item type like web_search_call). The
+ * released-log contract resolves every advertised call before its step
+ * closes, so an interrupted call folds with this error result. Same text as
+ * the kimi provider's placeholder, for family consistency.
+ */
+export const CODEX_INTERRUPTED_TOOL_RESULT = '（工具调用被中断，未能记录返回结果）';
 /** Quote one TOML basic string for the `-c` config override. */
 function tomlString(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -49,7 +58,10 @@ export function registerCodexMemberRun(ctx, childSessionId, parentSessionId) {
         + `command=${tomlString(bridge.command)},`
         + `args=[${bridge.args.map(tomlString).join(',')}],`
         + `env={${MEMBER_BRIDGE_SOCKET_ENV}=${tomlString(registry.memberBridgeSocketPath())},${MEMBER_BRIDGE_TOKEN_ENV}=${tomlString(token)}},`
-        + `default_tools_approval_mode=${tomlString('approve')}`
+        + `default_tools_approval_mode=${tomlString('approve')},`
+        // A bridge call may wait for the human (ask_user_question, a mode tool's
+        // approval): Codex's 60s MCP default would fail it first.
+        + `tool_timeout_sec=1800`
         + `}`;
     let released = false;
     return {
@@ -116,6 +128,7 @@ export class CodexCliProvider {
     live;
     model;
     overrides;
+    endpoint;
     name = 'codex-local';
     capabilities = NO_START_CAPABILITIES;
     inheritsParentContext = false;
@@ -126,22 +139,33 @@ export class CodexCliProvider {
      *   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.
+     *   reload; it receives the round's scope (a named scope's curated list
+     *   answers first). 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.
+     * @param endpoint - resolver for the scope's endpoint credential, read PER
+     *   ROUND so a settings-card write takes effect on the next delegation
+     *   without a reload. A resolution carrying a key routes the round at the
+     *   relay (a custom `model_providers` entry on the argv, the key in the
+     *   env); with no key the spawn carries no credential at all.
      */
-    constructor(ctx, sandbox = 'workspace-write', live, model, overrides) {
+    constructor(ctx, sandbox = 'workspace-write', live, model, overrides, endpoint) {
         this.ctx = ctx;
         this.sandbox = sandbox;
         this.live = live;
         this.model = model;
         this.overrides = overrides;
+        this.endpoint = endpoint;
+    }
+    /** The scope's endpoint credential for this round; absent resolver = never. */
+    resolveEndpoint(homeDir) {
+        return this.endpoint === undefined ? Promise.resolve(undefined) : this.endpoint(homeDir).catch(() => undefined);
     }
     /** Resolve the live driver for one round's member, if live is on for it. */
     liveDriver(childSessionId) {
@@ -198,7 +222,7 @@ export class CodexCliProvider {
                 ...record?.configurationLock === undefined ? {} : { configurationLock: record.configurationLock },
             }, configuration => this.startCodexResume(request, intent, cwd, homeDir, exec, scope, record?.model, configuration), request.signal, intent?.onAdmitted);
         }
-        const childSessionId = SessionId(intent?.preparedMemberId ?? randomUUID());
+        const childSessionId = SessionId(intent?.preparedMemberId ?? intent?.childSessionId ?? randomUUID());
         if (typeof this.ctx.localAgent.withMemberConfigurationRound !== 'function') {
             if (intent?.effort !== undefined)
                 throw new Error('Codex effort requires the configuration admission core');
@@ -231,14 +255,20 @@ export class CodexCliProvider {
                 },
             });
             const harness = this.ctx.localAgent.get('codex');
-            const label = subagentDelegationLabel(harness?.displayName ?? 'codex', request.descriptor.label);
+            // Host 0.2.1 no longer resolves a descriptor onto the request (the
+            // runtime's one-shot snapshot is gone), so the provider stamps the same
+            // payload itself; the activation spec's required label arrives as the
+            // empty string when the caller named none.
+            const label = subagentDelegationLabel(harness?.displayName ?? 'codex', request.label || undefined);
             childSession.append('subagent/descriptor', {
-                ...request.descriptor,
+                version: SUBAGENT_DESCRIPTOR_VERSION,
+                mode: 'one-shot',
+                provider: this.name,
                 label,
             });
-            // The official runtime appends the parent-side subagent/catalog
-            // discovery row only for in-process children (run.localAgent); this run
-            // is remote, so the provider appends it here — once per child, where
+            // The 0.2.1 manager appends the parent-side subagent/catalog discovery
+            // row only for parent-delivered children; the family runs caller
+            // delivery, so the provider appends it here — once per child, where
             // the descriptor lands. A failure degrades to the warn below; a missing
             // row never blocks the delegation.
             establishSubagentCatalogChild(request.parent.session, childSession.header, label);
@@ -251,11 +281,15 @@ export class CodexCliProvider {
         catch (error) {
             this.ctx.logger.warn(`subagent-codex: subagent session record failed: ${error instanceof Error ? error.message : String(error)}`);
         }
-        // Resolve the effective custom endpoint from the scoped config.toml for
-        // diagnostics: codex reads it directly (a user manually editing the
-        // config to route through a custom provider is authoritative). Logged
-        // BEFORE the drive-mode branch so live rounds report their endpoint too.
-        const baseUrl = await readCodexBaseUrl(homeDir).catch(() => undefined);
+        // The round's endpoint: a configured endpoint credential (the scope's
+        // endpoint-auth.json over the plugin config) routes the argv through a
+        // custom provider entry and its key rides the env. With no credential the
+        // scoped config.toml's own custom provider answers for the diagnostic
+        // exactly as before (a user-edited value is authoritative). Logged BEFORE
+        // the drive-mode branch so live rounds report their endpoint too.
+        const endpoint = await this.resolveEndpoint(homeDir);
+        const routed = hasEndpointCredential(endpoint);
+        const baseUrl = routed ? endpoint.baseUrl : await readCodexBaseUrl(homeDir).catch(() => undefined);
         this.ctx.logger.info(`subagent-codex: delegating via ${baseUrl ?? 'codex default endpoint'}`);
         // Live driver: the round goes to the resident app-server process (one per
         // member). A channel that fails at spawn/handshake falls through to the
@@ -314,11 +348,12 @@ export class CodexCliProvider {
         try {
             const run = await startCodexCliRun(request, {
                 cwd,
-                env: delegationEnv({ CODEX_HOME: homeDir }),
+                env: delegationEnv({ CODEX_HOME: homeDir, ...endpointAuthEnv(endpoint) }),
                 ...exec === undefined ? {} : { exec },
                 endpointLabel: baseUrl,
+                endpointArgv: endpointConfigOverrides(endpoint),
                 sandbox: this.sandbox,
-                ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(runId) ?? requestedModel, this.model)),
+                ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(runId) ?? requestedModel, () => this.model?.(scope))),
                 disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
                 spawn: spec => this.ctx.subprocess.spawn(spec),
                 onError: (error, stopReason) => {
@@ -383,7 +418,11 @@ export class CodexCliProvider {
                 throw new Error(`subagent-codex: resume target child session ${intent.childSessionId} is not live — start a fresh delegation instead`);
             }
             const nextTurn = childSession.snapshotEvents().filter(event => event.type === 'turn/start').length + 1;
-            const baseUrl = await readCodexBaseUrl(homeDir).catch(() => undefined);
+            // Same endpoint precedence as the fresh path: a configured endpoint
+            // credential routes the round at the relay, else the scoped
+            // config.toml's own custom provider answers for the diagnostic.
+            const endpoint = await this.resolveEndpoint(homeDir);
+            const baseUrl = hasEndpointCredential(endpoint) ? endpoint.baseUrl : await readCodexBaseUrl(homeDir).catch(() => undefined);
             // Logged BEFORE the drive-mode branch so live rounds report their endpoint too.
             this.ctx.logger.info(`subagent-codex: resuming via ${baseUrl ?? 'codex default endpoint'}`);
             // Live driver: continue the member's resident app-server thread. Channel
@@ -423,11 +462,12 @@ export class CodexCliProvider {
             try {
                 run = await startCodexCliRun(request, {
                     cwd,
-                    env: delegationEnv({ CODEX_HOME: homeDir }),
+                    env: delegationEnv({ CODEX_HOME: homeDir, ...endpointAuthEnv(endpoint) }),
                     ...exec === undefined ? {} : { exec },
                     endpointLabel: baseUrl,
+                    endpointArgv: endpointConfigOverrides(endpoint),
                     sandbox: this.sandbox,
-                    ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(intent.childSessionId) ?? requestedModel, this.model)),
+                    ...(configuration?.resolved ?? resolveRoundModel(this.overrides?.(intent.childSessionId) ?? requestedModel, () => this.model?.(scope))),
                     disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
                     spawn: spec => this.ctx.subprocess.spawn(spec),
                     onError: (error, stopReason) => {
@@ -622,6 +662,40 @@ function foldCodexStreamLine(state, raw) {
             }
         }
     }
+    else if (item.type === 'custom_tool_call') {
+        // Custom tools (the deferred `exec` discovery tool, dynamic tools): the
+        // call rides `input`, its result the paired custom_tool_call_output.
+        // Without this branch a tool-loop round mirrored as two bare adjacent
+        // replies with the call between them invisible.
+        countToolCall(state, 'custom_tool_call');
+        state.lines.push({
+            kind: 'tool',
+            id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+            name: item.name ?? 'custom',
+            ...typeof item.input === 'string' && item.input !== '' ? { args: item.input } : {},
+        });
+    }
+    else if (item.type === 'custom_tool_call_output') {
+        // {call_id, output: string | content blocks} — pair by recency, the same
+        // idiom function_call_output uses (the stream orders a result right
+        // behind its call).
+        const output = typeof item.output === 'string' ? item.output
+            : Array.isArray(item.output)
+                ? item.output
+                    .filter((block) => typeof block === 'object' && block !== null && typeof block.text === 'string')
+                    .map(block => block.text)
+                    .join('\n')
+                : undefined;
+        if (output !== undefined && output.trim() !== '') {
+            const last = state.lines[state.lines.length - 1];
+            if (last !== undefined && last.kind === 'tool') {
+                state.lines[state.lines.length - 1] = {
+                    ...last,
+                    result: last.result === undefined ? output : `${last.result}\n${output}`,
+                };
+            }
+        }
+    }
 }
 /**
  * Incremental `codex exec --json` parser: feed stdout chunks as they arrive
@@ -656,7 +730,8 @@ export class CodexStreamParser {
  * 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`
+ * `web_search_call`, `custom_tool_call`/`custom_tool_call_output` (deferred
+ * and dynamic tools), 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.
@@ -697,7 +772,9 @@ export function startCodexCliRun(request, spec) {
     const turn = spec.resume?.turn ?? 1;
     // The member bridge rides a per-process `-c` override placed right after
     // `exec` (the spike-verified position; `codex exec resume` accepts it too).
+    // The endpoint credential's overrides sit next to it — `-c` pairs commute.
     const memberArgv = spec.member === undefined ? [] : ['-c', spec.member.configOverride];
+    const endpointArgv = spec.endpointArgv ?? [];
     // `--skip-git-repo-check` rides every exec argv. Codex refuses to start
     // outside a Git repository ("Not inside a trusted directory and
     // --skip-git-repo-check was not specified") and exits before producing a
@@ -718,8 +795,8 @@ export function startCodexCliRun(request, spec) {
         ...spec.effort === undefined ? [] : ['-c', `model_reasoning_effort=${JSON.stringify(spec.effort)}`],
     ];
     const argv = spec.resume === undefined
-        ? ['codex', 'exec', ...memberArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', task]
-        : ['codex', 'exec', ...memberArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', 'resume', spec.resume.cliSessionId, task];
+        ? ['codex', 'exec', ...memberArgv, ...endpointArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', task]
+        : ['codex', 'exec', ...memberArgv, ...endpointArgv, ...modelArgv, '--sandbox', spec.sandbox, '--skip-git-repo-check', '--json', 'resume', spec.resume.cliSessionId, task];
     // Container target: the same argv, wrapped in `docker exec`. The host cwd
     // still applies — it is the docker CLIENT's working directory now, while
     // the CLI's own is the target's in-container workdir.
@@ -741,6 +818,17 @@ export function startCodexCliRun(request, spec) {
     // The turn opens at the real spawn moment so the timing projection
     // measures actual CLI runtime, not the post-hoc append time.
     spec.childSession?.append('turn/start', { turn });
+    // The provider's own launch facts are the child log's request config —
+    // codex's stream never carries model/effort, so the argv the provider
+    // spawns with is the authoritative source. The header contract requires a
+    // model: an unconfigured round records nothing rather than inventing one.
+    if (spec.model !== undefined && spec.childSession !== undefined) {
+        appendCodexRequestHeader(spec.childSession, {
+            provider: 'codex-local',
+            model: spec.model,
+            ...spec.effort === undefined ? {} : { reasoningEffort: spec.effort },
+        });
+    }
     // Live mirror: fold the NDJSON stream as chunks arrive so the child session
     // shows the run's progress before settle; the settle mirror below resumes
     // from the live counters and stays a no-op when live mirroring kept up.
@@ -865,29 +953,12 @@ export function startCodexCliRun(request, spec) {
         signal: request.signal,
         onAbort,
     }).then((settled) => {
-        // Every terminal path closes the turn so the timing window never stays
-        // open on a failed or cancelled run: success settles 'completed', a
-        // non-zero exit 'error', and a locally cancelled run 'aborted'. The
-        // turn/end timestamp is the real settle moment.
         // A completed round proves the scoped credential is live — the endpoint
         // answered. Reported here rather than from the mirror so it lands whether
-        // or not the round is session-backed.
+        // or not the round is session-backed. The turn boundary itself is the
+        // post-exit chain's job (it must follow the settle mirror).
         if (settled.stopReason === 'completed')
             spec.onAuthSuccess?.();
-        if (spec.childSession !== undefined) {
-            if (settled.stopReason === 'completed') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
-            }
-            else if (settled.stopReason === 'aborted') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
-            }
-            else {
-                spec.childSession.append('turn/end', {
-                    turn,
-                    reason: { kind: 'error', error: { message: `codex exec exited with code ${String(exitCode)}`, code: 'UNKNOWN' } },
-                });
-            }
-        }
         return settled;
     });
     // After the child EXITS — however it ended (completed, killed by dispose, or
@@ -895,9 +966,13 @@ export function startCodexCliRun(request, spec) {
     // subagent session, so a cancelled round still preserves its partial work
     // (reasoning, commands, replies) and real token usage. The thread id is
     // recorded even on abort so the partial thread stays resumable. Waits for
-    // the settle chain first (so turn/end is already appended) AND for the
-    // process to actually exit (so stdout is drained before parsing).
-    void result.then(() => child.done).then(() => {
+    // the settle chain first AND for the process to actually exit (so stdout is
+    // drained before parsing). The turn closes AFTER the settle mirror, still
+    // serialized behind the live mirror's queue: every mirrored step must land
+    // before turn/end — the released-log reader rejects a step outside an open
+    // turn on every cold read. The run's result still settles at the real
+    // moment (abort latency unchanged); only the boundary event moves.
+    void result.then(() => child.done).then(async () => {
         if (spec.onAuthFailure !== undefined) {
             // The seam's collected buffers are complete at process exit; the
             // streamed variables can lag `done` by a tick.
@@ -908,13 +983,38 @@ export function startCodexCliRun(request, spec) {
                 spec.onAuthFailure(authDetail.split('\n').find(line => line.trim() !== '') ?? 'auth failure');
             }
         }
-        return mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
+        await mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
+        // Every terminal path closes the turn so the timing window never stays
+        // open on a failed or cancelled run: success settles 'completed', a
+        // non-zero exit 'error', and a locally cancelled run 'aborted'.
+        if (spec.childSession !== undefined) {
+            const settled = await result;
+            if (settled.stopReason === 'completed') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+            }
+            else if (settled.stopReason === 'aborted') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+            }
+            else {
+                spec.childSession.append('turn/end', {
+                    turn,
+                    reason: { kind: 'error', error: { message: `codex exec exited with code ${String(exitCode)}`, code: 'UNKNOWN' } },
+                });
+            }
+            if (spec.ctx !== undefined) {
+                await persistChildSession(spec.ctx, spec.childSession).catch((error) => {
+                    spec.ctx?.logger.warn(`subagent-codex: turn/end persistence failed: ${thrown(error).message}`);
+                });
+            }
+        }
     }, () => { });
     return Promise.resolve(subprocessRunHandle({
-        // A session-backed run's id is the child session id (the seam's local-run
-        // contract), so the tool's resume self-description names the same handle
-        // the delegation registry records.
-        id: spec.childSession?.id ?? SessionId(randomUUID()),
+        // Host 0.2.1: the published run id is a fresh PER-EXECUTION identity —
+        // the activation manager rejects a run id naming a live Session (the
+        // mirrored child session is exactly that), and resume rounds reuse the
+        // child session id. The durable child identity the family tracks rides
+        // the staged intent instead (spec.childSession.id == its childSessionId).
+        id: SessionId(randomUUID()),
         result,
         signal: request.signal,
         onAbort,
@@ -922,6 +1022,27 @@ export function startCodexCliRun(request, spec) {
         teardown: disposeProcess,
     }));
 }
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export function appendCodexRequestHeader(childSession, config) {
+    const serialized = JSON.stringify(config);
+    let last;
+    for (const event of childSession.snapshotEvents()) {
+        if (event.type === 'request/header') {
+            last = JSON.stringify(event.data.header?.config);
+        }
+    }
+    if (last === serialized)
+        return;
+    childSession.append('request/header', {
+        header: { config },
+        reason: last === undefined ? 'initial' : 'change',
+    });
+}
 /** One assistant-role message event, attributed to the codex route. */
 export function codexAssistantEvent(blocks) {
     return createAssistantMessage({
@@ -935,35 +1056,48 @@ export function codexAssistantEvent(blocks) {
  * 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.
+ * drafts from the explicit coordinates, recovers it).
+ *
+ * A tool line folds the NATIVE lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, then its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes.
+ * Every fold sees a COMPLETED item (the exec live mirror holds the volatile
+ * last line; the live driver folds at item/completed), so a result the
+ * stream has not recorded by fold time will never arrive — the call folds
+ * with the synthesized interrupted result instead of leaving the step
+ * unresolvable.
  * @returns whether the line folded (false when the options skipped it).
  */
 export function appendCodexTranscriptLine(childSession, turn, step, line, usage) {
     childSession.append('step/start', { turn, step });
     if (line.kind === 'tool') {
-        // Native tool card: the call event now, the result event when the stream
-        // already carries it. Tool lines never carry the round's usage — the
-        // callers attach usage to the round's final line, which is an agent
-        // message on every well-formed stream.
+        // A tool-only call's usage rides the advertising assistant/message (the
+        // tool/call and tool/result events themselves have no usage slot).
+        const args = line.args ?? '';
+        childSession.append('assistant/message', {
+            turn,
+            step,
+            message: codexAssistantEvent([{ type: 'tool-call', id: line.id, name: line.name, arguments: args }]),
+            stream: [],
+            ...usage === undefined ? {} : { usage },
+        }, { surfaceOp: 'append' });
         const call = childSession.append('tool/call', {
             turn,
             step,
             callId: line.id,
             name: line.name,
-            arguments: line.args ?? '',
+            arguments: args,
         });
-        if (line.result !== undefined) {
-            childSession.append('tool/result', {
-                turn,
-                step,
-                message: createToolResultMessage({
-                    callId: line.id,
-                    content: [{ type: 'text', text: line.result }],
-                    isError: false,
-                }),
-            }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
-        }
+        childSession.append('tool/result', {
+            turn,
+            step,
+            message: createToolResultMessage({
+                callId: line.id,
+                content: [{ type: 'text', text: line.result ?? CODEX_INTERRUPTED_TOOL_RESULT }],
+                isError: line.result === undefined,
+            }),
+        }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
         childSession.append('step/end', { turn, step });
         return true;
     }

package/lib/types/endpoint-auth.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Endpoint-key authentication — the codex harness's ONLY auth mode. There is
+ * no web login anywhere in this package: a delegation round reaches its
+ * endpoint with a custom `model_providers` entry on the argv pointing at the
+ * relay and the key traveling as `OPENAI_API_KEY` in the process environment
+ * (verified against codex-cli 0.163.0: a fresh scoped home with only these
+ * runs `codex exec` with no login file at all). With no credential the spawn
+ * carries no auth at all — it fails loudly at the endpoint, exactly the
+ * honest reading the status shows.
+ *
+ * Verified against codex-cli 0.163.0 (2026-10-20): a fresh scoped home with
+ * only `OPENAI_API_KEY` plus the two `-c` overrides below runs
+ * `codex exec -m <model>` end-to-end through an OpenAI-compatible relay
+ * (openproxy, `wire_api = "responses"`) — no login, no auth.json, no
+ * onboarding gate.
+ *
+ * Two layers, merged per field, file over config:
+ *
+ * - `<scopedHome>/endpoint-auth.json` (mode 0600) — the per-scope credential.
+ *   Its name deliberately matches the eval contract hash's credential denylist
+ *   (`auth`), so the key material never enters an evaluation's condition
+ *   fingerprint; the file's mtime serves as the credential stamp, which makes
+ *   "edit the file" the recovery gesture for a `rejected` grade.
+ * - The plugin config's `baseUrl` / `apiKey` — the deployment default every
+ *   scope without a file shares. Read PER ROUND, so a profile edit applies to
+ *   the next round (and a host restart clears the in-memory `rejected` mark).
+ *
+ * `wireApi` is a file-only escape hatch: the settings card never edits it,
+ * the default `responses` is codex's native wire (relay-verified), and a
+ * hand-edit to `"chat"` survives the card's whole-file writes because the
+ * read merges it back. The env layer rides the family's existing plumbing:
+ * `delegationEnv` on the host, `containerExecSpawn`'s name-only `-e`
+ * forwarding into a container — a containerized round authenticates with the
+ * same credential as the host, nothing is authorized inside the unit.
+ * @module @khorsheed/dsh-local-agent-codex/endpoint-auth
+ */
+/**
+ * The scoped-home credential file's name. Chosen to match the eval contract
+ * hash's credential-shaped denylist (`/token|key|credential|secret|password|auth|\.env/i`),
+ * so the file is excluded from condition fingerprints by name.
+ */
+export declare const ENDPOINT_AUTH_FILE = "endpoint-auth.json";
+/** The custom provider's TOML key in the `-c` overrides (bare-key safe). */
+export declare const ENDPOINT_PROVIDER_NAME = "dsh-endpoint";
+/** The env var the custom provider reads the key from (`env_key`). */
+export declare const ENDPOINT_ENV_KEY = "OPENAI_API_KEY";
+/**
+ * One scope's endpoint credential. `baseUrl` is optional (absent means the
+ * CLI's own default OpenAI endpoint — an official platform key needs no
+ * relay); a non-empty `apiKey` is what makes the scope endpoint-authenticated.
+ * `wireApi` selects the custom provider's wire protocol; absent defaults to
+ * `responses` (codex's native wire, relay-verified).
+ */
+export interface CodexEndpointAuth {
+    readonly baseUrl?: string;
+    /** Sent as the custom provider's `env_key` environment value (Bearer). */
+    readonly apiKey?: string;
+    /** `responses` (default) or `chat`; file-only, never card-edited. */
+    readonly wireApi?: string;
+}
+/** Whether a resolved endpoint carries a usable credential. */
+export declare function hasEndpointCredential(auth: CodexEndpointAuth | undefined): auth is CodexEndpointAuth & {
+    apiKey: string;
+};
+/**
+ * Read the scope's endpoint-auth.json. Absent or unreadable yields undefined
+ * (the caller falls back to the plugin config); malformed JSON or a non-object
+ * payload also yields undefined — a torn file must not fail a status read.
+ * Non-string fields are dropped, never carried through.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the file's endpoint credential, or undefined.
+ */
+export declare function readEndpointAuthFile(homeDir: string): Promise<CodexEndpointAuth | undefined>;
+/**
+ * Resolve one scope's effective endpoint credential: the scope's
+ * endpoint-auth.json merged FIELD BY FIELD over the plugin config's
+ * `baseUrl` / `apiKey` (a file that names only a key rotates the key while
+ * keeping the deployment's relay URL). The result may carry no credential at
+ * all — {@link hasEndpointCredential} is the judgment, kept separate so the
+ * caller can still route/log the resolved baseUrl.
+ * @param homeDir - the scope's scoped home.
+ * @param config - the plugin config's deployment-level endpoint pair.
+ * @returns the merged endpoint auth.
+ */
+export declare function resolveEndpointAuth(homeDir: string, config: CodexEndpointAuth): Promise<CodexEndpointAuth>;
+/**
+ * The spawn-env layer for a resolved endpoint: the key under the custom
+ * provider's `env_key` name, nothing else. A credential-less resolution
+ * yields an empty layer — the spread then adds no keys at all, byte-identical
+ * to the pre-endpoint env. With no baseUrl the CLI's built-in OpenAI provider
+ * reads the same variable, so an official platform key needs no `-c`
+ * override either.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the explicit env entries for the delegation spawn.
+ */
+export declare function endpointAuthEnv(auth: CodexEndpointAuth | undefined): NodeJS.ProcessEnv;
+/**
+ * The `-c` config overrides routing the CLI at the resolved relay: a custom
+ * `model_providers` entry plus the `model_provider` selection, as a flat argv
+ * fragment (`-c <override>` pairs). Empty unless BOTH a key and a baseUrl are
+ * present — a key without a relay URL is served by the built-in provider
+ * through the env layer alone, and a relay URL without a key would route
+ * every round into a 401. Verified end-to-end against codex-cli 0.163.0.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the argv fragment, possibly empty.
+ */
+export declare function endpointConfigOverrides(auth: CodexEndpointAuth | undefined): string[];
+/**
+ * The credential marker's modification stamp (epoch ms): the endpoint file's
+ * mtime, or undefined when the scope has no file (a config-sourced credential
+ * has no marker — rotating it pairs with the profile edit and instance
+ * restart that clear the in-memory grade marks). A fresh file write is a
+ * fresh stamp, which is how an edited-in key recovers a `rejected` grade.
+ * @param homeDir - the scope's scoped home.
+ * @returns the stamp, or undefined.
+ */
+export declare function endpointAuthStamp(homeDir: string): Promise<number | undefined>;
+/** Whether the scope carries its own endpoint file at all. */
+export declare function endpointAuthFileExists(homeDir: string): Promise<boolean>;
+/**
+ * Write the scope's endpoint-auth.json (mode 0600, mkdir -p first). The
+ * payload preserves the file-only `wireApi` across card writes: callers pass
+ * the merged object (current file + edits), never a bare card payload.
+ * @param homeDir - the scope's scoped home.
+ * @param auth - the endpoint credential to persist.
+ */
+export declare function writeEndpointAuth(homeDir: string, auth: CodexEndpointAuth): Promise<void>;
+/**
+ * Clear the scope's OWN endpoint credential (the endpoint-auth.json file).
+ * A deployment-level credential from the plugin config is untouched — the
+ * core's logout reply then names the profile row as the place to edit.
+ * @param homeDir - the scope's scoped home.
+ */
+export declare function clearEndpointAuth(homeDir: string): Promise<void>;
+/** The official endpoint used when no baseUrl is configured anywhere. */
+export declare const OFFICIAL_BASE_URL = "https://api.openai.com";
+/** The probe's fetch shape (injected in tests). */
+export type EndpointCheckFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/**
+ * The outcome of one `GET <baseUrl>/v1/models`: the parsed id list, the HTTP
+ * status when the endpoint answered, or the transport error's message. No
+ * case throws.
+ */
+export type EndpointModelsResult = {
+    readonly kind: 'models';
+    readonly models: readonly string[];
+} | {
+    readonly kind: 'http';
+    readonly status: number;
+    readonly body: string;
+} | {
+    readonly kind: 'unreachable';
+    readonly message: string;
+} | {
+    readonly kind: 'malformed';
+};
+/**
+ * `GET <baseUrl>/v1/models` with `Authorization: Bearer <key>` — the
+ * token-free endpoint probe shared by the `/codex check` verdict and any
+ * future catalog. OpenAI's own API serves this route with the platform key;
+ * relays (openproxy verified 2026-10-20, 139 models) proxy it and answer the
+ * same OpenAI-list shape. Never throws: every failure mode folds into the
+ * result.
+ * @param endpoint - the resolved endpoint auth with a decided baseUrl.
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param signal - abort for the whole probe (timeout bundled by the caller).
+ * @returns the folded result.
+ */
+export declare function fetchEndpointModels(endpoint: CodexEndpointAuth & {
+    readonly baseUrl: string;
+}, fetchImpl?: EndpointCheckFetch, signal?: AbortSignal): Promise<EndpointModelsResult>;
+/**
+ * Probe the resolved endpoint with a cheap, token-free round-trip: `GET
+ * <baseUrl>/v1/models` with the resolved credential's Bearer header. A 200
+ * proves both reachability and credential validity — the exact evidence a
+ * "verify" button needs — and the served model list rides the reply. One
+ * transport-level retry rides along: a local proxy restart (a Surge/clash
+ * reload) stalls the first attempt into the timeout and answers the retry
+ * immediately. Never throws: every failure mode folds into the reply text,
+ * since the reply IS the diagnostic.
+ * @param endpoint - the resolved endpoint auth (scope file over settings).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param timeoutMs - one attempt's deadline (two attempts at most).
+ * @returns the human-readable verdict for the check reply.
+ */
+export declare function checkCodexEndpoint(endpoint: CodexEndpointAuth, fetchImpl?: EndpointCheckFetch, timeoutMs?: number): Promise<string>;
+//# sourceMappingURL=endpoint-auth.d.ts.map