dsh-llm-fallbacks 0.3.5 → 0.4.0

package/dist/state.d.ts

@@ -44,6 +44,46 @@ export interface PendingSwitch {
     role: string;
     reason: FallbackSwitchReason;
 }
+/**
+ * One plugin-originated subagent switch the host allowlist blocked (plan
+ * dsh-012-subagent-routing T3; spec D1). The intersection of the resolved
+ * candidates with the effective allowlist was empty while the 0.3.5 walk
+ * would have switched — the attempt is recorded in-memory only (issue #52:
+ * no durable session write) for the Subagents card warning (spec D4/T5).
+ */
+export interface BlockedSwitchAttempt {
+    /** Epoch ms when the switch was blocked. */
+    at: number;
+    /** The route the 0.3.5 walk would have switched to (exact provider+model). */
+    route: {
+        provider: string;
+        model: string;
+    };
+    /** The failure reason that triggered the would-be switch. */
+    reason: FallbackSwitchReason;
+}
+/**
+ * How the effective subagent chain head was chosen (plan dsh-012-subagent-routing
+ * T5 / T2 M3). Lives on a per-agent map (mirrors {@link BlockedSwitchAttempt}),
+ * not on {@link AgentFallbackState} — recording a head is not a switch intent
+ * (F-004: the fallback store grows only inside `commit()`).
+ */
+export type ChainHeadSource = 'authorized' | 'injected';
+/**
+ * The effective chain head for one subagent, plus the source label the
+ * Subagents card renders (spec D4). In-memory only (issue #52).
+ */
+export interface EffectiveChainHead {
+    /** Epoch ms when this head was recorded (recency for the card snapshot). */
+    at: number;
+    /** Exact provider+model of the effective chain head. */
+    route: {
+        provider: string;
+        model: string;
+    };
+    /** `authorized` = host spawn preserved; `injected` = plugin role-inject. */
+    source: ChainHeadSource;
+}
 /** The current (turn, step)'s failed-model set and switch budget (spec §5.1). */
 export interface StepFailures {
     turn: number;

package/dist/subagent-policy.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Subagent routing policy reader (plan dsh-012-subagent-routing T1; spec D1).
+ *
+ * Pure, host-free module: plain data in, results out. It resolves the
+ * effective subagent model-selection policy from two snapshots the wiring
+ * layer extracts from the host:
+ *
+ * 1. the session's `subagent/model-selection-policy` event payload, read
+ *    STRUCTURALLY — the upstream reader is not published from
+ *    `@deepseek-ai/dsh-tool-subagent` and throws on malformed payloads,
+ *    which is incompatible with the fail-closed no-throw requirement;
+ * 2. the host settings service snapshot (`SubagentModelSelectionConfig`
+ *    `.current()`), typed via a type-only peer import that is erased at emit.
+ *
+ * The session event wins over settings (ADR read order). Anything present but
+ * unreadable yields `'unprovable'` (fail-closed): callers must not emit a
+ * plugin-originated route they cannot prove is allowed. This module never
+ * throws.
+ *
+ * @module dsh-llm-fallbacks/subagent-policy
+ */
+import type { SubagentModelSelectionSettings } from '@deepseek-ai/dsh-tool-subagent/model-selection-settings';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Host-recorded route policy for a model-selectable subagent session.
+         * The payload shape mirrors upstream exactly, so a future published
+         * upstream augmentation merges identically. Read structurally by this
+         * plugin; never written here.
+         */
+        'subagent/model-selection-policy': {
+            /** Exact routes this session may select explicitly for a child. */
+            allowedModels: {
+                provider: string;
+                model: string;
+            }[];
+        };
+    }
+}
+/** One exact child LLM route (structural twin of upstream `AllowedModelRoute`). */
+export type PolicyRoute = {
+    readonly provider: string;
+    readonly model: string;
+};
+/**
+ * Effective subagent routing policy for one session.
+ *
+ * - `disabled`: host policy off or absent — selection matches pre-policy
+ *   (0.3.5) behavior.
+ * - `enabled`: an allowlist is proven; plugin-originated routes must stay
+ *   inside it.
+ * - `unprovable`: the policy is on but unreadable (malformed event payload,
+ *   or enabled settings with a malformed route list) — fail-closed; no
+ *   plugin-originated route may be emitted.
+ */
+export type EffectivePolicy = {
+    readonly state: 'disabled';
+} | {
+    readonly state: 'enabled';
+    readonly allowedModels: readonly PolicyRoute[];
+} | {
+    readonly state: 'unprovable';
+};
+/** Outcome of the structural session-event read. */
+export type SessionPolicyEventRead = {
+    readonly ok: true;
+    readonly allowedModels: PolicyRoute[];
+} | {
+    readonly ok: false;
+    readonly present: true;
+} | {
+    readonly ok: false;
+    readonly present: false;
+};
+/** Settings snapshot consumed by the reader — plain structural data, no host objects. */
+export type PolicySettings = {
+    readonly enabled: boolean;
+    readonly allowedModels: readonly PolicyRoute[];
+};
+/** Assignability guard: fails typecheck if the peer's settings shape drifts from the reader's snapshot contract. */
+type AssertSettingsShape<T extends PolicySettings> = T;
+/**
+ * The host settings service snapshot type, re-exported from the published
+ * peer subpath (type-only). Wiring reads the service's `current()` and passes
+ * the result in as plain data; if upstream drifts, this alias fails typecheck
+ * instead of drifting silently at runtime (plan ADR).
+ */
+export type PeerSettingsSnapshot = AssertSettingsShape<SubagentModelSelectionSettings>;
+/**
+ * Structurally read the session's `subagent/model-selection-policy` event.
+ * Never throws: a present-but-malformed payload is reported, not raised.
+ *
+ * Recency (qc fix wave S-asym — deliberate asymmetry, both sides mirror
+ * upstream): this read takes the FIRST occurrence, exactly like the upstream
+ * reader's `.find` — the host writes the policy event at most once per
+ * session (its ensure-guard checks the reader before appending), so a second
+ * occurrence would already be off-contract. The re-emittable
+ * `model/selection` log is the opposite: `authorized-route.ts`
+ * `lastModelSelection` scans backwards because upstream's selection
+ * projection folds to the newest entry.
+ *
+ * @param events - plain event descriptors (`type` + optional `data`) captured
+ *   from the session by the wiring layer.
+ * @returns the detached route list when the event is present and valid;
+ *   otherwise a presence flag distinguishing "no policy event" (pure
+ *   inheritance path) from "policy event unreadable" (fail-closed).
+ */
+export declare function readSessionPolicyEvent(events: readonly {
+    type: string;
+    data?: unknown;
+}[]): SessionPolicyEventRead;
+/**
+ * Resolve the effective policy from the session-event read and the settings
+ * snapshot. The session event wins over settings (ADR read order).
+ * Fail-closed: a present-but-malformed event, or enabled settings with a
+ * malformed route list, yields `'unprovable'`. Never throws.
+ *
+ * @param event - result of {@link readSessionPolicyEvent}.
+ * @param settings - settings service snapshot, or undefined when the host
+ *   does not compose the service.
+ */
+export declare function effectivePolicy(event: SessionPolicyEventRead, settings: PolicySettings | undefined): EffectivePolicy;
+export {};

