dsh-llm-fallbacks 0.4.1 → 0.4.3

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
@@ -169,9 +189,17 @@ export declare class FallbackStateStore {
      */
     syncRecovery(state: AgentFallbackState, now: number, mode: RecoveryPolicy): void;
     /**
-     * Observed completion ⇒ close the circuit (plan P2 rule 6): acts only when
-     * the entry exists and is half-open; otherwise a no-op (a stale in-flight
-     * success must not cancel a fresher escalated re-suppression).
+     * Observed completion ⇒ close the circuit (plan P2 rule 6). The lazy
+     * expiry runs FIRST — the same read the decision path performs — so a
+     * cooldown that lapsed BEFORE this completion is treated as what it is:
+     * an expired suppression, not an active one. The completion is
+     * post-expiry evidence and closes the circuit even when no decision-path
+     * read has transitioned the entry to half-open yet (a manual
+     * re-selection of the route, or a route no walk ever consulted because the
+     * current route kept succeeding). An ACTIVE suppression (`until > now`,
+     * including the `Infinity` of `revertPolicy: 'never'`) is untouched:
+     * a stale in-flight success must not cancel a fresher escalated
+     * re-suppression.
      */
-    observeSuccess(state: AgentFallbackState, key: string): void;
+    observeSuccess(state: AgentFallbackState, key: string, now?: number): void;
 }

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

package/scripts/build-client.ts

@@ -362,7 +362,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}`