dsh-llm-fallbacks 0.7.0 → 0.8.0

package/dist/virtual-adapter.d.ts

@@ -1,54 +1,38 @@
 /**
- * Virtual `FallbacksChain/Auto` LLM adapter (plan fallbacks-virtual-chain
- * Task 1, technical pins P1–P3; PR #62 feedback round): a mount-only
- * catalog row that makes the configured effective chain selectable as the
- * session **primary** in the host model picker, without patching dsh or
- * dsh-TUI (web and TUI share the adapter catalog).
+ * Virtual `FallbacksChain` LLM adapter (named virtual chains, plan
+ * named-virtual-chains T2): one provider carrying N model rows — ONE per
+ * named chain, the row id BEING the chain id (picker selection is
+ * `FallbacksChain/<chain id>`), without patching dsh or dsh-TUI.
  *
- * Wiring (P2): `installFallbacksAdapter` installs ONE conditional
+ * Wiring: `installFallbacksAdapter` installs ONE conditional
  * `ctx.inject(['llm'])` child — absent `llm` service (test harness) is a
  * clean no-op, and fiber unload ⇒ the child's disposer unregisters the
  * route. Registration is an idempotent transition-reconcile on COMMITTED
- * config snapshots: register when nothing is configured → something is
- * (`isFallbackActive` — content presence, plan fallbacks-web-ux-alignment
- * T2), unregister on the reverse, driven by the settings `onChange` hook
- * (the returned reconcile thunk, wired by `apply()`) plus child activation.
- * The row is visible whenever something is configured — a non-conforming
- * all-day chain does NOT hide it (PR #62 feedback); conformance still gates
- * a successful delegate (`effectiveHeadOf` below refuses a non-conforming
- * all-day). The registration gate is `isFallbackActive` content presence
- * (`rootChain` / `timeSlots` / declared roles): a slot-row edit that flips
- * that gate (e.g. removing the only slot while `rootChain` and roles are
- * empty) intentionally churns registration — the content-presence contract
- * (plan fallbacks-web-ux-alignment T2), not churn to design away; do NOT
- * re-narrow the condition to ignore `timeSlots`. Conformance-only chain
- * edits still never churn (conformance gates the delegate, not the row).
+ * config snapshots: register when `chains` goes empty → non-empty
+ * (`isFallbackActive` = `chains.length > 0`), unregister on the reverse,
+ * driven by the settings `onChange` hook (the returned reconcile thunk,
+ * wired by `apply()`) plus child activation. A chain with empty or
+ * non-conforming `entries` still shows its row (conformance gates the
+ * delegate via {@link effectiveHeadOf}, not the row). One
+ * `llm.registerAdapter([FALLBACKS_PROVIDER], adapter)` call serves all rows.
  *
- * Adapter behavior (P1/P3, direction C): `listModels` advertises exactly the
- * one virtual row; `stream()` WALKS the session's chain (cooldown / failed-set
- * / switch cap / recovery bookkeeping) in `src/chain-walk.ts` — the walk is
- * injected at install and owns the pre-attempt guards, so this module stays
- * the catalog + metadata surface. `resolveModel` proxies the current effective
- * head's metadata when resolvable (modalities/context-window/reasoning follow
- * the head) with a permissive default otherwise — never throws.
- * `providerRetryPolicy` and `imageRequestPricing` mirror the same head for the
- * host-captured retry policy and the token meter — also never throwing.
+ * Adapter behavior: `listModels` advertises one row per chain;
+ * `stream()` WALKS the selected chain (cooldown / failed-set / switch cap /
+ * recovery bookkeeping) in `src/chain-walk.ts` — the walk is injected at
+ * install and owns the pre-attempt guards. `resolveModel` /
+ * `imageRequestPricing` resolve the chain FROM the `model` argument and
+ * follow its effective head (permissive default otherwise — never throw).
+ * `providerRetryPolicy` returns `undefined` (documented degradation): the
+ * host captures the policy ONCE per provider at registration, so the virtual
+ * route cannot mirror a per-chain head's policy — the host default applies.
  *
- * @module dsh-llm-fallbacks/virtual-adapter
+@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 ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
-import { type FallbacksConfig } from './config.ts';
-import type { PolicyRoute } from './subagent-policy.ts';
+import { type FallbacksConfig, type NamedChain } from './config.ts';
 /** Provider route of the virtual adapter (exact string, spec lock). */
 export declare const FALLBACKS_PROVIDER = "FallbacksChain";
