dsh-llm-fallbacks 0.4.2 → 0.4.4

package/dist/seeds.d.ts

@@ -11,10 +11,13 @@
  * State model (spec §9.2) — two stores, strictly separated:
  * 1. operator config rows (persisted; a seeded role is a plain
  *    `roles.list` row `{ id, persona }`), and
- * 2. an in-memory per-apply seed registry (`Map<id, seedPersona>`),
- *    declare = replacement (the batch is the companion's full current set).
- * `seeded` / `personaOverridden` are DERIVED at read time, never stored —
- * a config round-trip cannot orphan an override (AC-3).
+ * 2. an in-memory per-apply seed registry (`Map<id, { persona, set }>` —
+ *    the declared default persona plus its provenance label), declare =
+ *    replacement (the batch is the companion's full current set).
+ * `seeded` / `personaOverridden` / `source` are DERIVED at read time, never
+ * stored — a config round-trip cannot orphan an override (AC-3), and
+ * provenance rides the in-memory registry only, so it can never churn a
+ * settings write.
  *
  * Materialization (spec §9.2): append `{ id, persona }` (two keys only,
  * R4) / attach row untouched / at-default tracking / override preserved +
@@ -31,6 +34,41 @@ export interface SeedDeclaration {
     id: string;
     persona: string;
 }
+/**
+ * Per-row provenance label (spec §2). The fixed labels: `bundled` (the
+ * plugin's own bundled preset self-declare), `external` (a companion
+ * declare without a set name — or with an invalid one, degraded), `user`
+ * (no live declaration). Any other value is a declared set name; the
+ * reserved names can never be declared as a set, so the fixed labels are
+ * unambiguous.
+ */
+export type SeedSource = 'bundled' | 'external' | 'user' | (string & {});
+/**
+ * Optional provenance for one `declare()` call (spec §2) — the PUBLIC
+ * options face (a companion's registered set name). This is also the type
+ * of the `FallbacksService.declareSeeds` second parameter: consumers can
+ * never label a declare `bundled` (reserved).
+ */
+export interface SeedsDeclareOptions {
+    /**
+     * Registered set name — trimmed. Empty after trim, non-string, or a
+     * reserved value (`bundled` / `user` / `external`) warns once and
+     * degrades the batch to the unnamed `external` source; the seeds still
+     * apply (a bad label must never drop roles).
+     */
+    set?: string;
+}
+/**
+ * The manager-level declare options — the public face plus the INTERNAL
+ * bundled marker for the plugin's own preset self-declare. Module-internal
+ * (never exported, never re-exported from the package root): only the
+ * preset child call site passes `bundled`, and only a structurally-checked
+ * object literal at that — the type itself is not nameable by consumers.
+ */
+interface SeedsInternalDeclareOptions extends SeedsDeclareOptions {
+    /** INTERNAL — bundled preset self-declare provenance. Not a consumer option. */
+    bundled?: true;
+}
 /**
  * Why one declared id was skipped (spec §9.1). Per-id skip + warn, never
  * coercion — valid siblings in the same batch still apply (AC-5).
@@ -68,6 +106,8 @@ export interface EffectiveRole {
     seeded: boolean;
     /** `seeded` && row persona !== current seed default. */
     personaOverridden: boolean;
+    /** Where the row's seed state comes from (read-time derived, never persisted) — `user` iff not seeded. */
+    source: SeedSource;
     /** Present iff seeded. */
     seedPersona?: string;
 }
@@ -86,6 +126,12 @@ export interface SeedRevertOutcome {
 export interface SeedsWireStatus {
     id: string;
     overridden: boolean;
+    /**
+     * Provenance label (spec §2) — additive and OPTIONAL on the wire: a
+     * gateway predating the field (version skew) sends entries without it;
+     * consumers treat a missing label as "no badge".
+     */
+    source?: SeedSource;
 }
 /**
  * The narrow IO seam this module writes through — keeps `src/seeds.ts`
@@ -105,6 +151,7 @@ export interface SeedsIo {
  */
 export declare class FallbacksSeedManager {
     private readonly logger;
+    /** Per-apply declaration registry: declared default persona + provenance label. */
     private registry;
     constructor(logger: FallbacksConfigLogger);
     /**
@@ -112,6 +159,10 @@ export declare class FallbacksSeedManager {
      * companion's FULL current declaration set; ids omitted from the batch
      * drop out of the registry while their rows remain (R2).
      *
+     * `options` labels the whole batch's provenance (spec §2), resolved once
+     * per call: an invalid set name warns once and degrades to the unnamed
+     * `external` case — the seeds still apply.
+     *
      * Per-id validation AS DECLARED (spec §9.3): non-string / pattern miss /
      * reserved `inherit` / duplicate-in-batch → skip + warn; valid siblings
      * still apply (AC-5). Materializes per spec §9.2, writes only when the
@@ -119,15 +170,17 @@ export declare class FallbacksSeedManager {
      * (idempotent, AC-1), and commits the registry only after a successful
      * write (compute → write → commit; retry-safe).
      */
-    declare(seeds: readonly SeedDeclaration[], io: SeedsIo): Promise<SeedDeclareOutcome>;
+    declare(seeds: readonly SeedDeclaration[], io: SeedsIo, options?: SeedsInternalDeclareOptions): Promise<SeedDeclareOutcome>;
     /**
      * Readback (b) — sync, derived: every config row annotated with
      * `seeded` / `personaOverridden` / `seedPersona` (trimmed row-id
-     * membership in the live declaration set; persona inequality). Nothing
+     * membership in the live declaration set; persona inequality) plus the
+     * row's provenance `source` (spec §2): the declaring set's label, or
+     * `user` when no live declaration covers the row. Nothing
      * override-shaped is stored, so a config round-trip cannot orphan state.
      */
     effectiveRoles(io: SeedsIo): EffectiveRolesReadback;
-    /** Card badge state (spec §9.4): seeded rows, with the override flag. */
+    /** Card badge state (spec §9.4): seeded rows, with the override flag and the provenance label. */
     wireStatus(io: SeedsIo): SeedsWireStatus[];
     /**
      * Revert one id to the CURRENT declared seed default (AC-3). Writes
@@ -139,3 +192,4 @@ export declare class FallbacksSeedManager {
     revert(id: string, io: SeedsIo): Promise<SeedRevertOutcome>;
     private warnSkip;
 }
+export {};

package/dist/state.d.ts

@@ -31,6 +31,19 @@ import type { FallbackSwitchReason } from './events.ts';
 import { CooldownStore, StepFailureSet } from './cooldown.ts';
 import { RecoveryStore } from './recovery.ts';
 import type { RecoveryPolicy } from './config.ts';
+/**
+ * What a switch's failure was actually about.
+ *
+ * `'route'` (the default) is every failure the plugin has ever walked: the
+ * provider/model itself is unhealthy (auth, quota, rate limit, ...), so the
+ * from-route is cooled down and counted as a route failure.
+ * `'request'` is a failure of the REQUEST on a healthy route — a
+ * `CONTEXT_WINDOW_EXCEEDED` rejection is the request being too big, not the
+ * model being down. `commit()` keeps the step-scoped bookkeeping for those
+ * but writes no suppression and no recovery failure (see `src/index.ts`
+ * `REQUEST_SCOPED_CODES`).
+ */
+export type SwitchScope = 'route' | 'request';
 /** Decision awaiting application at the next `agent/request` boundary (spec §5.1). */
 export interface PendingSwitch {
     from: {
@@ -43,6 +56,13 @@ export interface PendingSwitch {
     };
     role: string;
     reason: FallbackSwitchReason;
+    /**
+     * What the failure was about — absent means `'route'`, the semantics every
+     * switch had before request-scoped codes existed (same optional-with-a-
+     * documented-default idiom as `FallbacksRole.fallback`). Only the
+     * `agent/request-error` listener ever sets `'request'`.
+     */
+    scope?: SwitchScope;
 }
 /**
  * One plugin-originated subagent switch the host allowlist blocked (plan

package/dist/time-slots.d.ts

@@ -1,6 +1,6 @@
 /**
  * Time-slot rows for `fallbacks` (plan fallbacks-timeslots Task 1, pins
- * P4–P6): frozen preset windows, the official-V4 all-day conformance
+ * P4–P6): frozen preset windows, the official all-day conformance
  * guard, and the pure `resolveEffectiveChain` / `resolveSlotState`
  * resolver.
  *
@@ -15,9 +15,17 @@
  * @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";
+/** Official all-day selectors — the ONLY legal tails (length 1, XOR):
+ * Flash (the current official default, selectable) and Pro (displayed but
+ * disabled — its model is not yet served by the 0.1.5-rc.1 catalog). The
+ * retired V4 ids (`deepseek-v4-flash` / `deepseek-v4-pro`) are no longer
+ * legal tails. */
+export declare const OFFICIAL_FLASH = "deepseek-official/deepseek-flash";
+export declare const OFFICIAL_PRO = "deepseek-official/deepseek-pro";
+/** The two official all-day tail ids (XOR — exactly one legal tail). */
+export declare const OFFICIAL_ALL_DAY_IDS: readonly ["deepseek-official/deepseek-flash", "deepseek-official/deepseek-pro"];
+/** Whether `id` is one of the two official all-day tail ids. */
+export declare function isOfficialAllDayId(id: string): boolean;
 /** 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];
@@ -65,12 +73,13 @@ export interface PresetDefinition {
 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.
+ * entry (the tail — the card's 默认模型 panel) is exactly one official
+ * model — Flash or Pro (XOR). 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 model (including the retired V4
+ * ids) 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;
 /**

package/dist/tui-settings.d.ts

@@ -125,12 +125,14 @@ export declare const JSON_FIELD_MAX_DRAFT_BYTES: number;
 export declare function buildFallbacksTuiSection(): TuiSettingsSection;
 /**
  * Register the `fallbacks` section on the optional `tuiSettingsSections`
- * service. First-fiber-only (`serviceOwned === true` — mirrors
- * `installTuiClient` and the gateway/typert multi-fiber dedupe; the host
- * registry throws on a duplicate namespace, so a deduped later fiber must
- * never register). The service is optional: a composition without
- * `dsh-tui-settings-sections` keeps the plugin working and simply omits the
- * TUI settings surface.
+ * service. Gated by `serviceOwned` — the optimistic apply-time claim (see
+ * `apply()` in src/index.ts) — with a sibling dedupe guard inside the child,
+ * mirroring `installTuiClient`: the claim is not a fact, so a fiber applying
+ * inside the claim window can race another fiber's registration, and the
+ * host registry's duplicate throw must degrade (no-op disposer + debug log)
+ * instead of failing the child. Any other error stays loud. The service is
+ * optional: a composition without `dsh-tui-settings-sections` keeps the
+ * plugin working and simply omits the TUI settings surface.
  *
  * The inject child returns the registry disposer so cordis withdraws the
  * registration when this fiber (or the service) goes away.

package/dist/tui.d.ts

@@ -42,11 +42,18 @@ export interface TuiCommandTreeProvider {
 export declare const FALLBACKS_TUI_ROOT = "fallbacks";
 /**
  * Register the `/fallbacks` provider on the optional `tuiCommandTrees`
- * service. First-fiber-only (`serviceOwned === true` — mirrors the
- * gateway/typert multi-fiber dedupe; the host registry throws on duplicate
- * roots, so a deduped later fiber must never register). The service is
- * optional: a composition without `dsh-tui-command-trees` keeps the plugin
- * working and simply omits the TUI surface.
+ * service. Gated by the OPTIMISTIC `serviceOwned` claim taken at apply time
+ * (the service itself is provided inside the settings inject child, after
+ * apply returns — see `apply()` in src/index.ts), with the sibling dedupe
+ * guard inside the child: the claim is not a fact, so a fiber applying
+ * inside the claim window registers here and, when it loses the race for
+ * the host registry's root, degrades via the `already registered` catch
+ * below — only a post-settlement duplicate fiber skips at this gate (its
+ * claim INITIALIZED false: the service was already visible when the claim
+ * was taken; the child-side catch correction settles strictly after apply()
+ * and can never influence this synchronous read). The service is optional:
+ * a composition without `dsh-tui-command-trees` keeps the plugin working
+ * and simply omits the TUI surface.
  *
  * The inject child returns the registry disposer so cordis withdraws the
  * registration when this fiber (or the service) goes away.

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -60,45 +60,65 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-chat": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-commands": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm-retry": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-tool-subagent": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-commands": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm-retry": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@shikijs/langs": "^4.4.3",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.31",
     "@types/react-dom": "~18.3.7",
     "@types/use-sync-external-store": "^1.5.0",
+    "anser": "^2.3.5",
+    "clsx": "^2.1.1",
+    "immer": "^10.2.0",
     "jsdom": "29.1.1",
+    "katex": "^0.16.47",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "micromark-core-commonmark": "^2.0.3",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-math": "^3.1.0",
+    "micromark-factory-space": "^2.0.1",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "shiki": "^4.4.3",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "zustand": "~4.4.7"
   },
   "repository": {
     "type": "git",

package/scripts/build-client.ts

@@ -48,11 +48,15 @@ const OUT_FILE = 'index.js'
 
 /**
  * Frozen loader module table (dsh mechanism-guide): the plan-documented
- * composition = PLATFORM_MODULES (8 entries in 0.1.2, `web/src/platform.ts:8-15`
- * — the old runtime `./client` exemption became the
- * `@deepseek-ai/dsh-client-store` platform module, so the store VALUE import
- * stays external and resolves from the host loader table) + the
- * PRELOADED_CLIENT_EXTERNALS (empty in 0.1.2, `web/src/platform.ts:16-17`).
+ * composition = PLATFORM_MODULES (9 entries in 0.1.5-rc.1,
+ * `web/src/platform.ts:8-16` — the old runtime `./client` exemption became
+ * the `@deepseek-ai/dsh-client-store` platform module, so the store VALUE
+ * import stays external and resolves from the host loader table) + the
+ * host's PRELOADED_CLIENT_EXTERNALS (empty in `packages/client/web/src/platform.ts`).
+ * The table need not list
+ * every platform module — it lists what this plugin's client half resolves
+ * from the frozen loader table; the rc.1 addition
+ * `@deepseek-ai/dsh-client-ui-dockkit` is not imported by this plugin.
  * rc.8 dropped `dsh-client-web-react` (deleted
  * package — the uSES bridge is vendored in `src/client/use-snapshot.ts`),
  * `dsh-client-ui-attachment` and `dsh-client-schema-form` from the platform
@@ -362,7 +366,12 @@ for (const match of injectedCssMatches) {
     }
   }
 }
-const classMapMatches = [...bundleText.matchAll(/\b\w+_module_css_default\s*=\s*(\{[\s\S]*?\n\s*\});/g)]
+// The class-map object literal is FLAT (string → string, emitted by
+// cssModuleContents as one JSON.stringify), so the lazy match to the first
+// `};` is exact for both emit shapes the printer produces — multi-entry maps
+// across lines and a single-entry map inline (`{ "badge": "_<8hex>_badge" };`
+// has no newline before its closing brace).
+const classMapMatches = [...bundleText.matchAll(/\b\w+_module_css_default\s*=\s*(\{[\s\S]*?\});/g)]
 if (classMapMatches.length === 0) {
   throw new Error('client bundle contract: no inlined css-module class map found — check the dsh-css-modules-inline plugin')
 }

package/scripts/prepare-release.ts

@@ -79,7 +79,7 @@ export function parseArgs(argv: string[]): { version?: string; autoBump: boolean
  * version stays in its prerelease line, bumping only the numeric tail.
  */
 export function autoBumpPatch(current: string): string {
-  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(current)
+  const m = current.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/)
   if (!m) throw new Error(`Cannot auto-bump "${current}": not a parseable X.Y.Z[-pre] version`)
   const [, major, minor, patch, pre] = m
   if (pre === undefined) return `${major}.${minor}.${Number(patch) + 1}`