super-dsh 0.1.10 → 0.1.11-b

package/README.md

@@ -14,7 +14,7 @@ the foreign store.
 ## Install
 
 ```bash
-dsh plugin --profile <name> add super-dsh@0.1.0
+dsh plugin --profile <name> add super-dsh@0.1.11
 ```
 
 That single package composes the whole line (`@pgmi-builds/superd-hub` plus the
@@ -22,17 +22,86 @@ six primary `@pgmi-builds/agent-*` packages and three OPTIONAL SDK halves).
 Restart the profile and the
 home under `<DSH_HOME>/agents/<label>/` on first boot.
 
+## Remote web access
+
+To use the same authenticated UI through a reverse proxy or LAN relay, enable
+this profile patch:
+
+```yaml
+- id: superd-web-trust
+  config:
+    trustAllHosts: true
+```
+
+This skips Host/Origin restrictions and enables browser ownership for every
+hostname. Native token-to-cookie login, cookie expiry, and authority binding
+remain in effect. The default is `false`, preserving declared-authority mode.
+It does not change the server's listening address: keep loopback behind Caddy
+and a LAN relay. The test launcher enables this mode without `--host` or
+`--trusted-host` and starts the relay on every test port, including 4999.
+
 ## Runtimes
 
 | Label | Runtime | Integration |
 |---|---|---|
 | OMP | OMP (`~/.omp`) | host `omp` binary over RPC (`omp --mode rpc`, NDJSON v1), lazy per session |
-| Codex | Codex CLI (`~/.codex`) | adapter world plugin |
+| Codex | Codex app-server (`~/.codex`) | CLI first, desktop core and lazy world-home fetch fallback |
 | Claude | Claude Code (`~/.claude`) | standalone adapter, joined by the hub |
 | Pi | pi coding agent (`~/.pi`) | in-process SDK |
 | Hermes | Hermes (`~/.hermes`) | gateway child |
 | Antigravity | agy SDK | Python bridge (`bridge/agy_bridge.py`) |
 
+### Foreign-agent Hub facility
+
+Super D sessions in Pi, OMP, and Codex can use the same `superd-hub` facility
+for agent roster/status, messaging, and shell execution. Tool descriptions,
+argument validation, receipts, and reply guidance come from the existing Hub.
+Replies wake the initiating session automatically; do not poll for them.
+
+Pi and OMP share one native extension. It is loaded incrementally on the first
+prompt, preserving normal extension discovery and native tools. Its per-session
+wrapper lives under the Super D world home (`hub-extensions`, mode 0600), with a
+session capability for a loopback-only HTTP listener. No global extension is
+installed in `~/.pi` or `~/.omp`. Some OMP versions present registered extension
+tools as devices: read `xd://superd-hub` for instructions and write action JSON
+to that device.
+
+Codex uses the official experimental app-server `dynamicTools` interface on
+new threads. Callbacks bind to that thread and the Super D session; existing
+native tools/plugins remain available. No global plugin is installed in
+`~/.codex`. Resuming a thread created through this integration restores its
+saved tool definition. Older threads without that definition need a new
+Super D conversation to gain the facility. A native Codex client resuming one
+of these threads does not supply Super D's callback host.
+
+Pi/OMP extension closures cannot transparently renew an already-loaded listener
+capability when the Hub row is unmounted/remounted. Restart Super D and resume
+the conversation after that operation; the tool reports this recovery path
+when its connection becomes unavailable. Whole-app restart/resume is tested.
+
+Draft creation and passive history viewing create no extension file, listener,
+or agent process. Closing a session invalidates its capability. Interrupted
+tool operations retain conservative upstream recovery guidance about unknown
+outcomes rather than encouraging blind retries.
+
+### Codex in 0.1.11
+
+Codex discovers the local OpenAI OAuth login as a read-only provider in the
+model selector. Selecting it explicitly overrides a third-party provider in the
+native config, while credentials and native configuration stay in the native
+home. Third-party providers remain selectable per session.
+
+The adapter prefers the installed desktop core, then the CLI, then the bundled
+0.160.0 core (`CODEX_BIN` overrides discovery). Desktop host browser and computer
+use services are separate and are not attached by this adapter.
+
+**Provider compatibility:** each provider defines its own message, reasoning,
+and encrypted-state formats. Selecting another provider does not guarantee
+that it can consume the existing session history. Successful continuation
+across endpoints is an observed convenience, not an adapter guarantee.
+The adapter surfaces provider errors; if the selected provider rejects the
+history, start a new session with that provider.
+
 ### Opt-in SDK halves
 
 Three runtimes also ship a preserved in-process SDK transport beside the primary

