@vidge/dsh-agent-hub 0.1.0-rc1 → 0.1.0-rc3

package/README.md

@@ -64,19 +64,36 @@ runtime state — switching never requires a restart again.
 > can take the factory slot and re-mount that loop itself. Everything else in
 > that file is preserved byte for byte.
 
-### Requirements
+### Engine dependencies
 
-Only for the engines you actually use:
+Each engine's SDK is an **optional peer** — installing this plugin pulls in the
+router only. Add the engines you actually want:
 
-- **Claude Code** — the Claude Code CLI installed on the host. Credentials are
-  derived from dsh's own LLM provider configuration (see below); a CLI login is
-  a fallback, not a requirement.
+```sh
+# Claude Code
+pnpm add @anthropic-ai/claude-agent-sdk
+# Codex
+pnpm add @openai/codex
+# Pi
+pnpm add @earendil-works/pi-coding-agent
+```
+
+The `in-process` engine needs nothing beyond dsh itself, so a profile that
+installs no SDK at all still works.
+
+Selecting an engine whose SDK is missing fails that turn with a message naming
+the package to install; it never affects other sessions or engines.
+
+### Authentication
+
+Only for the engines you use:
+
+- **Claude Code** — credentials are derived from dsh's own LLM provider
+  configuration (see below); a CLI login is a fallback, not a requirement.
 - **Codex** — authenticated via `codex login`, or a `CODEX_API_KEY` entry.
 - **Pi** — authenticated the way `pi` expects: its own `~/.pi/agent/auth.json`,
   or the provider's API-key environment variable.
 
-The in-process engine needs nothing beyond dsh itself.
-
 ## Usage
 
 Choose an engine in the composer when starting a session. To change engines,

package/README.zh.md

@@ -55,18 +55,36 @@ dsh plugin --profile web add @vidge/dsh-agent-hub
 > `agent-loop` 行，以便路由器接管 factory 槽位并由它自己重新挂载该 loop。文件中
 > 其余内容逐字节保留。
 
-### 依赖要求
+### 引擎依赖
+
+各引擎的 SDK 都是**可选 peer 依赖**——安装本插件只会装入路由器本身。按需添加你
+真正要用的引擎：
+
+```sh
+# Claude Code
+pnpm add @anthropic-ai/claude-agent-sdk
+# Codex
+pnpm add @openai/codex
+# Pi
+pnpm add @earendil-works/pi-coding-agent
+```
+
+`in-process` 引擎除 dsh 本身外无任何额外要求，因此一个 SDK 都不装的 profile 仍可
+正常工作。
+
+选择了 SDK 未安装的引擎时，只有该次对话失败，并给出需要安装哪个包的提示；不会影响
+其他会话或其他引擎。
+
+### 认证
 
 仅针对你实际使用的引擎：
 
-- **Claude Code** —— 宿主机安装 Claude Code CLI。凭证由 dsh 自身的 LLM provider
-  配置派生（见下文）；CLI 登录只是兜底，不是必需。
+- **Claude Code** —— 凭证由 dsh 自身的 LLM provider 配置派生（见下文）；CLI 登录
+  只是兜底，不是必需。
 - **Codex** —— 通过 `codex login` 认证，或提供 `CODEX_API_KEY`。
 - **Pi** —— 按 pi 自己的方式认证：`~/.pi/agent/auth.json`，或对应 provider 的
   API-key 环境变量。
 
-in-process 引擎除 dsh 本身外无任何额外要求。
-
 ## 使用
 
 在 composer 中开始会话时选择引擎。要换引擎，开一个新会话——当前会话保持它的引擎，

package/lib/index.js