-/**
- * Model id of the virtual catalog row (exact string, spec lock). "Auto" is
- * the hardcoded picker id (not i18n — user decision 2026-08-18). The
- * catalog `name` the host picker renders is dynamic — see
- * {@link pickerDisplayName} (`Auto: <model>[<slot>]`).
- */
-export declare const FALLBACKS_CHAIN_MODEL = "Auto";
 /** One dispatchable exact head: `provider/model`. Wildcards are never seeds (P3). */
 export interface EffectiveHead {
     provider: string;
@@ -57,50 +41,32 @@ export interface EffectiveHead {
 /**
  * The FIRST DISPATCHABLE exact head of a chain — the single definition of
  * "effective head" (F-001) shared by this module's metadata paths
- * (`pickerDisplayName` / `resolveModel` / `providerRetryPolicy` /
- * `imageRequestPricing`), the walk's head and served-route resolution
- * (`servedRouteOf` in `src/chain-walk.ts`), and the seam's mount gate
- * (`injectRoute` in `src/subagents-seam.ts`). Walks the SAME chain
- * `resolveEffectiveChain` produces, skipping entries that can never
+ * (`pickerDisplayName` / `resolveModel` / `imageRequestPricing`) and the
+ * walk's head resolution (`resolveWalk` in `src/chain-walk.ts`). Walks the
+ * SAME chain `resolveEffectiveChain` produces, skipping entries that can never
  * be dispatched: malformed selectors (config-warning path), `provider/*`
  * `provider/*` wildcards (no real pair), and self-routes back to
  * `FallbacksChain/*` (the P1 recursion guard). `undefined` when the chain
  * is empty or no entry is dispatchable.
- *
- * `allowedModels` (spec D1) additionally restricts the result to the host
- * subagent allowlist: a PLUGIN-originated route is only ever attempted on a
- * route the host authorizes, so the seam's mount gate and a plugin-originated
- * walk's start pass the enabled policy's list and an entry it excludes is
- * skipped like any other non-dispatchable entry. An empty intersection is
- * `undefined` — the caller declines the mount / refuses the walk.
  */
-export declare function firstDispatchableExactHead(chain: readonly string[], allowedModels?: readonly PolicyRoute[]): EffectiveHead | undefined;
+export declare function firstDispatchableExactHead(chain: readonly string[]): EffectiveHead | undefined;
 /**
- * The effective chain head at `now` (P1): the first DISPATCHABLE exact head
- * of the SAME `resolveEffectiveChain` the routing engine uses — thin
- * config+clock entry into the shared {@link firstDispatchableExactHead} (no
- * divergent skip/walk rules). `undefined` when the chain is empty or no
- * entry is dispatchable (wildcard, self-route to `FallbacksChain/*`,
- * malformed selector).
- *
- * Conformance gate (PR #62 feedback): the all-day `rootChain` must be
- * conforming (exactly one official model — Flash or Pro)
- * for a successful delegate —
- * a legacy multi-model (or empty) all-day chain earns no primary
- * semantics even though the picker row is visible. `resolveModel` then
- * falls back to the permissive default. The delegate side of that gate is the
- * chain walk's ROOT-origin rule (`UNDISPATCHABLE_EFFECTIVE_HEAD`); a subagent
- * walks its role chain instead, so the all-day shape never gates a child.
+ * The effective chain head of ONE named chain at `now`: the first
+ * DISPATCHABLE exact head of the SAME `resolveEffectiveChain` the walk uses —
+ * thin chain+clock entry into the shared {@link firstDispatchableExactHead}.
+ * `undefined` when the entries are empty or non-conforming (the tail must be
+ * exactly one official model), or no entry is dispatchable (wildcard,
+ * self-route to `FallbacksChain/*`, malformed selector). `resolveModel` then
+ * falls back to the permissive default; the delegate side of the conformance
+ * gate is the chain walk's `UNDISPATCHABLE_EFFECTIVE_HEAD`.
  */
-export declare function effectiveHeadOf(config: FallbacksConfig, now: Date): EffectiveHead | undefined;
+export declare function effectiveHeadOf(chain: NamedChain, now: Date, tz?: string): EffectiveHead | undefined;
 /**
- * Host picker label: `Auto: <displayName>[<slot>]`.
- * Display name first so the trigger stays readable and platforms stay
- * distinguishable (catalog `name`, not the model id). Bare `Auto` when
- * there is no dispatchable head. Slot label from {@link resolveSlotState}.
- * @param modelDisplayName - catalog/resolved name; falls back to the id.
+ * Host picker label for one chain: `` `${chain.label}: <head>[<slot>]` ``.
+ * Bare `chain.label` when there is no dispatchable head. The label is
+ * user-editable and display-only; the model id is the chain id.
  */
-export declare function pickerDisplayName(config: FallbacksConfig, now?: Date, modelDisplayName?: string): string;
+export declare function pickerDisplayName(chain: NamedChain, now?: Date, modelDisplayName?: string, tz?: string): string;
 /**
  * The virtual adapter (P1/P3). `stream()` hands the call to the injected walk
  * (see `src/chain-walk.ts`) — registration metadata stays here.
@@ -115,50 +81,39 @@ export declare class FallbacksChainAdapter extends LlmAdapter {
         id: string;
         name: string;
     };
-    /** Advisory catalog: one virtual row; `name` is the live picker label. */
+    /** Advisory catalog: ONE row per named chain; `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.
+     * Model-scoped metadata: resolve the chain FROM the `model` argument (the
+     * chain id) and follow its effective head — modalities/context-window/
+     * reasoning follow the head, the truthful answer for the CURRENT head.
+     * Permissive default for an unknown chain id or an unresolvable head;
+     * never throws.
      */
     resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
     /**
-     * Route-accurate retry attribution: the virtual row declares no policy of
-     * its own — the virtual `provider` argument is intentionally ignored. The
-     * host captures `adapter.providerRetryPolicy(provider) ??
-     * resolveRetryPolicy(void 0, …)` ONCE, when a route is registered, so
-     * answering here with the SAME policy the concrete head route declared
-     * (e.g. a user's `llm-deepseek.retryPolicy`, including `mode: 'always'`)
-     * keeps retries behaving exactly as they do on the head `stream()`
-     * dispatches. Never throws: an unresolvable head, a vanished `llm`, or an
-     * unregistered head provider degrades to `undefined` — the host's own
-     * default. That last arm matters: the runtime's lookup THROWS `NO_ADAPTER`
-     * for an unknown provider, and this call happens inside the plugin's
-     * `registerAdapter`, so an escaping throw would take the whole virtual
-     * route down instead of just degrading its policy.
+     * DOCUMENTED DEGRADATION (named virtual chains): the adapter stays ONE
+     * `FallbacksChain` provider carrying N chain rows, but the host captures
+     * `adapter.providerRetryPolicy(provider)` ONCE per provider at
+     * registration, so the virtual route can no longer mirror its head's
+     * retry policy. It returns `undefined` — the host's own default applies.
      */
     providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;
     /**
-     * Route-accurate image pricing: 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.
+     * Image pricing, model-scoped: resolve the chain FROM the `model`
+     * argument and delegate through the runtime lookup for its effective head
+     * (including `undefined`). Never throws: an unknown chain id, 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;
+    imageRequestPricing(_provider: string, model: string): LlmImageRequestPricing | undefined;
     /**
-     * The virtual route's entry point (P1, direction C): the session's chain is
-     * WALKED (`src/chain-walk.ts`) — the walk owns the pre-attempt guards
-     * (`EMPTY_EFFECTIVE_CHAIN` / `UNDISPATCHABLE_EFFECTIVE_HEAD` /
-     * `LLM_UNAVAILABLE`, thrown synchronously before any chunk, so the runtime
-     * normalizes them exactly like an adapter throw) because only it can resolve
-     * WHICH chain the calling session walks: a subagent's role chain is not the
-     * root's all-day chain, so a root-only gate here would refuse a child that
-     * has a perfectly walkable role chain.
+     * The virtual route's entry point: `options.model` IS the chain id and the
+     * selected chain is WALKED (`src/chain-walk.ts`) — the walk owns the
+     * pre-attempt guards (`UNKNOWN_CHAIN` / `EMPTY_EFFECTIVE_CHAIN` /
+     * `UNDISPATCHABLE_EFFECTIVE_HEAD` / `LLM_UNAVAILABLE`, thrown synchronously
+     * before any chunk, so the runtime normalizes them exactly like an adapter
+     * throw).
      */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }

package/locale/en.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "title": "Fallbacks",
-    "description": "Automatic provider/model fallback chains that keep agent steps running when LLM requests keep failing (auth, quota, rate limit).",
+    "description": "Named fallback chains for model requests: on failure the walk switches to the next model in the chain so agent steps keep running; the main agent must select a virtual chain in the model picker for fallback to apply.",
     "detail": "docs/DETAIL.md"
   }
 }