package/agent-agy/dist/agent.d.ts

@@ -35,6 +35,7 @@ import { type WithSystemHead } from "../../superd-hub/dist/index.js";
 /** The CLI stream transport the agent drives (SDK bridge moved to agent-agy-sdk). */
 export type LiveAgyClient = Pick<AgyCliClient, "conversationId" | "lastUsage" | "onThinkingDelta" | "onToolEvent" | "setApprovalHandler" | "turn" | "close"> & {
     setSystemMessageHandler?(handler: (text: string) => void): void;
+    interrupt?: () => Promise<void>;
 };
 /** Classify a bridge turn failure into the stable {message, code} UI chip. */
 export declare function classifyTurnError(error: unknown): {
@@ -119,6 +120,7 @@ export declare class AgyAgent implements Agent {
     /** Flush ONE parked follow-up as a fresh prompt (never submit while busy). */
     private flushFollowUps;
     private pendingThinking;
+    private stopInFlight?;
     /** Calls from this turn still lacking a result (SDK 0.1.17 exposes none). */
     private unpairedCalls;
     private armTurnDeadline;

package/agent-agy/dist/agent.js

@@ -129,9 +129,27 @@ export class AgyAgent {
                     this.closeStep();
                 this.commitStepStart();
                 const callId = ToolCallId(ev.id || `agy-${this.dashTurn}-${this.step}`);
+                const argumentsJson = ev.args || "{}";
+                // Advertisement-before-execution (validator invariant, 2026-10-04 dev3
+                // omp/hermes repair family): agy assistant frames carry only
+                // reasoning/text — never tool-call blocks — so every tool/call needs
+                // a minimal advertisement assistant frame first; arguments are copied
+                // verbatim into both frames (validator: lifecycle arguments ≡
+                // advertised, strict string equality).
+                const advertisement = createAssistantMessage({
+                    content: [{ type: "tool-call", id: callId, name: ev.name, arguments: argumentsJson }],
+                    source: {
+                        provider: this.options.provider ?? "agy",
+                        model: this.options.model ?? "",
+                    },
+                });
+                this.session.append("assistant/message", {
+                    turn: this.dashTurn, step: this.step,
+                    message: advertisement, stream: [],
+                }, { surfaceOp: "append" });
                 this.session.append("tool/call", {
                     turn: this.dashTurn, step: this.step,
-                    callId, name: ev.name, arguments: ev.args || "{}",
+                    callId, name: ev.name, arguments: argumentsJson,
                 });
                 this.unpairedCalls.push({ callId, name: ev.name });
             }
@@ -275,6 +293,8 @@ export class AgyAgent {
                 this.ensureStreamBridge().push({ type: "text-delta", index: full.length, text: chunk });
                 full += chunk;
             }
+            await this.stopInFlight;
+            this.stopInFlight = undefined;
             this.clearTurnDeadline();
             // SDK 0.1.17 streams ToolCall but NEVER ToolResult (verified live and
             // in SDK source: receive_chunks yields Thought/Text/ToolCall only; the
@@ -309,6 +329,8 @@ export class AgyAgent {
             this.flushFollowUps();
         }
         catch (error) {
+            await this.stopInFlight;
+            this.stopInFlight = undefined;
             this.clearTurnDeadline();
             this.abandonStreamBridge();
             const failure = classifyTurnError(error);
@@ -327,8 +349,10 @@ export class AgyAgent {
             if (this.turnOpen && this.step > 0)
                 this.closeStep();
             this.closeTurn({ kind: "error", error: failure });
+            this.cancelCause = null;
             this.markIdle();
             this.endActivity();
+            this.flushFollowUps();
         }
     }
     appendSystemNotice(text) {
@@ -434,6 +458,7 @@ export class AgyAgent {
         this.deliverPrompt(entry.message);
     }
     pendingThinking = [];
+    stopInFlight;
     /** Calls from this turn still lacking a result (SDK 0.1.17 exposes none). */
     unpairedCalls = [];
     armTurnDeadline() {
@@ -444,6 +469,13 @@ export class AgyAgent {
             if (!this.turnOpen)
                 return;
             trace(`turn deadline exceeded after ${AGY_TURN_DEADLINE_MS}ms — failing open turn`);
+            if (this.client.interrupt !== undefined) {
+                // Keep ownership until the old CLI stops. Its catch pairs unresolved
+                // calls and only then starts the next queued message.
+                this.cancelCause = { kind: "hook", reason: `agy turn deadline exceeded after ${AGY_TURN_DEADLINE_MS}ms` };
+                this.stopInFlight = this.client.interrupt().catch(error => trace(`deadline interrupt failed: ${String(error)}`));
+                return;
+            }
             this.abandonStreamBridge();
             if (this.step > 0)
                 this.closeStep();

package/agent-agy/dist/agy-cli-client.d.ts

@@ -15,6 +15,7 @@
  *
  * Same surface as AgyBridgeClient so AgyAgent needs no changes.
  */
+import type { ForeignHubBinding } from "@pgmi-builds/superd-hub/foreign-hub";
 import { type AgyAuthMode, type AgySettingsMutation } from "./agy-auth.js";
 export interface AgyCliOptions {
     /** Key or a resolver (onboarding-saved keys become visible at first spawn). */
@@ -49,6 +50,9 @@ export interface AgyCliOptions {
     authMode?: AgyAuthMode;
     spawnAttempts?: number;
     trace?: (...parts: unknown[]) => void;
+    hubBinding?: ForeignHubBinding;
+    hubStagingDirectory?: string;
+    prepareHub?: () => Promise<string | undefined>;
 }
 export type CliEvent = {
     event: "ready";
@@ -110,6 +114,9 @@ export declare class AgyCliClient {
     private dead;
     private conversationIdValue;
     private toolsSeen;
+    private hubPreparation?;
+    private hubSession?;
+    private prepare;
     onThinkingDelta?: (text: string) => void;
     onToolEvent?: (ev: {
         event: "tool_call";
@@ -163,5 +170,7 @@ export declare class AgyCliClient {
     private readyReceived;
     private expectReady;
     ping(): Promise<void>;
+    /** Stop one CLI execution, preserving its conversation and Hub capability. */
+    interrupt(): Promise<void>;
     close(): Promise<void>;
 }

package/agent-agy/dist/agy-cli-client.js

@@ -16,6 +16,9 @@
  * Same surface as AgyBridgeClient so AgyAgent needs no changes.
  */
 import { spawn } from "node:child_process";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { prepareAgyNativePlugin } from "@pgmi-builds/superd-hub/foreign-agy";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { authChildEnv, authSettingsMutation, nativeSettingsPath, } from "./agy-auth.js";
@@ -63,6 +66,24 @@ export class AgyCliClient {
     dead = false;
     conversationIdValue = "";
     toolsSeen = 0;
+    hubPreparation;
+    hubSession;
+    async prepare() {
+        if (this.dead)
+            throw new Error("agy client is closed");
+        this.hubPreparation ??= (async () => {
+            if (this.opts.hubBinding === undefined)
+                return;
+            this.hubSession = await (this.opts.prepareHub?.() ?? prepareAgyNativePlugin(this.opts.hubBinding, join(this.realHome(), ".gemini", "antigravity-cli"), this.opts.hubStagingDirectory, async (directory) => {
+                const exec = promisify(execFile);
+                await exec(this.opts.agyBin ?? "agy", ["plugin", "install", directory], { timeout: 60_000 });
+                await exec(this.opts.agyBin ?? "agy", ["plugin", "enable", "superd-hub"], { timeout: 60_000 });
+            }));
+        })();
+        await this.hubPreparation;
+        if (this.dead)
+            throw new Error("agy client is closed");
+    }
     onThinkingDelta;
     onToolEvent;
     setApprovalHandler(_handler) {
@@ -90,6 +111,8 @@ export class AgyCliClient {
     spawnCli() {
         if (this.child || this.dead)
             return;
+        this.pending.length = 0;
+        this.buffer = "";
         const mode = this.opts.authMode ?? "apiKey";
         // Only key mode patches settings (`modelProvider: "gemini"`); ADC and OAuth
         // need the DEFAULT backend, where that key must be ABSENT — the binary
@@ -107,8 +130,9 @@ export class AgyCliClient {
             "--input-format=stream-json", "--output-format=stream-json",
             "--disable-slash-commands",
         ];
-        if (this.opts.conversationId)
-            args.push(`--conversation=${this.opts.conversationId}`);
+        const conversationId = this.conversationIdValue || this.opts.conversationId;
+        if (conversationId)
+            args.push(`--conversation=${conversationId}`);
         if (this.opts.model)
             args.push(`--model=${this.opts.model}`);
         if (this.opts.effort)
@@ -127,6 +151,9 @@ export class AgyCliClient {
                 // ADC, the key for key mode, and the auto-update pin on EVERY mode.
                 // NO_PROXY keeps the dev3 loopback bridge reachable.
                 const env = { ...process.env, NO_PROXY: "127.0.0.1,localhost", ...authChildEnv(mode, key) };
+                delete env.SUPERD_HUB_SESSION;
+                if (this.hubSession !== undefined)
+                    env.SUPERD_HUB_SESSION = this.hubSession;
                 // No HOME override, ever: the settings we just maintained live at
                 // `$HOME/.gemini`, ADC at `$HOME/.config/gcloud`, and the sign-in token
                 // in the keyring — isolating HOME destroys all three. That was the
@@ -155,6 +182,8 @@ export class AgyCliClient {
         });
         child.on("exit", (code) => {
             this.child = undefined;
+            this.readyReceived = false;
+            this.buffer = "";
             // The CLI reports its refusals on stderr / as non-JSON stdout lines and
             // then exits non-zero. Those lines ARE the diagnosis ("--effort is not
             // supported for model …", "Eligibility check failed: …"), so the exit
@@ -206,6 +235,8 @@ export class AgyCliClient {
                 continue;
             }
             if (parsed.event === "init") {
+                if (typeof parsed.conversation_id === "string")
+                    this.conversationIdValue = parsed.conversation_id;
                 const init = parsed.init;
                 this.toolsSeen = Array.isArray(init?.tools) ? init.tools.length : 0;
                 this.dispatch({ event: "ready", tools: this.toolsSeen, permissionMode: init?.permission_mode });
@@ -262,7 +293,6 @@ export class AgyCliClient {
                     event: "tool_call", id, name,
                     args: JSON.stringify(su.tool_info?.parameters ?? {}),
                 });
-                this.onToolEvent?.({ event: "tool_call", id, name, args: JSON.stringify(su.tool_info?.parameters ?? {}) });
             }
             else if (su.state === "DONE" || su.state === "ERROR") {
                 const output = su.tool_info?.output ?? "";
@@ -271,10 +301,6 @@ export class AgyCliClient {
                     event: "tool_result", id, name, is_error: isError,
                     result: output || (isError ? "tool failed" : "[agy CLI reported no output summary]"),
                 });
-                this.onToolEvent?.({
-                    event: "tool_result", id, name, is_error: isError,
-                    result: output || (isError ? "tool failed" : "[agy CLI reported no output summary]"),
-                });
             }
         }
     }
@@ -298,6 +324,7 @@ export class AgyCliClient {
     }
     /** One turn. First call spawns the CLI (lazy per §14-i) and keeps it resident. */
     async *turn(text) {
+        await this.prepare();
         this.spawnCli();
         await this.expectReady();
         this.send({ event: "user", message: { content: text } });
@@ -343,13 +370,34 @@ export class AgyCliClient {
         }
     }
     async ping() {
+        await this.prepare();
         this.spawnCli();
         await this.expectReady();
     }
+    /** Stop one CLI execution, preserving its conversation and Hub capability. */
+    async interrupt() {
+        const child = this.child;
+        if (child === undefined)
+            return;
+        this.readyReceived = false;
+        const exited = new Promise(resolve => child.once("exit", () => resolve()));
+        child.kill("SIGTERM");
+        const timer = setTimeout(() => child.kill("SIGKILL"), 2000);
+        timer.unref();
+        try {
+            await exited;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async close() {
-        if (!this.child)
+        if (this.dead)
             return;
         this.dead = true;
+        await this.opts.hubBinding?.dispose();
+        if (!this.child)
+            return;
         const child = this.child;
         try {
             child.stdin.end();

package/agent-agy/dist/index.js

@@ -18,6 +18,7 @@
  * `sessionPersistence` service (hermes create/resume transaction shape).
  */
 import { realpathSync, statSync } from "node:fs";
+import { bindForeignHub } from "@pgmi-builds/superd-hub/foreign-hub";
 import { join } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
@@ -149,6 +150,8 @@ export class AgyProvider extends Service {
     hasAuthEvidence() {
         if (this.resolveApiKey() !== undefined)
             return true;
+        if (hasSigninCredential(this.opts.realHome ?? process.env.HOME ?? ""))
+            return true;
         return hasAdcEvidence(process.env, process.env.HOME ?? "");
     }
     /** Default model id: adapter state → native TUI default (slug-normalized) → catalog head. */
@@ -260,7 +263,8 @@ export class AgyProvider extends Service {
         trace(`create id=${id} spawnCwd=${spawnCwd}`);
         // Full-lazy (§14-i): construct the client (spawns NOTHING); the bridge
         // child materializes on the first real prompt.
-        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        const agentRef = {};
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort, bindForeignHub("agy", id, this.home, () => agentRef.current));
         const preparation = SessionPreparation.create(loopCtx.sessions.prepare(id, {
             ...(options.seed === undefined ? {} : { seed: options.seed }),
             ...(meta === undefined ? {} : { meta }),
@@ -273,7 +277,7 @@ export class AgyProvider extends Service {
             upsertSession(this.home, String(id), { conversationId: null, cwd: spawnCwd, createdAt: Date.now(), preset: null });
             handedOff = true;
             const agentOptions = await this.sessionAgentOptions(options.agentOptions);
-            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "startup", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "startup", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client), agentRef);
         }
         catch (error) {
             trace(`create ${id} THREW: ${String(error)}`);
@@ -318,7 +322,8 @@ export class AgyProvider extends Service {
                 }
                 return verified;
             })();
-        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        const agentRef = {};
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort, bindForeignHub("agy", id, this.home, () => agentRef.current), blank ? undefined : record.conversationId);
         let handle;
         let stored;
         let preparation;
@@ -340,7 +345,7 @@ export class AgyProvider extends Service {
             handle = undefined;
             handedOff = true;
             const agentOptions = await this.sessionAgentOptions(options.agentOptions);
-            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client), agentRef);
         }
         catch (error) {
             trace(`resume ${id} THREW: ${String(error)}`);
@@ -363,8 +368,8 @@ export class AgyProvider extends Service {
      * environment for free while the SDK is an opt-in extra. Auth-form selection
      * still rides the agy-auth ladder.
      */
-    createLiveClient(cwd, modelId, reasoningEffort) {
-        return new AgyCliClient(this.cliOptions(cwd, modelId, reasoningEffort));
+    createLiveClient(cwd, modelId, reasoningEffort, hubBinding, conversationId) {
+        return new AgyCliClient({ ...this.cliOptions(cwd, modelId, reasoningEffort), conversationId, hubBinding, hubStagingDirectory: join(this.home, "hub-native-agy") });
     }
     /**
      * The auth form this machine should use: an explicitly selected, actually
@@ -457,7 +462,7 @@ async function appendUnstoredSuffix(stored, session) {
     stored.storedCount += suffix.length;
 }
 /** Shared create/resume transaction (module-level: Cordis tracing proxy). */
-async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, session, client, parentAgent, source, opts, stored, runtimeInfo, onTurnDone) {
+async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, session, client, parentAgent, source, opts, stored, runtimeInfo, onTurnDone, agentRef) {
     const runtime = { ...runtimeInfo, onTurnDone };
     let detachSession;
     let detachAgent;
@@ -465,6 +470,7 @@ async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, sessi
     let idleExit;
     try {
         agent = new AgyAgent(loopCtx, id, agentOptions, session, client, () => idleExit?.(), runtime);
+        agentRef.current = agent;
         // Pin THIS session to the agy route (static resolution — synchronous).
         try {
             const selection = { provider: agentOptions.provider ?? "agy", model: agentOptions.model ?? "" };

package/agent-agy/package.json

@@ -30,7 +30,8 @@
     "@deepseek-ai/dsh-scope": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session-persistence": ">=0.1.5-0 <0.3.0-0",
-    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0"
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0",
+    "@pgmi-builds/superd-hub": "*"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -51,6 +52,9 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
+    "@pgmi-builds/superd-hub": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-typert-protocol": {
       "optional": true
     }

package/agent-claude/dist/adapter.js

@@ -4,8 +4,23 @@
  * The browser model selector never touches the Claude agent directly: it is an
  * RPC round-trip through the apiproxy, which reads `ctx.llm.listProviders /
  * listModels / resolveModel` to build the catalog. This adapter answers those
- * queries from the models Claude actually reported (`models.ts`) under the
- * single provider route `claude`.
+ * queries from TWO sources, one route each (the codex twin's one-route-per-
+ * provider shape, 2026-10-04 F-A rework):
+ *
+ *   - the fixed native route `claude` serves the OBSERVED catalog only (raw
+ *     ids — what the CLI itself reports, `models.ts`); its group stays "Claude".
+ *   - one route PER configured provider (route id = provider id) serves that
+ *     provider's curated `models[]` (RAW model ids, `claude-providers.ts`).
+ *
+ * The route/model composition therefore yields selection ids identical to the
+ * old composite keys (`deepseek/deepseek-flash`, `glm/glm-5.3`), so route seeds
+ * and logged selections keep working — the route half simply moved from the
+ * hardcoded `claude` to the provider id itself.
+ *
+ * The curated half follows the codex twin's rule exactly: the store is read
+ * LIVE on every call, so a panel edit is visible to the next catalog query
+ * without re-registration. An absent `worldHome` means observed-only (the
+ * settings-UI round trip and the unit tests).
  *
  * The route id must be `claude`, NOT `claude-code`: the upstream package
  * `@deepseek-ai/dsh-subagent-claude-code` already occupies the subagent
@@ -14,47 +29,107 @@
  * `stream` is never dispatched: Claude owns generation through its own SDK
  * thread, so the adapter only serves catalog/metadata queries. It throws
  * rather than fabricating a wire route the harness would misuse.
+ *
+ * @module agent-claude/adapter
  */
 import { LlmAdapter, LlmError, ReasoningEffortId, } from "@deepseek-ai/dsh-llm";
+import { readProviderStore } from "./claude-providers.js";
 import { readModelCatalog } from "./models.js";
-/** The one provider route every observed Claude model is served under. */
+/** The fixed native route every observed Claude model is served under. */
 export const CLAUDE_PROVIDER_ID = "claude";
-/** Human-readable provider name for selectors and diagnostics. */
+/** Human-readable provider name for the fixed native route. */
 const CLAUDE_PROVIDER_NAME = "Claude";
+/** Whether a provider may be registered as a model route. */
+export function routableProvider(entry) {
+    return entry.models.length > 0;
+}
+/** The route ids a store currently contributes to `ctx.llm`: the fixed `claude`
+ *  route first, then one route per provider that has models (store order). */
+export function routeIds(store) {
+    return [CLAUDE_PROVIDER_ID, ...store.providers.filter(routableProvider).map((entry) => entry.id)];
+}
 export class ClaudeLlmAdapter extends LlmAdapter {
-    providerInfo(_provider) {
-        return { id: CLAUDE_PROVIDER_ID, name: CLAUDE_PROVIDER_NAME };
+    worldHome;
+    /**
+     * @param worldHome - the world's DSH home, holding the curated provider
+     *   store in `<worldHome>/claude-providers.json`. Read on every call (the
+     *   codex twin's rule), so a panel edit is visible to the next catalog query
+     *   without re-registration. Absent = observed-only (the fixed `claude` route).
+     */
+    constructor(worldHome) {
+        super();
+        this.worldHome = worldHome;
+    }
+    /** The curated store entry a provider route id names, or `undefined`. */
+    curatedProvider(providerId) {
+        if (this.worldHome === undefined)
+            return undefined;
+        return readProviderStore(this.worldHome).providers.find((entry) => entry.id === providerId);
+    }
+    providerInfo(provider) {
+        if (provider === CLAUDE_PROVIDER_ID)
+            return { id: CLAUDE_PROVIDER_ID, name: CLAUDE_PROVIDER_NAME };
+        // The display name is the entry's label — for a provider folded in from the
+        // user's own settings that is its endpoint URL, the only name it supplies.
+        return { id: provider, name: this.curatedProvider(provider)?.label ?? provider };
     }
-    async listModels(_provider) {
-        return readModelCatalog().models.map((model) => ({
-            provider: CLAUDE_PROVIDER_ID,
+    async listModels(provider) {
+        if (provider === CLAUDE_PROVIDER_ID) {
+            // Observed catalog only, raw ids exactly as the CLI reported them.
+            return readModelCatalog().models.map((model) => ({
+                provider: CLAUDE_PROVIDER_ID,
+                id: model.id,
+                name: model.label,
+                ...(model.description === undefined ? {} : { description: model.description }),
+            }));
+        }
+        const entry = this.curatedProvider(provider);
+        if (entry === undefined)
+            return [];
+        return entry.models.map((model) => ({
+            provider,
             id: model.id,
-            name: model.label,
-            ...(model.description === undefined ? {} : { description: model.description }),
+            name: model.displayName ?? model.id,
         }));
     }
-    async resolveModel(_provider, model) {
-        const found = readModelCatalog().models.find((candidate) => candidate.id === model);
-        if (found === undefined) {
+    async resolveModel(provider, model) {
+        if (provider === CLAUDE_PROVIDER_ID) {
+            // Observed catalog (primary; unchanged behavior for the native route).
+            const found = readModelCatalog().models.find((candidate) => candidate.id === model);
+            if (found !== undefined) {
+                return {
+                    provider: CLAUDE_PROVIDER_ID,
+                    id: found.id,
+                    name: found.label,
+                    ...(found.description === undefined ? {} : { description: found.description }),
+                    // Only a positive window is real metadata: an absent or zero window must
+                    // never become `context: { contextWindow: 0 }`.
+                    ...(found.contextWindow !== undefined && found.contextWindow > 0
+                        ? { context: { contextWindow: found.contextWindow } }
+                        : {}),
+                    // The CLI's advertised effort levels become adapter-owned reasoning
+                    // efforts (omp thinking.efforts parity); the CLI names no default, so
+                    // none is invented.
+                    ...(found.reasoningEfforts !== undefined && found.reasoningEfforts.length > 0
+                        ? { reasoning: { efforts: found.reasoningEfforts.map((effort) => ({ id: ReasoningEffortId(effort), name: effort })) } }
+                        : {}),
+                };
+            }
             throw new LlmError(`Claude provider "${CLAUDE_PROVIDER_ID}" does not serve model "${model}"`, "MODEL_NOT_FOUND");
         }
-        return {
-            provider: CLAUDE_PROVIDER_ID,
-            id: found.id,
-            name: found.label,
-            ...(found.description === undefined ? {} : { description: found.description }),
-            // Only a positive window is real metadata: an absent or zero window must
-            // never become `context: { contextWindow: 0 }`.
-            ...(found.contextWindow !== undefined && found.contextWindow > 0
-                ? { context: { contextWindow: found.contextWindow } }
-                : {}),
-            // The CLI's advertised effort levels become adapter-owned reasoning
-            // efforts (omp thinking.efforts parity); the CLI names no default, so
-            // none is invented.
-            ...(found.reasoningEfforts !== undefined && found.reasoningEfforts.length > 0
-                ? { reasoning: { efforts: found.reasoningEfforts.map((effort) => ({ id: ReasoningEffortId(effort), name: effort })) } }
-                : {}),
-        };
+        const entry = this.curatedProvider(provider);
+        const curated = entry?.models.find((candidate) => candidate.id === model);
+        if (entry !== undefined && curated !== undefined) {
+            return {
+                provider,
+                id: curated.id,
+                name: curated.displayName ?? curated.id,
+                ...(curated.contextWindow !== undefined && curated.contextWindow > 0
+                    ? { context: { contextWindow: curated.contextWindow } }
+                    : {}),
+            };
+        }
+        throw new LlmError(`Claude provider "${provider}" does not serve model "${model}"`, "MODEL_NOT_FOUND");
     }
     stream(_options) {
         throw new LlmError("the Claude adapter does not stream: Claude owns generation through its SDK thread", "UNSUPPORTED_STREAM");