super-dsh 0.1.6 → 0.1.10-e

package/agent-claude/dist/agent.js

@@ -39,11 +39,14 @@
  */
 import { randomUUID } from "node:crypto";
 import { agentEvents } from "@deepseek-ai/dsh-agent";
+import { canonicalHeader, headerEquals } from "@deepseek-ai/dsh-session";
 import { LlmAttemptId, ToolCallId, createAssistantMessage, createSystemMessage, createToolResultMessage, createUserMessage, } from "@deepseek-ai/dsh-llm";
 import { createScope } from "@deepseek-ai/dsh-scope";
 import { toClaudeContent } from "./content.js";
 import { Inbox } from "./inbox.js";
 import { resetProjectionState } from "./claude-events.js";
+import { NATIVE_LAUNCH } from "./claude-launch.js";
+import { resolveRoute, routeSeed } from "./claude-route.js";
 import { CLAUDE_PROVIDER_ID } from "./adapter.js";
 import { claudePermissionMode, presetFromEvents } from "./permission.js";
 import { catalogFromInit, modelEntryFromSdk, readModelCatalog, setModelCatalog } from "./models.js";
@@ -235,6 +238,9 @@ export class ClaudeAgent {
     inbox;
     ctx;
     client;
+    /** Unsubscriber for the LIVE client's wire listener — released before a swap closes the old child. */
+    clientUnsubscribe = undefined;
+    clientFactory;
     loopCtx;
     scope;
     dispatch;
@@ -262,7 +268,12 @@ export class ClaudeAgent {
     systemMessageDone = false;
     /** Last `request/context` route key (`provider/model`) — dedupes per-turn emits. */
     lastRouteKey = null;
-    /** Live v2 assistant-stream publication for the in-flight wire message. */
+    /** The route the OPEN turn runs, captured when the turn opened. */
+    turnRoute = undefined;
+    /** The route the LIVE client was last told to run (`provider/model`) — a work-saver. */
+    routeKey = null;
+    /** Whether THIS agent instance has already logged a `request/header` snapshot. */
+    requestHeaderLogged = false;
     streamBridge;
     assistantAttemptCounter = 0;
     assistantStreamRevision = 0;
@@ -295,12 +306,13 @@ export class ClaudeAgent {
     commandsSignature = "";
     /** Releases the current mirror before it is rebuilt or the agent is disposed. */
     commandsDisposer = undefined;
-    constructor(loopCtx, id, options, session, client, onIdleExit, runtimeInfo) {
+    constructor(loopCtx, id, options, session, client, onIdleExit, runtimeInfo, clientFactory) {
         this.loopCtx = loopCtx;
         this.id = id;
         this.options = options;
         this.session = withSystemHead(session, () => createSystemMessage(""));
         this.client = client;
+        this.clientFactory = clientFactory;
         this.onIdleExit = onIdleExit;
         this.runtimeInfo = runtimeInfo;
         this.dispatch = agentEvents(loopCtx, this);
@@ -318,7 +330,7 @@ export class ClaudeAgent {
             this.attachCommandRuntime(commandCtx.commands);
         });
         this.lastTurn = session.snapshotEvents().findLast((event) => event.type === "turn/start")?.data.turn ?? 0;
-        client.on((event) => this.handleEvent(event));
+        this.clientUnsubscribe = client.on((event) => this.handleEvent(event));
         // Session-start projection reset: the module-level tool-name map must never
         // leak another session's tool into this one (Task 4 review finding).
         resetProjectionState();
@@ -420,6 +432,12 @@ export class ClaudeAgent {
         }
         this.markIdle();
         this.endActivity();
+        // Release the live client's wire listener BEFORE its child closes (Task 9
+        // ledger): without this the dispose path can still receive the superseded
+        // client's stale `agent_end` — the same bug class `reattach()` guards
+        // against on the swap path.
+        this.clientUnsubscribe?.();
+        this.clientUnsubscribe = undefined;
         this.client.close();
         resetProjectionState();
         // Release the command mirror explicitly (the agent scope would also dispose
@@ -618,8 +636,14 @@ export class ClaudeAgent {
      * than hanging, then unwinds the reservation.
      */
     async startTurn(message) {
+        let route;
         try {
-            await this.client.ensureStarted();
+            // Resolve the route and put it in force BEFORE the client is touched: a
+            // provider move is a different child, and a mid-turn selection change must
+            // land on the NEXT turn's applyRoute — never kill the running turn.
+            route = this.resolveRoute();
+            await this.applyRoute(route);
+            this.turnRoute = route;
             await this.bootstrapSessionIdentity();
         }
         catch (error) {
@@ -637,9 +661,11 @@ export class ClaudeAgent {
         if (this.disposed)
             return;
         this.session.append("turn/start", { turn: this.dashTurn });
-        // Route metadata for the next request (`request/context`) lands before
-        // the turn's messages, exactly as the reference loop stamps it.
-        this.emitRequestContext();
+        // Route metadata for the next request lands before the turn's messages,
+        // exactly as the reference loop stamps it.
+        if (route !== undefined)
+            this.commitRequestHeader(route);
+        this.emitRequestContext(route);
         this.appendUserMessage(message);
         // Flush any idle-injection that was parked before this turn.
         for (const entry of this.remoteQueue.splice(0)) {
@@ -743,25 +769,132 @@ export class ClaudeAgent {
      * effective provider/model plus the model's context window when genuinely
      * known. Turn-enclosed (no step required) and deduped by route key.
      */
-    emitRequestContext() {
+    emitRequestContext(route) {
         if (!this.turnOpen)
             return;
-        const model = this.observedMessageModel || this.observedDefaultModel || this.options.model || "";
+        // A resolved route names the raw provider/model pair (the route the selector
+        // picked); a missing route falls back to the observed model (the degraded
+        // single-provider shape), preserving the pre-multi-provider metadata.
+        const model = route !== undefined
+            ? route.model
+            : (this.observedMessageModel || this.observedDefaultModel || this.options.model || "");
         if (model === "")
             return;
-        const key = `${CLAUDE_PROVIDER_ID}/${model}`;
+        const provider = route?.provider ?? CLAUDE_PROVIDER_ID;
+        const key = `${provider}/${model}`;
         if (key === this.lastRouteKey)
             return;
         this.lastRouteKey = key;
-        const entry = readModelCatalog().models.find((candidate) => candidate.id === model);
-        const contextWindow = entry?.contextWindow;
+        const contextWindow = route !== undefined
+            ? (this.runtimeInfo?.contextWindowFor?.(route.provider, route.model)
+                ?? readModelCatalog().models.find((candidate) => candidate.id === route.model)?.contextWindow)
+            : undefined;
         this.session.append("request/context", {
-            provider: CLAUDE_PROVIDER_ID,
+            provider,
             model,
             ...(contextWindow !== undefined && contextWindow > 0 ? { contextWindow } : {}),
         });
         trace(`request/context ${key}${contextWindow === undefined ? "" : ` ctx=${contextWindow}`}`);
     }
+    /**
+     * Resolve the route this session must run, mirroring the harness's own
+     * precedence (`pending ?? logged ?? preferred ?? fallback`). Each candidate is
+     * already a raw provider/model pair — the provider IS the route id and the
+     * model IS the raw wire id (the codex twin's shape). A provider id with no
+     * store entry reads as "launch native, inject nothing".
+     */
+    resolveRoute() {
+        const projections = this.loopCtx.get("sessionProjections");
+        const service = this.ctx.get("agentDefaultModel");
+        return resolveRoute({
+            pending: projections?.stateOf?.(this.session, "modelSelection")?.pending,
+            logged: this.session.requestHeader()?.config,
+            preferred: service?.currentSelection?.(),
+            fallback: routeSeed(this.options),
+        });
+    }
+    /**
+     * Put the resolved route in force on the client, swapping the child when the
+     * provider moved. Three cases, in increasing cost:
+     *  1. nothing spawned yet — pin the launch and let the first prompt spawn
+     *     (the lazy-spawn gate: choosing a model must not cost a process);
+     *  2. same provider — `setModel` rides the live query with the RAW id;
+     *  3. different provider — the child is replaced (`reattach`).
+     */
+    async applyRoute(route) {
+        const launch = route === undefined ? undefined : this.runtimeInfo?.launchFor?.(route.provider, route.model);
+        // An unknown provider id (a legacy session pinned before the multi-provider
+        // rework) maps to "no injection": the user's own settings.json decides.
+        const launchSpec = launch ?? NATIVE_LAUNCH;
+        const providerId = launch === undefined ? null : route?.provider ?? null;
+        const client = this.client;
+        const key = `${providerId ?? "native"}/${route?.model ?? ""}`;
+        if (!client.spawned) {
+            client.setLaunch(launchSpec);
+            await client.ensureStarted();
+        }
+        else if ((client.appliedProvider ?? null) !== providerId) {
+            await this.reattach(launchSpec, providerId, route);
+        }
+        else if (route !== undefined) {
+            await client.setModel(route.model).catch((error) => {
+                trace(`set_model ${key} failed: ${String(error)}`);
+            });
+        }
+        this.routeKey = key;
+    }
+    /**
+     * Replace the client at a turn boundary: close the old one and build a fresh
+     * child through the injected factory, resuming the SAME SDK session id and
+     * re-wiring the event listener and the live permission mode.
+     */
+    async reattach(launch, _providerId, _route) {
+        const old = this.client;
+        const threadId = old.threadId;
+        this.clientUnsubscribe?.();
+        old.close();
+        if (this.clientFactory === undefined) {
+            throw new Error("agent-claude: cannot reattach — no clientFactory was injected");
+        }
+        const replacement = this.clientFactory({ ...(threadId !== null ? { resumeSessionId: threadId } : {}), launch });
+        this.clientUnsubscribe = replacement.on((event) => this.handleEvent(event));
+        this.client = replacement;
+        // Re-apply the live permission mode onto the fresh child (the old client's
+        // buffered control calls died with it).
+        const mode = this.runtimeInfo?.claudeMode ?? claudePermissionMode(presetFromEvents(this.session.snapshotEvents()));
+        if (mode !== undefined)
+            void replacement.setPermissionMode(mode).catch(() => { });
+        await replacement.ensureStarted();
+    }
+    /**
+     * Log the request header the NEXT request runs under, so the harness's
+     * `modelSelection` projection retires a pending switch when it matches.
+     */
+    commitRequestHeader(route) {
+        const header = canonicalHeader({
+            config: {
+                provider: route.provider,
+                model: route.model,
+            },
+        });
+        const baseline = this.session.requestHeader();
+        if (!this.requestHeaderLogged) {
+            this.session.append("request/header", { header, reason: baseline === undefined ? "initial" : "resume" });
+            this.requestHeaderLogged = true;
+            return;
+        }
+        if (baseline === undefined || !headerEquals(baseline, header)) {
+            this.session.append("request/header", { header, reason: "change" });
+        }
+    }
+    /** Test-only thin shell over {@link applyRoute}. */
+    async applyRouteForTest(route) {
+        await this.applyRoute(route);
+    }
+    /** Test-only thin shell over {@link resolveRoute}. */
+    resolveRouteForTest() {
+        return this.resolveRoute();
+    }
     /** The open stream bridge for this message, starting one on first use. */
     ensureStreamBridge() {
         if (this.streamBridge === undefined || this.streamBridge.ended) {
@@ -856,7 +989,7 @@ export class ClaudeAgent {
         const assistant = createAssistantMessage({
             content: blocks,
             // The OBSERVED model (what the CLI actually ran), not the requested one.
-            source: { provider: CLAUDE_PROVIDER_ID, model: this.observedMessageModel || this.observedDefaultModel || this.options.model || "" },
+            source: { provider: this.turnRoute?.provider ?? CLAUDE_PROVIDER_ID, model: this.observedMessageModel || this.observedDefaultModel || this.options.model || "" },
         });
         const event = this.session.append("assistant/message", {
             turn: this.dashTurn,
@@ -905,13 +1038,17 @@ export class ClaudeAgent {
     observeModelCatalog(init) {
         if (typeof init.model === "string" && init.model !== "")
             this.observedDefaultModel = init.model;
+        // The observed catalog stays RAW: the fixed `claude` route serves exactly
+        // what the CLI reported, and curated provider models live under their own
+        // routes (2026-10-04 F-A) — no composite minting here.
         const entries = catalogFromInit(init);
         if (entries.length > 0)
             setModelCatalog(entries, this.observedDefaultModel);
         void this.client.supportedModels().then((models) => {
             const full = Array.isArray(models) ? models.flatMap((m) => modelEntryFromSdk(m)) : [];
-            if (full.length > 0)
-                setModelCatalog(full, this.observedDefaultModel);
+            if (full.length === 0)
+                return;
+            setModelCatalog(full, this.observedDefaultModel);
         }).catch((error) => {
             trace(`supportedModels() failed: ${String(error)}`);
         });
@@ -1133,7 +1270,7 @@ export class ClaudeAgent {
                     this.commitStepStart();
                     const assistant = createAssistantMessage({
                         content: blocks,
-                        source: { provider: CLAUDE_PROVIDER_ID, model: String(event.fallbackModel ?? this.options.model ?? "") },
+                        source: { provider: this.turnRoute?.provider ?? CLAUDE_PROVIDER_ID, model: String(event.fallbackModel ?? this.options.model ?? "") },
                     });
                     this.session.append("assistant/message", {
                         turn: this.dashTurn,

package/agent-claude/dist/claude-client.js

@@ -8,6 +8,15 @@
  * methods exist at all), drives the bridge lazily per session, and fans every
  * message out through `projectClaudeEvent` (claude-events.ts).
  *
+ * ## The SDK is runtime-self-fetched, not imported
+ *
+ * The SDK is not a static dependency of this package: the default factory
+ * resolves it at the first real prompt via `loadClaudeQuery(worldHome)`
+ * (sdk-runtime.ts), which fetches the pinned tree into the agent world's
+ * home. `ClaudeFactory` stays SYNCHRONOUS — the await lives in factory
+ * RESOLUTION, never between query construction and the `this.query`
+ * assignment (see `ensureStarted`).
+ *
  * ## The two hard deviations from the codex precedent
  *
  * 1. **No shared singleton.** `agent-codex` multiplexes all clients through one
@@ -54,38 +63,31 @@
  *   every push is queued in order and there is no separate follow-up channel.
  *   `steer` differs by pushing with `priority: "now"`.
  */
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { query as officialQuery } from "@anthropic-ai/claude-agent-sdk";
+import { loadClaudeQuery, resolveClaudeBinary } from "./sdk-runtime.js";
 import { InputQueue } from "./input-queue.js";
 import { projectClaudeEvent } from "./claude-events.js";
-/** Host Claude Code binary driven through the SDK bridge (spec ruling R5).
- * PATH-resolved like any host CLI: $CLAUDE_EXECUTABLE wins, else a bare
- * "claude" the SDK spawns through PATH. No machine-specific path ships. */
-export const DEFAULT_CLAUDE_EXECUTABLE = "claude";
-const defaultFactory = (o) => officialQuery({
-    prompt: o.prompt,
-    options: o.options,
-});
-const defaultExecutableResolver = () => process.env.CLAUDE_EXECUTABLE ?? resolveClaudeExecutable();
-/** PATH first, then the common native-installer locations (a service unit
- * PATH may not include ~/.local/bin — dev3 2026-09-22: "native binary not
- * found at claude" mid-session). */
-function resolveClaudeExecutable() {
-    for (const dir of (process.env.PATH ?? "").split(":").filter(Boolean)) {
-        if (existsSync(join(dir, "claude")))
-            return DEFAULT_CLAUDE_EXECUTABLE;
-    }
-    for (const candidate of [join(homedir(), ".local/bin/claude"), "/usr/local/bin/claude"]) {
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return DEFAULT_CLAUDE_EXECUTABLE;
-}
-let factory = defaultFactory;
+import { NATIVE_LAUNCH } from "./claude-launch.js";
+/** The default executable resolution: Task 1's `resolveClaudeBinary` —
+ * `$CLAUDE_EXECUTABLE` (only while it exists) > `claude` on PATH >
+ * `~/.local/bin/claude` > `/usr/local/bin/claude`. `undefined` means "no
+ * local binary": `pathToClaudeCodeExecutable` is left unset and the SDK's
+ * bundled platform payload is the CLI (bundled-payload mode). */
+const defaultExecutableResolver = () => resolveClaudeBinary();
+let factory; // test injection only
 let executableResolver = defaultExecutableResolver;
 let refcount = 0;
+/** The factory to construct queries with: a test-injected one wins (the sync
+ * seam); otherwise the SDK is self-fetched into `worldHome`'s durable runtime
+ * on first use (sdk-runtime.ts). */
+async function resolveFactory(worldHome) {
+    if (factory)
+        return factory;
+    if (worldHome === undefined) {
+        throw new Error("agent-claude: client needs worldHome to fetch its SDK runtime (the provider passes dshHomePath)");
+    }
+    const sdkQuery = await loadClaudeQuery(worldHome);
+    return (o) => sdkQuery({ prompt: o.prompt, options: o.options });
+}
 /** Replace the SDK entry point (tests inject a fake query). */
 export function setClaudeFactory(next) {
     factory = next;
@@ -101,7 +103,7 @@ export function claudeClientRefCount() {
 /** Restore module-level seams and refcount (test isolation only). */
 export function resetClaudeClientState() {
     refcount = 0;
-    factory = defaultFactory;
+    factory = undefined;
     executableResolver = defaultExecutableResolver;
 }
 /**
@@ -114,13 +116,15 @@ export function resetClaudeClientState() {
  * is the caller's to trace; the boot catalog stays as-is.
  */
 export async function probeClaudeModels(config = {}) {
+    const queryFactory = await resolveFactory(config.worldHome);
+    const executable = executableResolver();
     const queue = new InputQueue();
-    const query = factory({
+    const query = queryFactory({
         prompt: queue,
         options: {
             cwd: config.cwd ?? process.cwd(),
             env: { ...process.env },
-            pathToClaudeCodeExecutable: executableResolver(),
+            ...(executable !== undefined ? { pathToClaudeCodeExecutable: executable } : {}),
             persistSession: false,
         },
     });
@@ -145,10 +149,13 @@ export async function probeClaudeModels(config = {}) {
 }
 export class ClaudeSdkClient {
     cwdPath;
+    worldHome;
     claudeSessionId;
     resumeSessionId;
     canUseTool;
     allowDangerouslySkipPermissions;
+    /** The provider-pinning launch this client will spawn under (NATIVE_LAUNCH until `setLaunch`). */
+    launch;
     /** True while a user turn is in flight (set on push, cleared on `turn_end`/`agent_end`). */
     turnActive = false;
     queue;
@@ -164,10 +171,12 @@ export class ClaudeSdkClient {
             throw new Error("agent-claude: claudeSessionId and resumeSessionId are mutually exclusive");
         }
         this.cwdPath = config.cwd ?? process.cwd();
+        this.worldHome = config.worldHome;
         this.claudeSessionId = config.claudeSessionId;
         this.resumeSessionId = config.resumeSessionId;
         this.canUseTool = config.canUseTool;
         this.allowDangerouslySkipPermissions = config.allowDangerouslySkipPermissions;
+        this.launch = config.launch ?? NATIVE_LAUNCH;
         refcount += 1;
     }
     /**
@@ -186,6 +195,21 @@ export class ClaudeSdkClient {
     get threadId() {
         return this.threadIdValue;
     }
+    /** The provider id this client was last told to spawn under (constructor fact; `null` = native). */
+    get appliedProvider() {
+        return this.launch.providerId;
+    }
+    /**
+     * Pin the launch this client will spawn under. Only legal before the query
+     * exists: once the CLI subprocess is up, a provider move is a different child
+     * (the agent swaps the whole client at a turn boundary — see `#reattach`).
+     */
+    setLaunch(launch) {
+        if (this.query !== undefined) {
+            throw new Error("agent-claude: setLaunch after spawn is not allowed (a provider move swaps the client)");
+        }
+        this.launch = launch;
+    }
     /** The client's own running/streaming attestation (idle-TTL revalidation gate). */
     async getState() {
         return { isStreaming: this.turnActive };
@@ -221,22 +245,27 @@ export class ClaudeSdkClient {
         };
     }
     /**
-     * Lazily construct the query (zero-IO until this runs). Everything up to the
-     * `this.query = query` assignment is synchronous, so concurrent first prompts
-     * can never build two queries: the first caller assigns `this.query` before
-     * any `await` yields control. This single-query invariant therefore depends
-     * on the `ClaudeFactory` contract staying synchronous (it must return the
-     * `Query` without awaiting). The reader loop is started fire-and-forget before
-     * any pending control call is replayed, so a throwing control can never leave
-     * the CLI undrained.
+     * Lazily construct the query (zero-IO until this runs). The factory is
+     * resolved first — an await (a test-injected seam, or the world-home SDK
+     * self-fetch) — and a caller that loses the race during that await reuses
+     * the winner's query at the re-check. From the construct line through the
+     * `this.query = query` assignment everything is synchronous (zero awaits),
+     * so concurrent first prompts can never build two queries. The single-query
+     * invariant therefore still depends on the `ClaudeFactory` contract staying
+     * synchronous (it must return the `Query` without awaiting). The reader loop
+     * is started fire-and-forget before any pending control call is replayed, so
+     * a throwing control can never leave the CLI undrained.
      */
     async ensureStarted() {
         if (this.query !== undefined)
             return;
+        const f = await resolveFactory(this.worldHome); // await BEFORE the sync section
+        if (this.query !== undefined)
+            return; // lost the race to a concurrent first prompt — reuse its query
         const queue = new InputQueue();
-        const query = factory({ prompt: queue, options: this.buildOptions() });
+        const query = f({ prompt: queue, options: this.buildOptions() });
         this.queue = queue;
-        this.query = query;
+        this.query = query; // sync section: zero awaits before this assignment (invariant)
         void this.runReader(query);
         const controls = this.pendingControls;
         this.pendingControls = [];
@@ -303,11 +332,23 @@ export class ClaudeSdkClient {
     }
     // --- internals ------------------------------------------------------------
     buildOptions() {
+        const launchExecutable = this.launch.pathToClaudeCodeExecutable;
+        const executable = launchExecutable !== undefined && launchExecutable !== "" ? launchExecutable : executableResolver();
         return {
             cwd: this.cwdPath,
-            env: { ...process.env },
-            pathToClaudeCodeExecutable: executableResolver(),
+            // The launch env holds ADDITIONS only; spreading process.env first keeps
+            // PATH/HOME and the user's own key alive (NATIVE_LAUNCH carries an empty
+            // env, so the native shape is exactly `{ ...process.env }`).
+            env: { ...process.env, ...this.launch.env },
+            // The `--settings` command-line tier (a JSON string) outranks the user's
+            // native settings.json env, so a provider-pinned launch rides it here
+            // (2026-10-04 F-B: without it the native env pins the endpoint).
+            ...(this.launch.settings !== undefined ? { settings: this.launch.settings } : {}),
+            // undefined (no local binary) leaves the key unset — bundled-payload
+            // mode lets the SDK spawn its own platform payload as the CLI.
+            ...(executable !== undefined ? { pathToClaudeCodeExecutable: executable } : {}),
             persistSession: true,
+            ...(this.launch.model !== undefined ? { model: this.launch.model } : {}),
             ...(this.claudeSessionId !== undefined ? { sessionId: this.claudeSessionId } : {}),
             ...(this.resumeSessionId !== undefined ? { resume: this.resumeSessionId } : {}),
             ...(this.canUseTool !== undefined ? { canUseTool: this.canUseTool } : {}),

package/agent-claude/dist/claude-launch.js

@@ -0,0 +1,101 @@
+/**
+ * claude-launch.ts — how a provider reaches the Claude Code CLI
+ * (2026-10-04 multi-provider rework).
+ *
+ * Claude Code is a single-provider harness: its own `settings.json` env block
+ * names exactly one `ANTHROPIC_BASE_URL` with one key, so the LIST of
+ * configured providers lives in `claude-providers.ts` instead. This module is
+ * the other end of that store: given the route the next turn will run (DSH's
+ * own per-session model selection, read by `claude-route.ts`), the resolved
+ * provider entry, and the resolved host binary, it produces the slice Task 9
+ * merges into the SDK's `Options`.
+ *
+ * The child's environment is the ONE channel a provider's variables enter the
+ * process through (spec §2.2) — AND, for a provider-pinned launch, the same env
+ * is re-carried as a `--settings`-tier JSON string so the command-line tier
+ * outranks the user's native `~/.claude/settings.json` env (2026-10-04 F-B).
+ * Concretely, the env keys are:
+ *
+ *   - `ANTHROPIC_BASE_URL` — always, from the entry (validation guarantees a
+ *     non-empty endpoint; an entry without one is not an entry).
+ *   - `ANTHROPIC_AUTH_TOKEN` for `authToken` (Bearer), `ANTHROPIC_API_KEY` for
+ *     `apiKey` (x-api-key) — exactly one, chosen by the entry's auth KIND, with
+ *     the stored value verbatim. The kind names the channel, so the variable is
+ *     present even when the value is empty ("keyed outside Super D"): the CLI
+ *     reads both names with `.trim() || undefined` (measured in
+ *     `@anthropic-ai/claude-agent-sdk` 2.1.263), so an empty value is unset
+ *     rather than a fabricated secret.
+ *   - `ANTHROPIC_MODEL` — the RAW route model id (`glm-5.2`), never the
+ *     selector's composite key (`glm/glm-5.2`); the composite is a DSH catalog
+ *     id and has no meaning on the wire.
+ *   - `ANTHROPIC_DEFAULT_{SONNET,OPUS,HAIKU}_MODEL` — ONLY for aliases the
+ *     entry actually declares, and never an empty-string one: an alias the user
+ *     did not write must not be invented, or the child silently answers on a
+ *     model they never chose.
+ *
+ * The returned env holds ADDITIONS only. The caller composes the child
+ * environment as `{ ...process.env, ...launch.env }` — the spread AFTER
+ * `process.env` is the contract, and it is why this function never reads or
+ * mutates `process.env` itself: it is a pure declaration, and the caller's
+ * precedence is what makes it effective. `NATIVE_LAUNCH` is the same
+ * declaration with nothing in it: `providerId: null` and an empty env, for a
+ * route no provider entry answers (a legacy bare-id selection, the native
+ * settings-only shape).
+ *
+ * The same reasoning makes `pathToClaudeCodeExecutable` optional and
+ * conditional: it is set only when a host binary was actually resolved, so an
+ * unresolved binary omits the key entirely and lets the SDK fall back to its
+ * bundled payload (spec §2.1) instead of spawning an empty path.
+ *
+ * @module agent-claude/claude-launch
+ */
+/** The launch for "no provider injection at all" (the native settings apply). */
+export const NATIVE_LAUNCH = { providerId: null, env: {} };
+/** The variable each auth kind authenticates through. */
+const AUTH_ENV = {
+    authToken: "ANTHROPIC_AUTH_TOKEN",
+    apiKey: "ANTHROPIC_API_KEY",
+};
+/** The alias slots an entry may declare, in catalog order. */
+const ALIAS_ENV = [
+    ["sonnet", "ANTHROPIC_DEFAULT_SONNET_MODEL"],
+    ["opus", "ANTHROPIC_DEFAULT_OPUS_MODEL"],
+    ["haiku", "ANTHROPIC_DEFAULT_HAIKU_MODEL"],
+];
+/**
+ * Turn one resolved provider into the SDK `Options` slice for one route.
+ *
+ * Pure: reads no file, no env, no clock, and spawns nothing. The provider id
+ * comes from the ENTRY (the caller resolves the entry BY `route.provider`, so
+ * the label and the injected data stay one fact); the model comes from the
+ * ROUTE, because that is what the session selected.
+ *
+ * @param route - the route the next turn runs (raw model half).
+ * @param entry - the provider entry that route resolved to.
+ * @param hostBinary - the resolved Claude Code binary, or `undefined` to let
+ *   the SDK use its bundled payload.
+ * @returns the env additions, the wire model, and the optional binary path.
+ */
+export function claudeLaunchFor(route, entry, hostBinary) {
+    const env = {
+        ANTHROPIC_BASE_URL: entry.baseUrl,
+        [AUTH_ENV[entry.auth.kind]]: entry.auth.value,
+        ANTHROPIC_MODEL: route.model,
+    };
+    // Declared aliases only: `undefined` means the entry never named that slot,
+    // and "" is not a model id — emitting either would invent a choice.
+    for (const [slot, name] of ALIAS_ENV) {
+        const value = entry.aliases?.[slot];
+        if (value !== undefined && value !== "")
+            env[name] = value;
+    }
+    return {
+        providerId: entry.id,
+        env,
+        settings: JSON.stringify({ env }),
+        model: route.model,
+        // Spread, not `pathToClaudeCodeExecutable: hostBinary`: an absent key must
+        // not exist at all, or it would ride a spread into Options as `undefined`.
+        ...(hostBinary !== undefined && hostBinary !== "" ? { pathToClaudeCodeExecutable: hostBinary } : {}),
+    };
+}