dsh-llm-fallbacks 0.7.0 → 0.8.0

package/dist/role-resolution.d.ts

@@ -1,38 +1,22 @@
 /**
- * Dispatch-time role resolution (plan fallbacks-role-automatch Task 2; the
- * dispatch-role stage added by plan dsh-148-agent-team-role-delivery Task 1).
- *
- * Precedence (first hit wins) across three ordered stages:
+ * Dispatch-time role resolution (named virtual chains, plan
+ * named-virtual-chains T3): narrowed to TWO stages —
  * 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 the next stage;
+ *    id → that role's DECLARED RAW id (via the `roleIds` trimmed-id map); the
+ *    reserved `'inherit'` and undeclared presets are NEVER dispatchable
+ *    explicit roles;
  * 2. dispatch — `opts.dispatchRole`: the role the dispatch seam resolved from
  *    the Assignment/teammate prompt (`**Execute as**: <id>`, the single
  *    parser in `src/subagents-seam.ts`), canonicalized by the same trim +
  *    `roleIds` lookup. An absent, empty, `'inherit'` or no-longer-declared
- *    reference falls through silently — a role removed after the dispatch is
- *    not an error;
- * 3. rules — the existing `resolveRole` passthrough, unchanged (a declared
- *    role wins; no-rule-match / an explicit rule targeting `'inherit'`
- *    resolve to `'inherit'`).
- *
- * `'inherit'` is the single "no specific role" outcome — reached by
- * no-rule-match OR an explicit rule targeting `'inherit'`.
+ *    reference resolves to `undefined` — no role, no error.
  *
- * There is deliberately NO auto-match stage: the only host point it ever had
- * was the deleted `agent/request` inject, and running an LLM call inside the
- * walk's `stream()` would be a nested request per failure (design
- * dsh-022-rc1-upgrade §2.2). Resolution is therefore pure and synchronous —
- * the walk must throw its pre-attempt errors before the first chunk.
+ * The rules stage is DELETED with `roles.rules` (v2). `undefined` is the
+ * single "no specific role" outcome — the plugin does not intervene and the
+ * child inherits the delegating agent's route.
  *
  * @module dsh-llm-fallbacks/role-resolution
  */
-import { type FallbacksRoleRule } from './config.ts';
-import { type AgentLike } from './roles.ts';
-export type { FallbacksRoleRule } from './config.ts';
-/** Options for {@link resolveDeclaredRole}. */
 export interface DeclaredRoleOptions {
     /**
      * Dispatch-declared role: the DECLARED RAW id the seam resolved from the
@@ -40,27 +24,14 @@ export interface DeclaredRoleOptions {
      * live `roleIds` map; absent, `inherit`, or no-longer-declared → skipped.
      */
     dispatchRole?: string;
-    /** Warning sink — the decision path injects the plugin logger. */
-    warn: (message: string) => void;
-    /**
-     * The route the agent's request was actually SERVED by, when that differs
-     * from the pair recorded on the agent (the virtual `FallbacksChain/Auto`
-     * row). Rule matching accepts either, so a rule keyed on the real chain head
-     * keeps matching a child whose recorded route is the virtual pair (QC1 I-1).
-     * `undefined` for every real route.
-     */
-    servedRoute?: {
-        provider: string;
-        model: string;
-    };
 }
 /**
- * The dispatch role: explicit → dispatch-declared → rules.
+ * The dispatch role: explicit preset → dispatch-declared. Returns
+ * `undefined` when neither stage resolves (NOT SPECIFIED — no plugin
+ * intervention).
  *
  * `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).
+ * by trim and returns the DECLARED RAW id.
  */
-export declare function resolveDeclaredRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, opts: DeclaredRoleOptions): string;
+export declare function resolveDeclaredRole(agentPreset: string | undefined, roleIds: ReadonlyMap<string, string>, opts: DeclaredRoleOptions): string | undefined;

package/dist/schema.d.ts

@@ -15,9 +15,10 @@
  * Object fields are optional by default in schemastery; `.default()` fills
  * the spec defaults, `.required()` keeps mandatory fields. Unknown keys are
  * RETAINED by the composition (verified plan Task 1 Step 1) — that is what