package/locale/zh.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "title": "故障降级",
-    "description": "模型请求持续失败（认证、配额、限流）时自动切换备用模型链，保持 agent 步骤继续运行。",
+    "description": "为模型请求配置命名降级链：失败时按链内顺序切换到备用模型，保持 agent 步骤继续运行；主代理需在模型选择器中选择一条虚拟链才有降级效果。",
     "detail": "docs/DETAIL.zh.md"
   }
 }

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/client/GeneralFallbacksRow.d.ts

@@ -1,19 +0,0 @@
-import type { ReactNode } from 'react';
-import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
-import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
-import type { FallbacksSettingsController, FallbacksSettingsState } from './fallbacks-store.ts';
-/** Injected dependencies of {@link GeneralFallbacksRow} (slot `inject`). */
-export interface GeneralFallbacksRowInjected {
-    /** The shared controller (loaded on first mount, refreshed on pushed invalidations). */
-    controller: FallbacksSettingsController;
-    /** uSES subscription hook bound to the store (inject face — advisor pattern). */
-    useSnapshot: SnapshotSelectorHook<FallbacksSettingsState>;
-}
-/** Props delivered by the slot outlet: runtime share + locale seat + inject face. */
-export type GeneralFallbacksRowProps = PropsRuntime<'settings.general.item'> & PropsLocale<'fallbacks'> & GeneralFallbacksRowInjected;
-/**
- * Render the Fallbacks status row.
- * @param props - composed slot props.
- * @returns the row element tree.
- */
-export declare function GeneralFallbacksRow({ controller, useSnapshot, t }: GeneralFallbacksRowProps): ReactNode;

