dsh-llm-fallbacks 0.2.1 → 0.3.0

package/dist/role-resolution.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Dispatch-time three-stage role resolution (plan fallbacks-role-automatch
+ * Task 2).
+ *
+ * Precedence (first hit wins):
+ * 1. explicit — `session.header.agentPreset` trimmed matches a declared role
+ *    id → that role's DECLARED RAW id (via the `roleIds` trimmed-id map, the
+ *    same canonicalization the rules path uses); the reserved `'inherit'`
+ *    and undeclared presets are NEVER dispatchable explicit roles and fall
+ *    through to rules;
+ * 2. rules — the existing `resolveRole` passthrough, unchanged (a declared
+ *    role wins; no-rule-match / an explicit rule targeting `'inherit'`
+ *    resolve to `'inherit'`);
+ * 3. auto-match — only when stage 2 resolved to `'inherit'` AND
+ *    `opts.automatchEnabled`: call `opts.automatch` with the agent. The hook
+ *    (Task 3 supplies the bounded LLM caller) MUST return a declared raw id
+ *    or `null`; the resolver defensively validates the return against
+ *    `roleIds` — an unknown id warns and resolves to `'inherit'`, never an
+ *    undeclared role. When `automatch` is undefined or `automatchEnabled`
+ *    is false the hook is skipped.
+ *
+ * `'inherit'` is the single "no specific role" outcome — reached by
+ * no-rule-match OR an explicit rule targeting `'inherit'` — and both are
+ * auto-match eligible when enabled. An operator who wants a class to never
+ * auto-match sets `roleAutoMatch: false` (→ `automatchEnabled: false`).
+ *
+ * Pure ordering logic: no config object and no LLM service inside this
+ * module — the LLM is an injectable hook owned by Task 3/4.
+ *
+ * @module dsh-llm-fallbacks/role-resolution
+ */
+import { type FallbacksRoleRule } from './config.ts';
+import { type AgentLike } from './roles.ts';
+import type { Selector } from './selectors.ts';
+export type { FallbacksRoleRule } from './config.ts';
+/** Options for {@link resolveRoleAtDispatch}. */
+export interface ResolveRoleAtDispatchOptions {
+    /**
+     * Whether the auto-match stage may run (the `roleAutoMatch` config switch).
+     * When `false`, stage 3 never runs and the outcome is identical to the
+     * rules stage alone.
+     */
+    automatchEnabled: boolean;
+    /**
+     * Auto-match hook — Task 3 supplies the bounded LLM caller; the resolver
+     * itself contains no LLM. Contract: given the agent being resolved, return
+     * a declared raw role id or `null`. The resolver defensively validates the
+     * return against `roleIds` — an unknown id warns and resolves to
+     * `'inherit'`, never an undeclared role. Skipped when undefined.
+     */
+    automatch?: (agent: AgentLike) => Promise<string | null>;
+    /** Warning sink — the decision path injects the plugin logger. */
+    warn: (message: string) => void;
+}
+/**
+ * Resolve the dispatch-time role for an agent across three ordered stages
+ * (explicit → rules → auto-match hook). Never throws on its own inputs; the
+ * hook's own rejection is deliberately NOT caught here (the Task-3/4 wiring
+ * bounds the LLM call so it never throws out of the request path).
+ *
+ * `roleIds` is the canonical trimmed-id map (`trimmed id → declared raw id`,
+ * built in `src/index.ts` apply()): every stage canonicalizes its reference
+ * by trim and returns the DECLARED RAW id, so roleDef lookups in
+ * `chains.ts` / `commands.ts` find the stored `roles.list[]` entry exactly
+ * (qc2 F-001 — no silent role inertness on padded YAML ids).
+ */
+export declare function resolveRoleAtDispatch(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, opts: ResolveRoleAtDispatchOptions): Promise<string>;
+/**
+ * The dispatch-time chain head (plan fallbacks-role-automatch Task 4): the
+ * FIRST candidate of a `resolveChainViews` pass whose `wildcard` flag is
+ * false — an exact `provider/model` entry. `provider/*` entries are NOT
+ * dispatch injection targets (no failing model to anchor them; a guessed
+ * injection risks a hard failure whose code may sit outside `triggerCodes`),
+ * so a wildcard-only chain yields `undefined` → no injection (today's
+ * behavior). No cooldown/failed filtering and no existence probe run here —
+ * a fresh subagent's first request has no failure-scoped state (see the Task
+ * 4 decision) and exact heads are never probed. Pairs with
+ * {@link resolveChainViews}'s parallel `wildcard` provenance (`src/chains.ts`);
+ * the caller resolves the role's concatenated chain first.
+ */
+export declare function firstExactCandidate(all: readonly Selector[], wildcard: readonly boolean[]): Selector | undefined;

package/dist/roles.d.ts

@@ -2,9 +2,20 @@
  * 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) is the three-stage resolver in
