dsh-llm-fallbacks 0.6.13 → 0.8.0

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.6.13",
+  "version": "0.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,7 +28,11 @@
     "bundle",
     "locale",
     "icon.svg",
-    "scripts"
+    "scripts",
+    "docs/DETAIL.md",
+    "docs/DETAIL.zh.md",
+    "docs/preview.svg",
+    "docs/preview.zh.svg"
   ],
   "dsh": {
     "bundle": {
@@ -65,29 +69,29 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-gateway": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-remotes": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-store": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-chat": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-commands": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-llm": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-llm-retry": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-session": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-settings": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-tool-subagent": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-typert-protocol": "^0.2.1-rc.4",
-    "@deepseek-ai/dsh-typert-registry": "^0.2.1-rc.4",
+    "@deepseek-ai/dsh-agent": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tool-subagent": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.2.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.5",
     "react": "^18.2.0"
   },

package/dist/authorized-route.d.ts

@@ -1,68 +0,0 @@
-/**
- * Authorized-route detection from durable child state (plan
- * dsh-012-subagent-routing T2; spec D2).
- *
- * Pure, host-free module: a plain-data session view in, one route out. The
- * wiring captures the view at a subagent's first request from the detection
- * sources the plan names (shapes verified against upstream
- * `packages/subagent/subagent/src/child-agent.ts:68-85` and
- * `packages/api/session-controller/src/types.ts:284`):
- *
- * - the session's `model/selection` log entries (plain descriptors; payload
- *   is the `ModelSelection` shape — provider, model, optional
- *   reasoningEffort), an explicit host-recorded selection for this session;
- * - the durable `request/header` config fold (`requestHeader()?.config`);
- * - the resolved creation options (`agent.options`) as the pre-first-request
- *   fallback — upstream precedence: the durable header wins, options
- *   fallback (`parentAgentOptionsForDelegation`);
- * - the pure-inheritance baseline: the delegating parent's current route,
- *   resolved by the wiring the same way (`requestHeader()?.config` else
- *   creation options).
- *
- * A source yields a route only when BOTH provider and model are present
- * non-empty strings — an effort alone is not a route (spec Terms). A
- * `model/selection` entry is definitionally an explicit selection, so it is
- * authorized as-is. A route read from the header or the creation options is
- * explicit only when it is NOT the pure-inheritance continuation: when the
- * baseline is provable (complete) and equals the candidate exactly, the
- * candidate is the parent's inherited route, not a selection — pure
- * inheritance is NOT an authorized route (spec Terms; upstream
- * `resolveChildAgentOptions` materializes the parent route into child
- * options even without an explicit selection, so equality with the baseline
- * is the only child-side inheritance signal). With the baseline unprovable
- * the candidate stands: D2 keeps authorized chain heads unoverwritten, and
- * the allowlist-constrained inject below this decision holds D1 either way.
- *
- * Never throws; malformed source shapes yield `undefined`, not routes.
- *
- * @module dsh-llm-fallbacks/authorized-route
- */
-import type { PolicyRoute } from './subagent-policy.ts';
-/** One plain route-bearing source shape (header config, options, selection payload, baseline). */
-export type RouteSource = {
-    readonly provider?: unknown;
-    readonly model?: unknown;
-    readonly reasoningEffort?: unknown;
-};
-/** Structural session view consumed by {@link detectAuthorizedRoute} — plain data only, no live host objects. */
-export interface AuthorizedRouteSession {
-    /** Durable request-header config fold captured from the child session (absent before the first logged header). */
-    readonly requestHeader?: RouteSource | undefined;
-    /** Plain event descriptors (`type` + optional `data`) captured from the child session's log. */
-    readonly events?: readonly {
-        readonly type: string;
-        readonly data?: unknown;
-    }[] | undefined;
-    /** Resolved creation options captured from the agent (pre-first-request fallback). */
-    readonly options?: RouteSource | undefined;
-    /** Pure-inheritance baseline: the delegating parent's current route (absent when unprovable). */
-    readonly inherited?: RouteSource | undefined;
-}
-/**
- * Detect the subagent's explicit authorized route at its first request, or
- * `undefined` for pure inheritance (semantics in the module doc). The wiring
- * skips role-inject on a defined result — the authorized route is the chain
- * head (spec D2) — and runs the allowlist-constrained four-stage inject on
- * `undefined`.
- */
-export declare function detectAuthorizedRoute(session: AuthorizedRouteSession): PolicyRoute | undefined;

package/dist/automatch.d.ts

@@ -1,98 +0,0 @@
-/**
- * LLM auto-match role selection (plan fallbacks-role-automatch Task 3).
- *
- * This module is the bounded LLM caller behind the resolver's stage-3
- * auto-match hook (`resolveRoleAtDispatch`, `role-resolution.ts`). When the
- * explicit and rules stages resolve to `'inherit'` and `roleAutoMatch` is
- * enabled, `pickRoleByLlm` asks the model to pick the best-fit declared role
- * from the taxonomy and returns its declared RAW id, or `null` (= `'inherit'`).
- *
- * Contract (architect-locked, plan Global Constraints · Auto-match bounded):
- * - ONE bounded completion per decision: small `maxTokens`
- *   ({@link AUTOMATCH_MAX_TOKENS}) and a timeout
- *   ({@link AUTOMATCH_TIMEOUT_MS}, default 5s) that abandons the stream via
- *   the streaming contract's cancellation (`options.signal`) — no dangling
- *   iterator, no unhandled rejection.
- * - Never throws. Every failure mode — throw, timeout, `none`, no valid id,
- *   garbage answer, malformed inputs — resolves to `null`, so the "never
- *   throws out of `agent/request`" invariant holds end-to-end (the resolver
- *   deliberately does NOT catch the hook).
- * - Fast paths that avoid an LLM call entirely: empty taxonomy, absent
- *   `ctx.llm` service, and no concrete provider/model route for the judgment
- *   call. The plugin does NOT listen on `llm/stream`, so this call cannot
- *   recurse into the plugin.
- *
- * Judgment-call route choice (documented): the concrete provider/model for the
- * judgment call is taken from the roles' DECLARED context first — the first
- * exact (non-wildcard) `provider/model` selector across the declared chains,
- * in declaration order (the operator's own taxonomy is the most stable route
- * set). If no declared chain yields an exact selector, the agent's current
- * `options.provider`/`options.model` is used when both halves are present;
- * otherwise the call is skipped (`null`).
- *
- * Pure helpers exported for unit testing:
- * - {@link buildAutomatchPrompt} — the taxonomy prompt (declared ids +
- *   personas + agent origin/agentPreset; instructs exactly-one-declared-id-or-
- *   `none`).
- * - {@link parseAutomatchAnswer} — parses a declared id out of the model
- *   answer with surrounding whitespace/punctuation/quote/backtick tolerance;
- *   `none` (case-insensitive) and unknown ids → `null`. `roleIds` is the
- *   trimmed-id → declared-raw-id map, the same canonicalization the resolver
- *   uses.
- *
- * @module dsh-llm-fallbacks/automatch
- */
-import { type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
-import type { FallbacksRole, FallbacksRoles } from './config.ts';
-import type { AgentLike } from './roles.ts';
-/** Default auto-match completion timeout in ms — abandons the stream. */
-export declare const AUTOMATCH_TIMEOUT_MS = 5000;
-/** Output bound (tokens) for the judgment call: one id or the literal `none`. */
-export declare const AUTOMATCH_MAX_TOKENS = 32;
-/**
- * Minimal `llm` service surface {@link pickRoleByLlm} reads. The real
- * `LlmRuntime.stream(options)` matches structurally; this face keeps the
- * module free of the full cordis Context merge.
- */
-export interface AutomatchLlm {
-    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
-}
-/**
- * Minimal context surface: `ctx.get('llm')` (optional service — absent →
- * `null` fast-path). The broad `get(name: string)` face is satisfied by the
- * real cordis `Context` (`ReflectService.get` overloads return `any`/the
- * merged service), so the Task-4 wiring can pass `ctx` directly.
- */
-export interface AutomatchContext {
-    get(name: string): AutomatchLlm | undefined;
-}
-/** Options for {@link pickRoleByLlm}. */
-export interface PickRoleByLlmOptions {
-    /** Completion timeout in ms; defaults to {@link AUTOMATCH_TIMEOUT_MS}. */
-    timeoutMs?: number;
-    /** Warning sink — the decision path injects the plugin logger. */
-    warn: (message: string) => void;
-}
-/**
- * Build the auto-match taxonomy prompt: every declared role's trimmed id and
- * persona, the agent's origin (and non-empty `agentPreset` when present), and
- * the exactly-one-declared-id-or-`none` instruction. Pure — no I/O.
- */
-export declare function buildAutomatchPrompt(roles: readonly FallbacksRole[], agent: AgentLike): string;
-/**
- * Parse the model's answer into a declared role id.
- *
- * The answer is expected to BE an id (possibly wrapped in whitespace, quotes,
- * backticks, or trailing punctuation); surrounding characters outside the id
- * grammar (`[a-zA-Z0-9-]`) are stripped, then the remaining string must match
- * a declared id exactly (case-insensitive) via `roleIds` (trimmed id →
- * declared RAW id, the resolver's canonicalization). `none` (case-insensitive)
- * and any unknown/malformed answer → `null`.
- */
-export declare function parseAutomatchAnswer(answer: string, roleIds: ReadonlyMap<string, string>): string | null;
-/**
- * Bounded LLM role-selection call (see module header). Resolves the declared
- * RAW id of the best-fit role, or `null` on any fast path or failure. NEVER
- * throws.
- */
-export declare function pickRoleByLlm(ctx: AutomatchContext, roles: FallbacksRoles, agent: AgentLike, opts: PickRoleByLlmOptions): Promise<string | null>;

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/override.d.ts

@@ -1,39 +0,0 @@
-/**
- * RouteChanged effort rule for config overrides (plan dsh-012-subagent-routing
- * T4; spec D3).
- *
- * Pure, host-free module: plain seed config plus a target route in, the
- * overridden config out. The effort handling mirrors the upstream
- * `resolveChildAgentOptions` rule (deepseek-harness
- * `subagent/src/child-agent.ts:117`): a changed provider+model route drops the
- * seed's route-owned `reasoningEffort` so the selected model resolves its own
- * default, unless an effort is explicitly named for the override; an
- * unchanged route keeps the seed effort. Policy-independent by design — the
- * same rule applies on every override path whether the subagent routing
- * policy is on or off (spec D3). Never throws.
- *
- * @module dsh-llm-fallbacks/override
- */
-import type { LlmCallConfig } from '@deepseek-ai/dsh-llm';
-/** Reasoning-effort value carried by `LlmCallConfig.reasoningEffort`. */
-export type LlmReasoningEffort = NonNullable<LlmCallConfig['reasoningEffort']>;
-/**
- * Override a request config with a target route under the upstream
- * routeChanged effort rule (spec D3):
- *
- * - An explicitly named effort always survives — it wins over the seed effort
- *   on either route (upstream semantics: the request overrides the parent).
- * - Same provider+model route → the seed `reasoningEffort` is preserved.
- * - Route changed without an explicit effort → the seed effort is dropped
- *   (never carry a stale effort into a different provider/model route).
- *
- * @param seed - the caller's current request config.
- * @param to - the effective target route.
- * @param explicitEffort - an effort explicitly named for this override.
- * @returns a fresh config routed to `to` with the effort rule applied; never
- * mutates `seed`.
- */
-export declare function overrideConfigWithRouteRule(seed: LlmCallConfig, to: {
-    provider: string;
-    model: string;
-}, explicitEffort?: LlmReasoningEffort): LlmCallConfig;

package/dist/roles.d.ts

@@ -1,90 +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 four-stage resolver in `role-resolution.ts` — explicit
- * (`session.header.agentPreset`) → dispatch-declared role (the seam record
- * resolved from `**Execute as**`) → this rules stage → an optional auto-match
- * hook; `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,123 +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 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
- *   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 {};