@@ -61,11 +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 { query as officialQuery } from "@anthropic-ai/claude-agent-sdk";
+import { canonicalHeader, headerEquals } from "@deepseek-ai/dsh-session";
 
 // src/engine-claude/mapping.ts
 import {
@@ -693,7 +692,21 @@ function invokedSkillNames(messages) {
 
 // src/engine-claude/agent.ts
 var PROVIDER = "claude-code";
+var claudeQueryPromise;
+async function loadClaudeQuery() {
+  claudeQueryPromise ??= import("@anthropic-ai/claude-agent-sdk").then(
+    (mod) => mod.query,
+    (error) => {
+      claudeQueryPromise = void 0;
+      throw new Error(
+        `the Claude Code engine requires "@anthropic-ai/claude-agent-sdk", which is not installed. Add it to this profile, or pick another engine for this session. (${String(error)})`
+      );
+    }
+  );
+  return claudeQueryPromise;
+}
 var NATIVE_MODEL_LABEL = "claude-code-native";
+var NATIVE_PROVIDER_LABEL = PROVIDER;
 function failureCode(subtype) {
   switch (subtype) {
     case "error_during_execution":
@@ -1024,19 +1037,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:
    *
-   * 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.
+   *  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.
    */
-  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" };
     }
@@ -1056,22 +1085,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() {
@@ -1087,7 +1182,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 = () => {
@@ -1098,7 +1195,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({
@@ -1116,6 +1212,7 @@ var ClaudeCodeAgent = class {
           diagnostics.push(line);
         }
       }, controller);
+      const officialQuery = await loadClaudeQuery();
       const query = officialQuery({ prompt, options });
       let finished = false;
       const chunkSeqs = [];
@@ -1606,7 +1703,13 @@ import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 var require2 = createRequire(import.meta.url);
 function codexCliEntrypoint() {
-  return join(dirname(require2.resolve("@openai/codex/package.json")), "bin", "codex.js");
+  try {
+    return join(dirname(require2.resolve("@openai/codex/package.json")), "bin", "codex.js");
+  } catch (error) {
+    throw new Error(
+      `the Codex engine requires "@openai/codex", which is not installed. Add it to this profile, or pick another engine for this session. (${String(error)})`
+    );
+  }
 }
 var AppServerClient = class _AppServerClient {
   process;
@@ -3609,7 +3712,14 @@ function resolveConfig3(config) {
   };
 }
 function piCliEntrypoint() {
-  const mainUrl = import.meta.resolve("@earendil-works/pi-coding-agent");
+  let mainUrl;
+  try {
+    mainUrl = import.meta.resolve("@earendil-works/pi-coding-agent");
+  } catch (error) {
+    throw new Error(
+      `the Pi engine requires "@earendil-works/pi-coding-agent", which is not installed. Add it to this profile, or pick another engine for this session. (${String(error)})`
+    );
+  }
   const root = dirname2(dirname2(fileURLToPath(mainUrl)));
   const pkg = JSON.parse(readFileSync(join2(root, "package.json"), "utf8"));
   const bin = pkg.bin;

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/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0-rc1",
+  "version": "0.1.0-rc3",
   "repository": "github:vidgewong/dsh-agent-hub",
   "type": "module",
   "main": "lib/index.js",
@@ -61,12 +61,8 @@
     "@anthropic-ai/sdk": "0.93.0",
     "@deepseek-ai/schemastery": "3.18.1"
   },
-  "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.220",
-    "@earendil-works/pi-coding-agent": "0.84.3",
-    "@openai/codex": "0.149.1"
-  },
   "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
     "@deepseek-ai/dsh-agent-loop": "0.1.1-rc.2",
@@ -77,11 +73,14 @@
     "@deepseek-ai/dsh-session-persistence": "0.1.1-rc.2",
     "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
     "@deepseek-ai/dsh-subprocess": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.1.1-rc.2"
+    "@deepseek-ai/dsh-timeout": "0.1.1-rc.2",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@openai/codex": "0.149.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "0.1.1-rc.2",
+    "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "@deepseek-ai/dsh-agent-loop": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.1.1-rc.2",
     "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
     "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
     "@deepseek-ai/dsh-client-store": "0.1.2-alpha.2",
@@ -93,6 +92,8 @@
     "@deepseek-ai/dsh-session-persistence-jsonl": "0.1.1-rc.2",
     "@deepseek-ai/dsh-subprocess-local": "0.1.1-rc.2",
     "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@openai/codex": "0.149.1",
     "@types/node": "^22.20.0",
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.8",
@@ -103,5 +104,16 @@
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.8",
     "yaml": "^2.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@openai/codex": {
+      "optional": true
+    }
   }
 }