package/dist/virtual-adapter.d.ts

@@ -31,6 +31,7 @@
  * @module dsh-llm-fallbacks/virtual-adapter
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { LlmAdapter, type GenerateOptions, type LlmImageRequestPricing, type LlmModelInfo, type LlmResolvedModelInfo, type LlmRuntime, type StreamChunk } from '@deepseek-ai/dsh-llm';
 import type { FallbacksConfig } from './config.ts';
 /** Provider route of the virtual adapter (exact string, spec lock). */
 export declare const FALLBACKS_PROVIDER = "FallbacksChain";
@@ -78,6 +79,54 @@ export declare function firstDispatchableExactHead(chain: readonly string[]): Ef
  * @param modelDisplayName - catalog/resolved name; falls back to the id.
  */
 export declare function pickerDisplayName(config: FallbacksConfig, now?: Date, modelDisplayName?: string): string;
+/**
+ * The virtual adapter (P1/P3). `stream()` is a thin head-delegate, never a
+ * second routing engine: no chain walk, cooldown, caps, revert bookkeeping,
+ * or state writes live here — those stay in the `agent/request` /
+ * `agent/request-error` listeners. Exported so the defensive guard paths
+ * the registration lifecycle cannot reach (a registered route whose `llm`
+ * vanished mid-teardown) stay unit-testable by direct construction.
+ */
+export declare class FallbacksChainAdapter extends LlmAdapter {
+    private readonly readConfig;
+    private readonly getLlm;
+    constructor(readConfig: () => FallbacksConfig, getLlm: () => LlmRuntime | undefined);
+    /** Minimal honest descriptor (P3) — the provider route IS the display name. */
+    providerInfo(provider: string): {
+        id: string;
+        name: string;
+    };
+    /** Advisory catalog: one virtual row; `name` is the live picker label. */
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * Proxy the current effective head's model metadata when resolvable (P3):
+     * modalities/context-window/reasoning follow the head — the truthful
+     * answer for the CURRENT head. Permissive default otherwise; never throws.
+     */
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * Route-accurate image pricing (0.1.2 adoption): the virtual row has no
+     * pricing of its own — the virtual `provider`/`model` arguments are
+     * intentionally ignored. Resolves the SAME effective head `stream()`
+     * dispatches and delegates through the runtime lookup, so the token
+     * meter gets exactly the answer the concrete route's adapter would give
+     * (including `undefined`). Never throws: an unresolvable head, a
+     * vanished `llm`, or a throwing delegate degrades to `undefined` — the
+     * token meter's neutral estimate.
+     */
+    imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;
+    /**
+     * Thin head-delegate (P1): resolve the effective chain head and dispatch
+     * that REAL pair through the host LLM runtime. Throws an explicit
+     * `LlmError` only when there is no real pair to delegate to: an empty
+     * effective chain, an undispatchable head (wildcard / malformed /
+     * self-route — the recursion guard), or a vanished `llm` runtime. The
+     * runtime normalizes the throw into a terminal error finish chunk, so the
+     * documented listener-order degradation stays graceful instead of a hard
+     * outage.
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
 /**
  * Install the virtual adapter registration lifecycle (P2).
  *

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.3.5",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,7 +32,6 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-settings-plugins",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-conversation",
@@ -60,25 +59,30 @@
     "use-sync-external-store": "^1.6.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^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-ui-conversation": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.1-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.2-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0"
   },
   "devDependencies": {

package/scripts/build-client.ts

@@ -2,8 +2,9 @@
  * Client bundle build: emits the closure-factory CJS artifact the dsh web
  * loader consumes — `window.__ModuleLoader__.load({ id: 'dsh-llm-fallbacks',
  * factory: (require) => { … return module.exports; } })`. Externals resolve
- * through the loader module table (platform seed entries + the documented
- * `@deepseek-ai/dsh-client-runtime/client` exemption); everything else
+ * through the loader module table (the platform seed entries — in 0.1.2 the
+ * former runtime exemption is folded into the `@deepseek-ai/dsh-client-store`
+ * platform module, the client half's one VALUE import); everything else
  * inlines.
  *
  * Build tool: `tsdown` (rolldown) — the same tool the dsh host itself uses
@@ -47,9 +48,12 @@ const OUT_FILE = 'index.js'
 
 /**
  * Frozen loader module table (dsh mechanism-guide): the plan-documented
- * composition = PLATFORM_MODULES (7 entries, `web/src/platform.ts:8-12`)
- * + the PRELOADED_CLIENT_EXTERNALS (`@deepseek-ai/dsh-client-runtime/client`,
- * `web/src/platform.ts:15-17`). rc.8 dropped `dsh-client-web-react` (deleted
+ * composition = PLATFORM_MODULES (8 entries in 0.1.2, `web/src/platform.ts:8-15`
+ * — the old runtime `./client` exemption became the
+ * `@deepseek-ai/dsh-client-store` platform module, so the store VALUE import
+ * stays external and resolves from the host loader table) + the
+ * PRELOADED_CLIENT_EXTERNALS (empty in 0.1.2, `web/src/platform.ts:16-17`).
+ * rc.8 dropped `dsh-client-web-react` (deleted
  * package — the uSES bridge is vendored in `src/client/use-snapshot.ts`),
  * `dsh-client-ui-attachment` and `dsh-client-schema-form` from the platform
  * table. `@deepseek-ai/cordis` is the in-box cordis framework (dsh-advisor
@@ -63,9 +67,9 @@ export const CLIENT_EXTERNALS: readonly string[] = [
   'react-dom',
   'react-dom/client',
   '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-store',
   '@deepseek-ai/dsh-client-ui-slots',
   '@deepseek-ai/dsh-client-ui-primitives',
-  '@deepseek-ai/dsh-client-runtime/client',
 ]
 
 /**