package/dist/roles.d.ts

@@ -1,89 +0,0 @@
-/**
- * Role resolution for fallback chains (spec §7.1; plan fallbacks-role-runtime
- * Task 1).
- *
- * This module is the RULES stage. Dispatch-time role resolution
- * (plan fallbacks-role-automatch; plan dsh-148 added the dispatch stage) is
- * the three-stage resolver in `role-resolution.ts` — explicit
- * (`session.header.agentPreset`) → dispatch-declared role (the seam record
- * resolved from `**Execute as**`) → this rules stage; `AgentLike` carries the
- * additive `session.header.agentPreset?` carrier for that explicit stage.
- *
- * Precedence (first hit wins):
- * 1. the first `rules` entry whose specified provider/model patterns match
- *    the agent — rules are SUBAGENT-ONLY (PR #62 feedback): a root-origin
- *    agent never matches rules and resolves straight to the built-in
- *    `'inherit'` (→ `rootChain`). The legacy per-rule `origin` field (a
- *    pre-feedback config may still carry `origin: root|subagent`) is
- *    IGNORED at match time — every rule applies to subagents regardless
- *    of the stored origin value;
- * 2. the built-in `'inherit'` role (no-rule-match default, spec §7.1 / D4).
- *
- * A matched rule must target a declared role id (`roleIds`, derived from
- * `config.roles.list`) or the built-in `'inherit'` — an undeclared target
- * warns and falls back to `'inherit'` (defensive; startup validation already
- * flagged the reference, spec §7.1 / AC-4).
- *
- * Role ids are canonicalized by trim (qc2 F-001, client-canonical trim
- * alignment — `validateFallbacksConfig` trims ids and rule references, so
- * the runtime must too): `roleIds` maps a TRIMMED id to the DECLARED RAW
- * id, membership compares `rule.role.trim()`, and a matched rule returns
- * the declared raw id — so roleDef lookups in `chains.ts` / `commands.ts`
- * match the stored `roles.list[].id` exactly and a padded YAML id
- * (`' coder '`) with a trimmed rule reference (`'coder'`) resolves to the
- * same role instead of silently degrading to `'inherit'`.
- *
- * A missing agent origin is treated as `'root'` — and root agents never
- * match rules (rules are subagent-only, PR #62 feedback). Origin is read
- * from `session.header.origin` — a native `SessionHeader` field the store folds
- * from `CreateSessionOptions.meta.origin` (`packages/core/session/src/
- * index.ts:884`); subagent children set it via `childSessionMeta`
- * (`packages/subagent/subagent/src/child-agent.ts:115`), root agents carry
- * none. A subagent `persona` is NOT readable at the decision point:
- * `AgentOptions` is provider/model/maxTokens only, and persona is installed
- * as a scoped system-prompt section in the child's creation window — see
- * `.mstar/iterations/iter-20260811-fallbacks-mount-only/guides/
- * role-and-model-selection-exploration.md` (Role section).
- *
- * @module dsh-llm-fallbacks/roles
- */
-import { type FallbacksRoleRule } from './config.ts';
-export type { FallbacksRoleRule } from './config.ts';
-/** Agent origins (spec §3) — an agent property, not a rule constraint:
- * rules are subagent-only (PR #62 feedback). */
-export type Origin = 'root' | 'subagent';
-/** Loose agent shape sufficient for role resolution (spec §3 / brief). */
-export interface AgentLike {
-    options?: {
-        provider?: string;
-        model?: string;
-    };
-    session?: {
-        header?: {
-            origin?: Origin;
-            /** Dispatch-time explicit role carrier (plan fallbacks-role-automatch Task 2). */
-            agentPreset?: string;
-        };
-    };
-}
-/**
- * Resolve the fallback-chain role for an agent: first matching rule (in
- * listed order) → the built-in `'inherit'` role. A rule targeting an id
- * outside the declared-id set ∪ {'inherit'} warns once and resolves to
- * `'inherit'` (the defensive path — `validateFallbacksConfig` already
- * warned at startup, spec §7.1).
- *
- * `roleIds` is the canonical trimmed-id map built by the wiring
- * (`trimmed id → declared raw id`, see `src/index.ts` apply()): a matched
- * rule returns the declared RAW id so the roleDef lookups in
- * `chains.ts` / `commands.ts` find the stored `roles.list[]` entry exactly
- * (qc2 F-001 — no silent rule inertness on padded YAML ids).
- *
- * `warn` defaults to `console.warn` (direct-call compatibility); the
- * decision path injects the cordis `logger.warn` so every plugin warning
- * flows through the plugin log namespace (qc2 F-002 / qc3 S-3).
- */
-export declare function resolveRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, warn?: (message: string) => void, servedRoute?: {
-    provider: string;
-    model: string;
-}): string;

