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

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

@@ -16,10 +16,11 @@
 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';
 /** Quote one TOML basic string for the `-c` config override. */
@@ -116,6 +117,7 @@ export class CodexCliProvider {
     live;
     model;
     overrides;
+    endpoint;
     name = 'codex-local';
     capabilities = NO_START_CAPABILITIES;
     inheritsParentContext = false;
@@ -126,22 +128,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 +211,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 +244,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 +270,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 +337,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 +407,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 +451,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) => {
@@ -697,7 +726,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 +749,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.
@@ -911,10 +942,12 @@ export function startCodexCliRun(request, spec) {
         return mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
     }, () => { });
     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,

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