+ * `role-resolution.ts` — explicit (`session.header.agentPreset`) → 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 origin/provider/model patterns
- *    all match the agent;
+ * 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
@@ -21,8 +32,9 @@
  * (`' 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'`. Origin is read from
- * `session.header.origin` — a native `SessionHeader` field the store folds
+ * 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
@@ -36,7 +48,8 @@
  */
 import { type FallbacksRoleRule } from './config.ts';
 export type { FallbacksRoleRule } from './config.ts';
-/** Agent origins understood by role rules (spec §3). */
+/** 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 {
@@ -47,6 +60,8 @@ export interface AgentLike {
     session?: {
         header?: {
             origin?: Origin;
+            /** Dispatch-time explicit role carrier (plan fallbacks-role-automatch Task 2). */
+            agentPreset?: string;
         };
     };
 }

package/dist/time-slots.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Time-slot rows for `fallbacks` (plan fallbacks-timeslots Task 1, pins
+ * P4–P6): frozen preset windows, the official-V4 all-day conformance
+ * guard, and the pure `resolveEffectiveChain` / `resolveSlotState`
+ * resolver.
+ *
+ * Pure module — no `@deepseek-ai/*` runtime imports: the client card
+ * imports the row types type-only (mirroring `config.ts`) and the runtime
+ * wires these helpers at request time (Task 2). Malformed rows NEVER
+ * throw: they warn ONCE per row instance (through `console.warn` — the
+ * resolver's 3-argument contract has no logger parameter) and are
+ * skipped; a legacy non-empty non-conforming `rootChain` keeps the
+ * v0.2.2 failure walk verbatim (P6).
+ *
+ * @module dsh-llm-fallbacks/time-slots
+ */
+import type { FallbacksConfig } from './config.ts';
+/** Official V4 models — the ONLY legal all-day selectors (length 1, XOR). */
+export declare const OFFICIAL_V4_FLASH = "deepseek-official/deepseek-v4-flash";
+export declare const OFFICIAL_V4_PRO = "deepseek-official/deepseek-v4-pro";
+/** The four frozen preset ids (exact strings, spec lock). */
+export declare const PRESET_IDS: readonly ["liang-peak", "liang-valley", "glm-peak", "glm-valley"];
+export type PresetId = (typeof PRESET_IDS)[number];
+/** A frozen UTC+8 window: `start ≤ t < end`, wrap-midnight when `start > end`. */
+export interface SlotWindow {
+    /** Window start, `HH:mm` (24h). */
+    start: string;
+    /** Window end, `HH:mm` — EXCLUSIVE (a window contains `t` iff the day
+     * matches AND (`start ≤ end` ? `start ≤ t < end` : `start ≤ t || t < end`)). */
+    end: string;
+    /** Day mask: 0=Sunday … 6=Saturday. Omitted/empty = every day. */
+    days?: number[];
+}
+/** One extra time-slot row (P4 storage shape; `chain` is always editable). */
+export interface SlotRowConfig {
+    kind: 'preset' | 'custom';
+    /** Preset id — required for `kind: 'preset'`; windows live in
+     * {@link PRESETS}, never stored. */
+    preset?: PresetId;
+    /** Custom-only: window start `HH:mm`. */
+    start?: string;
+    /** Custom-only: window end `HH:mm` (exclusive; may wrap midnight). */
+    end?: string;
+    /** Custom-only: day mask 0=Sunday…6=Saturday; omitted/empty = all days. */
+    days?: number[];
+    /** Custom-only display name (PR #62 feedback round, collapsed rows). */
+    name?: string;
+    /** Models for this row (editable even on preset rows). */
+    chain: string[];
+}
+/** Frozen preset definition (P4): windows are code constants, never stored. */
+export interface PresetDefinition {
+    windows: readonly SlotWindow[];
+    /** `true` = matches iff the peak windows do NOT match (valley derives
+     * from its peak — no duplicated window enumerations that can drift). */
+    complement: boolean;
+    /** Display label for the status strip / settings card. */
+    label: string;
+}
+/**
+ * Frozen preset windows (UTC+8). `liang-*` presets have NO day mask (they
+ * apply every day, weekends included); `glm-peak` is Monday–Friday only.
+ * The two valleys are `complement: true` of their peak.
+ */
+export declare const PRESETS: Record<PresetId, PresetDefinition>;
+/**
+ * All-day conformance (P6): the all-day chain is conforming when its LAST
+ * entry (the tail — the card's 默认模型 panel) is exactly one official V4
+ * model — Flash XOR Pro. Leading entries (the card's 默认降级链 block) are
+ * the ordered walk before that last-resort fallback. An empty chain or a
+ * chain whose tail is not an official V4 model keeps slot rows inert and
+ * refuses the virtual-row override/delegate; the v0.2.2 failure walk over
+ * the raw chain stays verbatim.
+ */
+export declare function isAllDayConforming(chain: readonly string[]): boolean;
+/**
+ * Effective chain for a root request at `now` (P5): the FIRST extra row
+ * whose descriptor contains `now` (stored order) — that row's `chain`
+ * REPLACES the all-day chain (never concatenated); no match ⇒ `rootChain`
+ * (the all-day row, always last and required). Malformed rows warn once
+ * and are skipped; never throws.
+ *
+ * P6 (qc1 F-001): without a conforming all-day the slot rows are inert, so
+ * this IS the raw `rootChain` — the gate lives in {@link resolveSlotState},
+ * the single source every slot surface (this, the 分时切换 log, the
+ * `/fallbacks` strip, select-is-primary, the virtual adapter delegate) reads.
+ */
+export declare function resolveEffectiveChain(config: FallbacksConfig, now: Date, tz: string): string[];
+/**
+ * Slot winner + display label (P5): drives 分时切换 detection (per-root-agent
+ * last-winner marker, in-process only) and the card / `/fallbacks` status
+ * strip. `winner` is the matching row or `'all-day'`; `label` names the
+ * slot (frozen preset label or `custom HH:mm-HH:mm`).
+ *
+ * P6 gate (qc1 F-001): without a conforming all-day
+ * (`isAllDayConforming(config.rootChain)`) the winner is ALWAYS `'all-day'`
+ * — a legacy multi-model (or empty) chain earns no slot rows, so every
+ * surface fed by this resolver reports the inert state and routing stays on
+ * the raw `rootChain` (the v0.2.2 walk verbatim).
+ */
+export declare function resolveSlotState(config: FallbacksConfig, now: Date, tz: string): {
+    winner: SlotRowConfig | 'all-day';
+    label: string;
+};

package/dist/virtual-adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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).
+ *
+ * Wiring (P2): `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 on `enabled` false→true, unregister on
+ * true→false, driven by the settings `onChange` hook (the returned
+ * reconcile thunk, wired by `apply()`) plus child activation. The row is
+ * visible whenever the plugin is enabled — a non-conforming all-day chain
+ * does NOT hide it (PR #62 feedback); conformance still gates a
+ * successful override/delegate (`effectiveHeadOf` below refuses a
+ * non-conforming all-day). The condition deliberately ignores `timeSlots`
+ * and conformance, so slot-row edits and chain edits never churn
+ * registration.
+ *
+ * Adapter behavior (P1/P3): `listModels` advertises exactly the one virtual
+ * row; `stream()` is a THIN single-hop delegate to the effective chain head
+ * through the host LLM runtime — no chain walk, no cooldown/caps/revert
+ * bookkeeping, no state writes (a failure inside the delegate surfaces at
+ * `agent/request-error`, where the existing engine walks from there).
+ * `resolveModel` proxies the current effective head's metadata when
+ * resolvable (modalities/context-window/reasoning follow the head) with a
+ * permissive default otherwise — never throws.
+ *
+ * @module dsh-llm-fallbacks/virtual-adapter
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FallbacksConfig } 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";
+/**
+ * `LlmError` code: the effective chain is empty — the virtual route has no
+ * head to delegate to (P1 guard).
+ */
+export declare const EMPTY_EFFECTIVE_CHAIN_CODE = "EMPTY_EFFECTIVE_CHAIN";
+/**
+ * `LlmError` code: the effective chain head is not a dispatchable real pair
+ * (non-conforming all-day, wildcard selector, malformed selector, or a
+ * self-route back to `FallbacksChain/*` — the P1 recursion guard).
+ */
+export declare const UNDISPATCHABLE_HEAD_CODE = "UNDISPATCHABLE_EFFECTIVE_HEAD";
+/** `LlmError` code (defensive): the `llm` runtime disappeared mid-flight. */
+export declare const LLM_UNAVAILABLE_CODE = "LLM_UNAVAILABLE";
+/** One dispatchable exact head: `provider/model`. Wildcards are never seeds (P3). */
+export interface EffectiveHead {
+    provider: string;
+    model: string;
+}
+/**
+ * The FIRST DISPATCHABLE exact head of a chain — the single definition of
+ * "effective head" (F-001) shared by the root select-is-primary override
+ * (`src/index.ts`) and the virtual adapter's delegate paths. 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.
+ */
+export declare function firstDispatchableExactHead(chain: readonly 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.
+ */
+export declare function pickerDisplayName(config: FallbacksConfig, now?: Date, modelDisplayName?: string): string;
+/**
+ * Install the virtual adapter registration lifecycle (P2).
+ *
+ * @param ctx - the plugin context.
+ * @param readConfig - live config reader (the same `source()` the runtime
+ *   reads, so reconcile always sees COMMITTED composed snapshots).
+ * @returns the reconcile thunk — call it from the settings `onChange` hook
+ *   (child activation runs one reconcile on its own).
+ */
+export declare function installFallbacksAdapter(ctx: Context, readConfig: () => FallbacksConfig): () => void;

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +48,7 @@
     "build-client": "tsx scripts/build-client.ts",
     "release:prepare": "tsx scripts/prepare-release.ts",
     "release:validate": "tsx scripts/validate-release-version.ts",
+    "repair:fallbacks-switch-logs": "tsx scripts/repair-fallbacks-switch-logs.ts",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc --noEmit",
     "prepare": "pnpm run build"
@@ -57,24 +58,24 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-web-react": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-web-react": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.0-rc.7",
     "react": "^18.2.0",
     "@deepseek-ai/schemastery": "^3.18.1"
   },