@vidge/dsh-agent-hub 0.1.0-rc2 → 0.1.0-rc4

package/lib/index.js

@@ -61,10 +61,10 @@ import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 import { SessionPreparation } from "@deepseek-ai/dsh-session";
 
 // src/engine-claude/agent.ts
-import { Inbox, agentEvents } from "@deepseek-ai/dsh-agent";
+import { Inbox, agentEvents, assembleContextFor } from "@deepseek-ai/dsh-agent";
 import { LlmError, createAssistantMessage, createUserMessage, errorChain } from "@deepseek-ai/dsh-llm";
 import { createScope } from "@deepseek-ai/dsh-scope";
-import { canonicalHeader } from "@deepseek-ai/dsh-session";
+import { canonicalHeader, headerEquals } from "@deepseek-ai/dsh-session";
 
 // src/engine-claude/mapping.ts
 import {
@@ -486,15 +486,21 @@ var SHARED_ENV_KEYS = [
 ];
 function inheritedLlmCredentials(backend) {
   const creds = {};
-  const take = (key) => {
+  const chosen = backend === "auto" ? BACKEND_ENV_GROUPS.find((group) => process.env[group.selector] !== void 0) : BACKEND_ENV_GROUPS.find((group) => group.id === backend);
+  for (const key of chosen?.keys ?? []) {
     const value = process.env[key];
     if (value !== void 0) creds[key] = value;
-  };
-  const chosen = backend === "auto" ? BACKEND_ENV_GROUPS.find((group) => process.env[group.selector] !== void 0) : BACKEND_ENV_GROUPS.find((group) => group.id === backend);
-  for (const key of chosen?.keys ?? []) take(key);
-  for (const key of SHARED_ENV_KEYS) take(key);
+  }
   return creds;
 }
+function inheritedSharedEnv() {
+  const shared = {};
+  for (const key of SHARED_ENV_KEYS) {
+    const value = process.env[key];
+    if (value !== void 0) shared[key] = value;
+  }
+  return shared;
+}
 function claudeChildEnv(spec) {
   const derived = spec.providerEnv;
   const selected = derived ?? inheritedLlmCredentials(spec.backend ?? "auto");
@@ -506,6 +512,7 @@ function claudeChildEnv(spec) {
   }
   return {
     ...env,
+    ...inheritedSharedEnv(),
     ...selected,
     ...spec.model === void 0 ? {} : { ANTHROPIC_MODEL: spec.model },
     ...spec.env
@@ -606,6 +613,7 @@ function readProviderProfile(ctx, provider) {
 }
 function mapRouteToEnv(provider, profile, key) {
   const headers = profile.headers ?? {};
+  const extra = profile.childEnv ?? {};
   if (BEDROCK_PROVIDER_IDS.has(provider)) {
     return {
       CLAUDE_CODE_USE_BEDROCK: "1",
@@ -615,13 +623,15 @@ function mapRouteToEnv(provider, profile, key) {
       // explicit and the gateway ignores it; without one the client refuses to
       // construct. A route pointing at a corporate gateway has no real region,
       // so this is a placeholder the endpoint override makes irrelevant.
-      ..."AWS_REGION" in headers ? {} : { AWS_REGION: "us-east-1" }
+      ..."AWS_REGION" in headers ? {} : { AWS_REGION: "us-east-1" },
+      ...extra
     };
   }
   if (ANTHROPIC_PROVIDER_IDS.has(provider) || profile.api === "anthropic-messages") {
     return {
       ANTHROPIC_AUTH_TOKEN: key,
-      ...profile.baseURL === void 0 ? {} : { ANTHROPIC_BASE_URL: profile.baseURL }
+      ...profile.baseURL === void 0 ? {} : { ANTHROPIC_BASE_URL: profile.baseURL },
+      ...extra
     };
   }
   return void 0;
@@ -644,9 +654,10 @@ async function deriveProviderEnv(ctx, provider) {
   if (key === void 0 || key === "") return void 0;
   const env = mapRouteToEnv(provider, profile, key);
   if (env === void 0) return void 0;
+  const extra = Object.keys(profile.childEnv ?? {});
   return {
     env,
-    diagnostic: `claude-code: routing to dsh provider "${provider}"${profile.baseURL === void 0 ? "" : ` at ${profile.baseURL}`} (credential ${ref})`
+    diagnostic: `claude-code: routing to dsh provider "${provider}"${profile.baseURL === void 0 ? "" : ` at ${profile.baseURL}`} (credential ${ref})${extra.length === 0 ? "" : `; route env ${extra.join(", ")}`}`
   };
 }
 
@@ -706,6 +717,7 @@ async function loadClaudeQuery() {
   return claudeQueryPromise;
 }
 var NATIVE_MODEL_LABEL = "claude-code-native";
+var NATIVE_PROVIDER_LABEL = PROVIDER;
 function failureCode(subtype) {
   switch (subtype) {
     case "error_during_execution":
@@ -1036,19 +1048,35 @@ var ClaudeCodeAgent = class {
     return true;
   }
   /**
-   * Resolve the model one query runs on, session choice first.
+   * Resolve the model one query runs on, per-session selection first.
+   *
+   * The layers, in precedence order:
+   *
+   *  1. **The `agent/request` waterfall.** This is the seam the dsh model
+   *     picker actually drives. api-proxy installs `installModelSelection` on
+   *     every agent's own context, which listens on `system-prompt/assemble`
+   *     to *snapshot* the session's selection and on `agent/request` to *apply*
+   *     the snapshot — two stages, so a mid-turn switch lands on a later step
+   *     rather than splitting the prompt from the route. Both must be
+   *     dispatched, and in that order: the request listener reads
+   *     `selection.assembled`, which only the assemble listener writes, so
+   *     dispatching the request waterfall alone yields nothing.
+   *  2. `AgentOptions.model` — the create-time seed.
+   *  3. `agentDefaultModel` — the global default.
+   *  4. The deployment's pinned `config.model`.
+   *  5. Nothing, leaving the CLI on its own model.
    *
-   * The web surface sets `AgentOptions.model` when a session picks a model, and
-   * `agentDefaultModel` holds the global default; reading both is what makes
-   * the dsh model picker mean something for this engine. The service is
-   * optional — a minimal profile may not mount it — so it is resolved through
-   * `ctx.get` rather than `inject`, and a faulting provider degrades to the
-   * next layer instead of failing the turn.
+   * Every layer is optional and every failure degrades to the next one: a
+   * minimal profile mounts neither service, and a listener that throws must
+   * cost this session its turn no more than a missing service does.
    *
+   * @param signal - the step's cancellation signal, forwarded to prompt assembly.
    * @returns the chosen id (undefined leaves the CLI on its own default),
    * its provider route, and the layer that chose it.
    */
-  resolveModel() {
+  async resolveModel(signal) {
+    const selected = await this.selectionFromWaterfall(signal);
+    if (selected !== void 0) return selected;
     if (this.options.model !== void 0) {
       return { model: this.options.model, provider: this.options.provider, source: "session" };
     }
@@ -1068,22 +1096,88 @@ var ClaudeCodeAgent = class {
     }
     return { model: void 0, provider: void 0, source: "native" };
   }
-  /** Model label recorded in the request header for one lifecycle. */
-  modelLabel() {
-    return this.resolveModel().model ?? NATIVE_MODEL_LABEL;
+  /**
+   * Ask the host what this session is routed to, through the two waterfalls
+   * that carry a per-session selection.
+   *
+   * The seed handed to `agent/request` is the same one the in-process loop
+   * seeds with — the agent's own options — so a host that installs no listener
+   * gets its own answer back and this returns undefined, leaving the layers
+   * below untouched. A listener that replaces it wins.
+   *
+   * The assemble pass is dispatched for its *side effect* on the selection
+   * state; its returned prompt is discarded, because Claude Code builds its own
+   * prompt and dsh's assembly never reaches the child. That makes this a real
+   * (if small) cost per step: the host's prompt providers run and their output
+   * is dropped. It is the price of reaching a selection whose only publisher is
+   * that listener pair.
+   *
+   * @param signal - the step's cancellation signal.
+   * @returns the selection when a listener supplied one, else undefined.
+   */
+  async selectionFromWaterfall(signal) {
+    const phase = this.phase;
+    if (phase.kind !== "running") return void 0;
+    const { turn, step } = phase;
+    const seed = {
+      provider: this.options.provider ?? "",
+      model: this.options.model ?? ""
+    };
+    try {
+      const systemPrompt = this.loopCtx.get("systemPrompt");
+      if (systemPrompt !== void 0) {
+        await systemPrompt.assemble(assembleContextFor(this, signal));
+      }
+      const proposed = await this.dispatch.waterfall(
+        "agent/request",
+        { turn, step, signal },
+        () => Promise.resolve(seed)
+      );
+      if (proposed.model === "" || proposed.provider === "") return void 0;
+      if (proposed.provider === seed.provider && proposed.model === seed.model) return void 0;
+      return { model: proposed.model, provider: proposed.provider, source: "selection" };
+    } catch (error) {
+      this.ctx.logger.warn("claude-code: per-session model selection unavailable: %s", error);
+      return void 0;
+    }
   }
-  /** Append the request header snapshot once per loop instance. */
-  assertRequestHeader() {
-    if (this.requestHeaderLogged) return;
+  /**
+   * Append the request header, and re-append it whenever the route changes.
+   *
+   * The provider written here is the **real** dsh route (`copilot-proxy`,
+   * `amazon-bedrock`, …), not this engine's name. That is not cosmetic:
+   * api-proxy re-reads this field on every read as "the model this session is
+   * on", resolves it against `ctx.llm.listProviders()`, and locks the composer
+   * when the name is not a registered provider — so writing the engine name
+   * here made every session demand a fresh model pick after each turn. The
+   * engine that ran the turn is recorded in the `*.loop-engine.json` sidecar,
+   * which is where per-session engine provenance already lives.
+   *
+   * Re-logging on change mirrors the in-process loop: the header is the log's
+   * record of what each request ran under, so a mid-session model switch has to
+   * produce a new snapshot or the log misattributes every later turn.
+   *
+   * @param selected - the model resolved for the step about to run.
+   */
+  noteRequestHeader(selected) {
     const header = canonicalHeader({
-      config: { provider: PROVIDER, model: this.modelLabel() }
+      config: {
+        provider: selected.provider ?? NATIVE_PROVIDER_LABEL,
+        model: selected.model ?? NATIVE_MODEL_LABEL
+      }
     });
     const baseline = this.session.requestHeader();
-    this.session.append("request/header", {
-      header,
-      reason: baseline === void 0 ? "initial" : "resume"
-    });
-    this.requestHeaderLogged = true;
+    if (!this.requestHeaderLogged) {
+      this.session.append("request/header", {
+        header,
+        reason: baseline === void 0 ? "initial" : "resume"
+      });
+      this.requestHeaderLogged = true;
+      return;
+    }
+    if (baseline === void 0 || !headerEquals(baseline, header)) {
+      this.session.append("request/header", { header, reason: "change" });
+    }
   }
   /** Run one Claude Code query for the current step and map its transcript into the session log. */
   async step() {
@@ -1099,7 +1193,9 @@ var ClaudeCodeAgent = class {
     if (prompt.length === 0) {
       throw new Error(`agent "${this.id}": cannot derive a prompt from an empty session log`);
     }
-    this.assertRequestHeader();
+    const selected = await this.resolveModel(signal);
+    signal.throwIfAborted();
+    this.noteRequestHeader(selected);
     signal.throwIfAborted();
     const controller = new AbortController();
     const cancel = () => {
@@ -1110,7 +1206,6 @@ var ClaudeCodeAgent = class {
     signal.addEventListener("abort", cancel, { once: true });
     const diagnostics = [];
     try {
-      const selected = this.resolveModel();
       const derived = await deriveProviderEnv(this.loopCtx, selected.provider);
       if (derived !== void 0) diagnostics.push(derived.diagnostic);
       const options = claudeQueryOptions({

package/lib/types/engine-claude/agent.d.ts

@@ -93,23 +93,72 @@ export declare class ClaudeCodeAgent implements Agent {
     /** Open one turn before claiming its first proposed step. */
     private turn;
     /**
-     * Resolve the model one query runs on, session choice first.
+     * Resolve the model one query runs on, per-session selection first.
      *
-     * The web surface sets `AgentOptions.model` when a session picks a model, and
-     * `agentDefaultModel` holds the global default; reading both is what makes
-     * the dsh model picker mean something for this engine. The service is
-     * optional — a minimal profile may not mount it — so it is resolved through
-     * `ctx.get` rather than `inject`, and a faulting provider degrades to the
-     * next layer instead of failing the turn.
+     * The layers, in precedence order:
      *
+     *  1. **The `agent/request` waterfall.** This is the seam the dsh model
+     *     picker actually drives. api-proxy installs `installModelSelection` on
+     *     every agent's own context, which listens on `system-prompt/assemble`
+     *     to *snapshot* the session's selection and on `agent/request` to *apply*
+     *     the snapshot — two stages, so a mid-turn switch lands on a later step
+     *     rather than splitting the prompt from the route. Both must be
+     *     dispatched, and in that order: the request listener reads
+     *     `selection.assembled`, which only the assemble listener writes, so
+     *     dispatching the request waterfall alone yields nothing.
+     *  2. `AgentOptions.model` — the create-time seed.
+     *  3. `agentDefaultModel` — the global default.
+     *  4. The deployment's pinned `config.model`.
+     *  5. Nothing, leaving the CLI on its own model.
+     *
+     * Every layer is optional and every failure degrades to the next one: a
+     * minimal profile mounts neither service, and a listener that throws must
+     * cost this session its turn no more than a missing service does.
+     *
+     * @param signal - the step's cancellation signal, forwarded to prompt assembly.
      * @returns the chosen id (undefined leaves the CLI on its own default),
      * its provider route, and the layer that chose it.
      */
     private resolveModel;
-    /** Model label recorded in the request header for one lifecycle. */
-    private modelLabel;
-    /** Append the request header snapshot once per loop instance. */
-    private assertRequestHeader;
+    /**
+     * Ask the host what this session is routed to, through the two waterfalls
+     * that carry a per-session selection.
+     *
+     * The seed handed to `agent/request` is the same one the in-process loop
+     * seeds with — the agent's own options — so a host that installs no listener
+     * gets its own answer back and this returns undefined, leaving the layers
+     * below untouched. A listener that replaces it wins.
+     *
+     * The assemble pass is dispatched for its *side effect* on the selection
+     * state; its returned prompt is discarded, because Claude Code builds its own
+     * prompt and dsh's assembly never reaches the child. That makes this a real
+     * (if small) cost per step: the host's prompt providers run and their output
+     * is dropped. It is the price of reaching a selection whose only publisher is
+     * that listener pair.
+     *
+     * @param signal - the step's cancellation signal.
+     * @returns the selection when a listener supplied one, else undefined.
+     */
+    private selectionFromWaterfall;
+    /**
+     * Append the request header, and re-append it whenever the route changes.
+     *
+     * The provider written here is the **real** dsh route (`copilot-proxy`,
+     * `amazon-bedrock`, …), not this engine's name. That is not cosmetic:
+     * api-proxy re-reads this field on every read as "the model this session is
+     * on", resolves it against `ctx.llm.listProviders()`, and locks the composer
+     * when the name is not a registered provider — so writing the engine name
+     * here made every session demand a fresh model pick after each turn. The
+     * engine that ran the turn is recorded in the `*.loop-engine.json` sidecar,
+     * which is where per-session engine provenance already lives.
+     *
+     * Re-logging on change mirrors the in-process loop: the header is the log's
+     * record of what each request ran under, so a mid-session model switch has to
+     * produce a new snapshot or the log misattributes every later turn.
+     *
+     * @param selected - the model resolved for the step about to run.
+     */
+    private noteRequestHeader;
     /** Run one Claude Code query for the current step and map its transcript into the session log. */
     private step;
 }

package/lib/types/engine-claude/provider-env.d.ts

@@ -13,7 +13,9 @@
  *
  * Only the route's *transport* is derived. Which model runs is settled earlier
  * by the agent's own resolution (session choice, then `agentDefaultModel`), and
- * is passed in rather than re-read here.
+ * is passed in rather than re-read here. A route may also carry a `childEnv`
+ * map, which is not derived at all but forwarded verbatim — the escape hatch
+ * for what a protocol mapping cannot express.
  *
  * Everything is resolved per call. `credentials.resolve` is contractually a
  * per-call read — the store layers process env over `~/.dsh/.credentials.yaml`

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0-rc2",
+  "version": "0.1.0-rc4",
   "repository": "github:vidgewong/dsh-agent-hub",
   "type": "module",
   "main": "lib/index.js",