dsh-llm-fallbacks 0.2.2 → 0.3.0

package/dist/roles.d.ts

@@ -9,8 +9,13 @@
  * `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
@@ -27,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
@@ -42,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 {

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.2",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",