- * lets `detectLegacyKeys` flag two-block-era leftovers (`chains` /
- * `roles.default`) on the composed object at startup (warn + gateway
- * `legacyKeys`, see `src/index.ts` apply()).
+ * lets `detectLegacyKeys` flag v1 two-block leftovers (`rootChain` /
+ * `roles.rules` / …) on the composed object at startup (warn-only
+ * migration; the gateway strips them via LEGACY_KEYS, see
+ * `src/gateway.ts`).
  *
  * Current host contract: the whole schema is marked `volatile` (the host
  * retired `installSection` — the Loader entry Config IS the settings
@@ -34,7 +35,7 @@
  * @module dsh-llm-fallbacks/schema
  */
 import z from '@deepseek-ai/schemastery';
-import type { FallbacksConfig } from './config.ts';
+import type { FallbacksConfigSource } from './config.ts';
 declare module '@deepseek-ai/schemastery' {
     namespace Schemastery {
         interface Meta {
@@ -43,4 +44,4 @@ declare module '@deepseek-ai/schemastery' {
         }
     }
 }
-export declare const Config: z<FallbacksConfig>;
+export declare const Config: z<FallbacksConfigSource>;

package/dist/seeds.d.ts

@@ -42,7 +42,7 @@
  *
  * @module dsh-llm-fallbacks/seeds
  */
-import { type FallbackStrategy, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRoles } from './config.ts';
+import { type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRoles } from './config.ts';
 /** A seed declaration from a companion plugin (spec §9.1). */
 export interface SeedDeclaration {
     id: string;
@@ -112,10 +112,8 @@ export interface EffectiveRole {
     id: string;
     /** Effective row persona. */
     persona: string;
-    /** Passthrough — never touched by seeds (R4). */
-    chain?: string[];
-    /** Passthrough — never touched by seeds (R4). */
-    fallback?: FallbackStrategy;
+    /** Passthrough — never touched by seeds (R4): the named-chain POINTER. */
+    chain?: string;
     /** Id is in the live declaration set (trimmed row-id match). */
     seeded: boolean;
     /** `seeded` && row persona !== current seed default. */
@@ -154,7 +152,7 @@ export interface SeedsWireStatus {
 export interface SeedsIo {
     /** Fresh composed config read (the same source the gateway reads). */
     read(): FallbacksConfig;
-    /** Persist a full `{ list, rules }` to the settings user layer. */
+    /** Persist the `{ list }` to the settings user layer. */
     writeRoles(roles: FallbacksRoles): Promise<void>;
 }
 /**
@@ -192,7 +190,7 @@ export declare class FallbacksSeedManager {
      * RESOLVED effective default before/after the candidate slice commit
      * (at-default tracking follows the resolution winner — a producer that
      * is not the winner for an id it declares never rewrites the row),
-     * writes only when the computed `{ list, rules }` differs from the
+     * writes only when the computed `{ list }` differs from the
      * current composed roles (idempotent, AC-1), and commits the slice only
      * after a successful write (compute → write → commit; retry-safe). An
      * empty batch drops the producer's slice.

package/dist/state.d.ts

@@ -16,51 +16,9 @@
  *
  * @module dsh-llm-fallbacks/state
  */
-import type { FallbackSwitchReason } from './events.ts';
 import { CooldownStore } from './cooldown.ts';
 import { RecoveryStore } from './recovery.ts';
 import type { RecoveryPolicy } from './config.ts';
-/**
- * One plugin-originated subagent switch the host allowlist blocked (plan
- * dsh-012-subagent-routing T3; spec D1). The intersection of the resolved
- * candidates with the effective allowlist was empty while the unconstrained walk
- * would have switched — the attempt is recorded in-memory only (issue #52:
- * no durable session write) for the Subagents card warning (spec D4/T5).
- */
-export interface BlockedSwitchAttempt {
-    /** Epoch ms when the switch was blocked. */
-    at: number;
-    /** The route the unconstrained walk would have switched to (exact provider+model). */
-    route: {
-        provider: string;
-        model: string;
-    };
-    /** The failure reason that triggered the would-be switch. */
-    reason: FallbackSwitchReason;
-}
-/**
- * How the effective subagent chain head was chosen (plan dsh-012-subagent-routing
- * T5 / T2 M3). Lives on a per-agent map (mirrors {@link BlockedSwitchAttempt}),
- * not on {@link AgentFallbackState}. The write point is the dispatch seam
- * (direction C): `authorized` = the spawn request carried an explicit route,
- * `injected` = the seam mounted the child on the virtual chain row.
- */
-export type ChainHeadSource = 'authorized' | 'injected';
-/**
- * The effective chain head for one subagent, plus the source label the
- * Subagents card renders (spec D4). In-memory only (issue #52).
- */
-export interface EffectiveChainHead {
-    /** Epoch ms when this head was recorded (recency for the card snapshot). */
-    at: number;
-    /** Exact provider+model of the effective chain head. */
-    route: {
-        provider: string;
-        model: string;
-    };
-    /** `authorized` = host spawn preserved; `injected` = plugin role-inject. */
-    source: ChainHeadSource;
-}
 /** One agent's fallback runtime state. */
 export interface AgentFallbackState {
     /** `provider/model → expiry epoch ms`; lazily expired on read. */

package/dist/subagents-seam.d.ts

@@ -61,22 +61,25 @@
  * before the child's first pre-step. This module reads no provider persona
  * capability and injects no agent preset.
  *
- * Virtual chain mount (plan dsh-022-rc1-upgrade §1.3; direction C): the SAME
- * resolution point is where a dispatch child is mounted on the virtual
- * `FallbacksChain/Auto` row — `request.agentOptions` is stamped (rc.1 merges
- * it over the parent's route when `manager.startLocal` creates the child) when
- * all five conditions hold: a resolved role, no explicit `agentOptions` route
- * (explicit = authorized, untouched), a LOCAL backend, an active config whose
- * resolved role chain has a dispatchable exact head ON the host allowlist when
- * the subagent policy is `enabled`, and a policy that is not `unprovable`. The
- * record carries `virtualRouteInjected` (sticky) and the effective chain head
- * is labelled in `chainHeads` (`injected` / `authorized`). Injection is
+ * Role chain stamp (named virtual chains §3, `injectRoleChain`): the SAME
+ * resolution point is where a dispatch child is pointed at a named chain —
+ * `request.agentOptions` is stamped with `{ provider: 'FallbacksChain',
+ * model: <role.chain> }` (rc.1 merges it over the parent's route when
+ * `manager.startLocal` creates the child) when all FOUR conditions hold: a
+ * declared role resolved, its `chain` is non-empty AND declared, the request
+ * carries no explicit `agentOptions` (explicit = authorized, untouched), and
+ * the backend is LOCAL. No host-policy consultation: the mapping is the
+ * user's STATIC config, never a model-authored route — no allowlist, no
+ * `unprovable` branch, no `virtualRouteInjected` flag. The seam does NOT
+ * check conformance: a declared-but-non-conforming chain is still stamped and
+ * the walk's own tail gate refuses it — one gate, in the walk. Injection is
  * creation-time only BY CONSTRUCTION: rc.1's `startActivation` rejects any
- * child id that already exists (`DUPLICATE_CHILD`), so this path never attaches
- * to an existing child and cannot overwrite its durable selection — a
- * caller-reserved `childId` is a pre-chosen identity for a NEW child. A
- * non-injectable dispatch forwards the caller's spec untouched (external
- * backends keep pure inheritance).
+ * child id that already exists (`DUPLICATE_CHILD`): a caller-reserved
+ * `childId` the seam already recorded is a RE-ACTIVATION of that child (its
+ * durable selection is already fixed), so it stamps nothing — that activation
+ * writes the role record only (I-000081). A non-stamped dispatch forwards the
+ * caller's spec untouched (external backends keep pure inheritance; not
+ * specified ⇒ the child inherits the delegating agent's route).
  *
  * In-session notice row (plan Task 3): the SAME install point registers the
  * `agent/pre-step` emitter (`./role-notice.ts`) over the record map it owns, so
@@ -107,8 +110,6 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { type FallbacksConfig, type FallbacksRole } from './config.ts';
-import type { EffectiveChainHead } from './state.ts';
-import type { EffectivePolicy } from './subagent-policy.ts';
 /**
  * The cordis service-read waterfall event the seam registers on. Referenced
  * ONCE (registration) so a future cordis rename is a one-line change here.
@@ -168,18 +169,6 @@ export interface SubagentSeamRecord {
      * `true` survives.
      */
     personaNotApplied?: boolean;
-    /**
-     * `true` when this dispatch MOUNTED the child on the virtual
-     * `FallbacksChain/Auto` row (design §1.3): the plugin stamped the creation
-     * options, so the child's chain is plugin-originated and its switches are
-     * allowlist-filtered. Read by the chain walk (`ChainWalkDeps.seamRecord`)
-     * and never by a host surface.
-     *
-     * STICKY, like `personaNotApplied`: the mount happened at spawn and a record
-     * rewrite (a resume reusing the `childId`) carries no verdict of its own, so
-     * the first `true` survives.
-     */
-    virtualRouteInjected?: true;
 }
 /** One consumed prompt content block (`@deepseek-ai/dsh-llm` `ContentBlock` text members). */
 export interface SubagentPromptBlockView {
@@ -243,21 +232,10 @@ export interface SubagentSeamOptions {
     roles?: () => readonly FallbacksRole[];
     /**
      * Live config reader — the SAME `source()` the runtime and the adapter walk
-     * read. Absent ⇒ the seam never mounts a child on the virtual route (a
-     * partial wiring keeps the native dispatch unchanged).
+     * read. Absent ⇒ the seam never stamps a role chain (a partial wiring keeps
+     * the native dispatch unchanged).
      */
     source?: () => FallbacksConfig;
-    /**
-     * The host subagent model-selection policy for one agent (guarded read,
-     * fail-closed). Absent ⇒ treated as `'disabled'` (no policy to fail closed
-     * on); an `'unprovable'` answer skips the mount.
-     */
-    policyFor?: (agentId: string) => EffectivePolicy;
-    /**
-     * Per-agent effective chain head, keyed by child session id (the Subagents
-     * card's read). Absent ⇒ the seam records no head label.
-     */
-    chainHeads?: Map<string, EffectiveChainHead>;
     /** Contained debug sink (at most one line per contained degrade). */
     debug?: (message: string) => void;
 }
@@ -331,15 +309,15 @@ export declare function resolveDeclaredRoleFromAssignment(prompt: string, roleId
  * DECLARED RAW id the seam already resolved, so this is an exact id match, not
  * a second canonicalization pass.
  *
- * Only `id` and `persona` are read: no `chain`, no `rootChain`, no routing
- * state — a `chain: []` role's persona resolves exactly like a chained one's.
+ * Only `id` and `persona` are read: no `chain` pointer, no routing state — a
+ * role that specifies a chain names its persona exactly like one that does not.
  *
  * @param roles - the live declared roles (`roles.list`).
  * @param roleId - the DECLARED RAW role id resolved at the seam.
  */
 export declare function personaForRole(roles: readonly FallbacksRole[], roleId: string): string | undefined;
 /**
- * @internal Test seam (mirrors `chainHeads`): the seam installed on
+ * @internal Test seam: the seam installed on
  * `ctx`, if any. Not part of the plugin's public surface — lets tests read and
  * seed the per-child record map without reaching into the installation
  * closure. `undefined` when no seam is installed.

package/dist/time-slots.d.ts

@@ -9,12 +9,12 @@
  * 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
- * legacy failure walk verbatim (P6).
+ * skipped; a non-empty non-conforming `entries` tail keeps the failure walk
+ * verbatim (the chain's delegate stays inert).
  *
  * @module dsh-llm-fallbacks/time-slots
  */
-import type { FallbacksConfig } from './config.ts';
+import type { NamedChain } from './config.ts';
 /** Official all-day selectors — the ONLY legal tails (length 1, XOR):
  * Flash (the current official default) and Pro, both selectable. The Pro
  * tail id is the catalog id verbatim: the official default catalog
@@ -87,32 +87,29 @@ export declare const PRESETS: Record<PresetId, PresetDefinition>;
  */
 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.
+ * Effective chain for a request on ONE named chain at `now`: the FIRST
+ * matching row of {@link NamedChain.timeSlots} (stored order) — that row's
+ * `chain` REPLACES {@link NamedChain.entries} (never concatenated); no match
+ * ⇒ the chain's own `entries`. 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, the virtual adapter delegate, its served-route anchor)
- * reads.
+ * Without a conforming entries tail the slot rows are inert, so this IS the
+ * raw `entries` — the gate lives in {@link resolveSlotState}, the single
+ * source every slot surface reads.
  */
-export declare function resolveEffectiveChain(config: FallbacksConfig, now: Date, tz: string): string[];
+export declare function resolveEffectiveChain(chain: NamedChain, 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`).
+ * Slot winner + display label for one named chain: drives 分时切换 detection
+ * (per-(agent, chain) 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 legacy walk verbatim).
+ * Gate: without a conforming entries tail (`isAllDayConforming(chain.entries)`)
+ * the winner is ALWAYS `'all-day'` — a 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 `entries`.
  */
-export declare function resolveSlotState(config: FallbacksConfig, now: Date, tz: string): {
+export declare function resolveSlotState(chain: NamedChain, now: Date, tz: string): {
     winner: SlotRowConfig | 'all-day';
     label: string;
 };

package/dist/tui-settings.d.ts

@@ -114,14 +114,11 @@ export declare const FALLBACKS_TUI_SECTION_NS = "fallbacks";
  */
 export declare const JSON_FIELD_MAX_DRAFT_BYTES: number;
 /**
- * The `fallbacks` /settings section: 10 fields covering the web-card
- * capabilities (the default-model choice rides `rootChain`'s last entry and
- * the per-role fallback strategy rides `roles.list` JSON; the config-level
- * `enabled` switch is REMOVED — plan fallbacks-web-ux-alignment T2, the
- * Plugins-page row toggle is the master switch and the runtime gates read
- * content presence; the always-mode retry cap and the dispatch role
- * auto-match switch are REMOVED with their mechanisms — direction C, only a
- * `FallbacksChain/Auto` session walks a chain). Scalar
+ * The `fallbacks` /settings section covering the web-card capabilities
+ * (named virtual chains v2: ONE `Chains (JSON)` field over `chains` on the
+ * same bounded-parse machinery; `Roles (JSON)` keeps the chain POINTER; the
+ * v1 `rootChain` / top-level `timeSlots` / `roles.rules` fields are REMOVED
+ * with their mechanisms). Scalar
  * capabilities use native kinds (boolean/number/select); complex structures
  * use `text` fields with custom `format`/`parse` that mirror the gateway's
  * validation. Built fresh per call — the host deep-freezes whatever it