package/dist/route-allowlist.d.ts

@@ -1,43 +0,0 @@
-/**
- * Route identity and allowlist intersection on resolved candidates (plan
- * dsh-012-subagent-routing T2; spec D1 ∩ D2).
- *
- * Pure, host-free module: plain route data in, results out. Route identity is
- * the EXACT provider string plus the EXACT model string — no aliasing, no
- * case-folding, no catalog-id substitution (spec Terms). Intersections run on
- * RESOLVED candidates (concrete provider+model after the chain candidate
- * pipeline); this module never resolves chains or expands wildcards — the
- * caller passes already-resolved candidates in.
- *
- * Fail-closed direction: an empty allowlist contains nothing and an empty
- * intersection yields `undefined` — the caller must skip the
- * plugin-originated route rather than fall back to an unproven one (spec D1).
- * Never throws.
- *
- * @module dsh-llm-fallbacks/route-allowlist
- */
-import type { PolicyRoute } from './subagent-policy.ts';
-/** One resolved chain candidate: a selector anchored to a concrete model id. */
-export type ResolvedCandidate = {
-    readonly provider: string;
-    readonly model?: string;
-};
-/**
- * Normalize resolved chain candidates into detached plain routes. Candidates
- * without a concrete model id are dropped (they are not routes); every
- * surviving entry is a fresh object, so the result never aliases the
- * caller's candidate list.
- */
-export declare function resolvedRoutes(candidates: readonly ResolvedCandidate[]): PolicyRoute[];
-/**
- * Whether the route is on the allowlist under exact route identity: both the
- * provider and the model strings must equal an allowed route exactly.
- */
-export declare function routeOnAllowlist(route: PolicyRoute, allowedModels: readonly PolicyRoute[]): boolean;
-/**
- * The first resolved candidate that is on the allowlist, preserving the
- * candidate order (the chain's first in-allowlist entry wins), or `undefined`
- * when the intersection is empty — the caller then skips the inject / switch
- * and the host seed stands (spec D1 ∩ D2).
- */
-export declare function firstAllowedCandidate(resolved: readonly PolicyRoute[], allowedModels: readonly PolicyRoute[]): PolicyRoute | undefined;

