dsh-llm-fallbacks 0.6.13 → 0.8.0

package/dist/virtual-adapter.d.ts

@@ -1,67 +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): `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. `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 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";
-/**
- * `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;
@@ -69,10 +40,10 @@ export interface EffectiveHead {
 }
 /**
  * The FIRST DISPATCHABLE exact head of a chain — the single definition of
- * "effective head" (F-001) shared by the virtual adapter's delegate paths and
- * the routing engine's served-route anchor (`anchorServedRoute` in
- * `src/index.ts`). Walks the SAME chain `resolveEffectiveChain` produces,
- * skipping entries that can never
+ * "effective head" (F-001) shared by this module's metadata paths
+ * (`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
@@ -80,91 +51,69 @@ export interface EffectiveHead {
  */
 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 and `stream()` throws
- * {@link UNDISPATCHABLE_HEAD_CODE}.
+ * 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()` 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.
+ * The virtual adapter (P1/P3). `stream()` hands the call to the injected walk
+ * (see `src/chain-walk.ts`) — registration metadata stays here.
  */
 export declare class FallbacksChainAdapter extends LlmAdapter {
     private readonly readConfig;
     private readonly getLlm;
-    constructor(readConfig: () => FallbacksConfig, getLlm: () => LlmRuntime | undefined);
+    private readonly walk;
+    constructor(readConfig: () => FallbacksConfig, getLlm: () => LlmRuntime | undefined, walk: (options: GenerateOptions) => AsyncIterable<StreamChunk>);
     /** 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. */
+    /** 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;
     /**
-     * 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.
+     * 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>;
 }
@@ -174,7 +123,9 @@ export declare class FallbacksChainAdapter extends LlmAdapter {
  * @param ctx - the plugin context.
  * @param readConfig - live config reader (the same `source()` the runtime
  *   reads, so reconcile always sees COMMITTED composed snapshots).
+ * @param walk - the chain walk the adapter's `stream()` runs for one virtual
+ *   call (built by `apply()` over its live state — see `src/chain-walk.ts`).
  * @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;
+export declare function installFallbacksAdapter(ctx: Context, readConfig: () => FallbacksConfig, walk: (options: GenerateOptions) => AsyncIterable<StreamChunk>): () => void;

package/docs/DETAIL.md

@@ -0,0 +1 @@
+![A request failing on an auth code in the FallbacksChain walk, the next provider/model serving it, the switch log line, and the FallbacksChain / Auto row in the model picker](preview.svg)

package/docs/DETAIL.zh.md

@@ -0,0 +1 @@
+![请求在降级链上命中认证失败码后由下一个 provider/model 接手、切换日志，以及模型选择器中的 FallbacksChain / Auto 行](preview.zh.svg)