package/dist/subagent-policy.d.ts

@@ -1,137 +0,0 @@
-/**
- * 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's live subagent model-selection settings value (the
- *    `subagent-model-selection-settings` settings namespace), typed via a
- *    type-only peer import that is erased at emit. rc.1 made the settings
- *    service's own snapshot reader private, so the wiring reads the settings
- *    form value and narrows it structurally here.
- *
- * 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
- *   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 value's shape, re-exported from the published peer
- * subpath (type-only). Wiring passes the settings form's namespace value in as
- * plain data; if upstream drifts, this alias fails typecheck instead of
- * drifting silently at runtime (plan ADR).
- */
-export type PeerSettingsSnapshot = AssertSettingsShape<SubagentModelSelectionSettings>;
-/**
- * Narrow a host settings value into the reader's snapshot contract.
- * Reads STRUCTURALLY like {@link readSessionPolicyEvent} — rc.1 publishes no
- * settings value reader — so a malformed value is reported, never raised; the
- * wiring decides its failure face (warn + fail-closed).
- *
- * @param value - untrusted settings-form value for the policy namespace.
- * @returns a detached snapshot, or undefined when the value is not one.
- */
-export declare function policySettingsFrom(value: unknown): PolicySettings | undefined;
-/**
- * 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 - host settings value narrowed by
- *   {@link policySettingsFrom}, or undefined when the host composes no such
- *   settings entry.
- */
-export declare function effectivePolicy(event: SessionPolicyEventRead, settings: PolicySettings | undefined): EffectivePolicy;
-export {};