dsh-llm-fallbacks 0.3.4 → 0.4.0-alpha.1

package/dist/gateway.d.ts

@@ -59,12 +59,73 @@
  * @module dsh-llm-fallbacks/gateway
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
 import type { FallbacksConfig } from './config';
 import type { FallbacksSeedManager, SeedRevertOutcome, SeedsWireStatus } from './seeds';
-/** The `fallbacks` settings namespace (registered when a settings service exists). */
-export declare const FALLBACKS_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/**
+ * The `fallbacks` settings namespace (registered when a settings service
+ * exists). 0.1.2 removed the `settingsNamespace` helper: the registered
+ * namespace is the lowercase-hyphenated literal itself, branded through the
+ * `SettingsNamespace` type the service APIs constrain on.
+ */
+export declare const FALLBACKS_SETTINGS_NAMESPACE: SettingsNamespace;
+/** One exact child LLM route on the additive `subagentPolicy` wire field (T5). */
+export type SubagentPolicyRoute = {
+    provider: string;
+    model: string;
+};
+/**
+ * Additive `/api/fallbacks/get` host-policy snapshot (spec D4 / T5).
+ * Omitted only when the snapshot is unwired (3-arg constructor) so older
+ * clients and gateway unit tests keep a byte-identical `{ config,
+ * legacyKeys, seeds }` payload. A wired snapshot always emits the field —
+ * `{ state: 'disabled' }` included — so a write after an enabled get cannot
+ * keep-last an allowlist. Never written through `set`/`reset`.
+ */
+export type SubagentPolicyWire = {
+    state: 'enabled';
+    allowedModels: SubagentPolicyRoute[];
+    head?: {
+        route: SubagentPolicyRoute;
+        source: 'authorized' | 'injected';
+    };
+    blockedAttempt?: {
+        at: number;
+        route: SubagentPolicyRoute;
+        reason: string;
+    };
+} | {
+    state: 'disabled';
+} | {
+    state: 'unprovable';
+};
+/**
+ * Live host-policy snapshot the gateway projects onto the wire. Built in
+ * `apply()` from the SAME T1 reader the override paths use — no second
+ * policy source. Optional: the 3-arg constructor (gateway unit tests)
+ * omits the field entirely.
+ */
+export type SubagentPolicySnapshotFn = () => {
+    policy: {
+        state: 'disabled';
+    } | {
+        state: 'enabled';
+        allowedModels: readonly SubagentPolicyRoute[];
+    } | {
+        state: 'unprovable';
+    };
+    head?: {
+        route: SubagentPolicyRoute;
+        source: 'authorized' | 'injected';
+    };
+    blockedAttempt?: {
+        at: number;
+        route: SubagentPolicyRoute;
+        reason: string;
+    };
+};
 /**
  * The live configuration source for the gateway (guide §7 — the same bridge
  * shape the runtime reads through). `source()` returns the live composed
@@ -87,6 +148,13 @@ export interface FallbacksReadResult {
     config: FallbacksConfig;
     legacyKeys: string[];
     seeds: SeedsWireStatus[];
+    /**
+     * Host subagent-model-selection policy (spec D4). Additive — old readers
+     * ignore it; omitted only when no snapshot is wired. A wired snapshot
+     * always carries the field (`disabled` included) so keep-last cannot
+     * retain an allowlist after policy-off.
+     */
+    subagentPolicy?: SubagentPolicyWire;
 }
 /** The `fallbacks/revert-seed` response — a read result plus the revert outcome. */
 export interface FallbacksRevertResult extends FallbacksReadResult {
@@ -110,6 +178,12 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
     private readonly seeds;
     /** The live settings service once the optional inject child activates. */
     private settings;
+    /**
+     * Optional host-policy snapshot (T5). When omitted the additive
+     * `subagentPolicy` field is absent on every read — the 3-arg constructor
+     * used by gateway unit tests stays byte-identical to the pre-T5 payload.
+     */
+    private readonly subagentPolicy;
     /**
      * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
      * @param bridge - the same `FallbacksSettingsBridge` the runtime reads, so
@@ -117,8 +191,10 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      * @param seeds - the per-apply `FallbacksSeedManager` constructed in
      *   `apply()` — the gateway delegates badge state and revert to it (no
      *   copied manager logic), through the io seam built over this bridge.
+     * @param subagentPolicy - live host-policy snapshot from `apply()`; omit
+     *   to leave the additive field off the wire.
      */
-    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager);
+    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager, subagentPolicy?: SubagentPolicySnapshotFn);
     /**
      * Read the current composed config (schema defaults → entry base → settings
      * user layer). No hard-gate resolver (ADR-2): the raw composed config is

package/dist/index.d.ts

@@ -16,8 +16,9 @@
  *   cooldown + failure bookkeeping, then return
  *   `{ kind: 'retry' }` (own recovery, no `next()`).
  * - `agent/request` waterfall: apply a pending switch after `await next()`
- *   (provider/model override, inherited `reasoningEffort` dropped — the
- *   `installModelSelection` `withoutInheritedEffort` pattern); a
+ *   (provider/model override; the inherited `reasoningEffort` follows the
+ *   upstream routeChanged rule — dropped on a route change unless explicitly
+ *   named, preserved on a same-route override; spec D3); a
  *   root-origin `FallbacksChain/Auto` seed then overrides to the
  *   effective chain's first exact head (select-is-primary, plan
  *   fallbacks-virtual-chain Task 2); then the always-mode cap check (count
@@ -36,7 +37,7 @@ import { detectLegacyKeys, validateFallbacksConfig, type FallbacksConfig } from
 import { Config } from './schema.ts';
 import { resolveChain } from './chains.ts';
 import { resolveRole } from './roles.ts';
-import { FallbackStateStore } from './state.ts';
+import { FallbackStateStore, type BlockedSwitchAttempt, type EffectiveChainHead } from './state.ts';
 import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome } from './seeds.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
@@ -82,10 +83,12 @@ export { Config };
 /** The plugin's composition config — the `fallbacks` settings schema (spec §4). */
 export type Config = FallbacksConfig;
 export type { FallbackSwitchReason, FallbacksSwitchEventData } from './events.ts';
-export type { AgentFallbackState, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+export type { AgentFallbackState, BlockedSwitchAttempt, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+/** @internal T5 test-seam types (mirrors `BlockedSwitchAttempt`; not public API). */
+export type { ChainHeadSource, EffectiveChainHead } from './state.ts';
 export { resolveRole, type AgentLike, type Origin, } from './roles.ts';
 export { annotateCandidates, createCandidateFilter, hasWildcardEntry, resolveCandidate, resolveChain, resolveChainViews, selectCandidates, type AnnotatedCandidate, type CandidateFilterOptions, type CandidateSkipReason, type FailingModel, } from './chains.ts';
-export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, } from './config.ts';
+export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, type RecoveryPolicy, } from './config.ts';
 export { parseSelector, SelectorError, type Selector, } from './selectors.ts';
 export { FallbacksSeedManager, type EffectiveRole, type EffectiveRolesReadback, type SeedConflict, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertFailReason, type SeedRevertOutcome, type SeedSkipReason, type SeedsIo, type SeedsWireStatus, } from './seeds.ts';
 export { presetRoles } from './presets.ts';
@@ -96,6 +99,23 @@ export { presetRoles } from './presets.ts';
  * request must not grow the store) without reaching into the closure.
  */
 export declare function stateStore(ctx: Context): FallbackStateStore | undefined;
+/**
+ * @internal Test seam (mirrors `stateStore`): the per-agent blocked-switch
+ * attempts recorded by the T3 allowlist gate for the plugin applied to `ctx`
+ * (spec D1; in-memory only, issue #52). Not part of the plugin's public
+ * surface; lets tests (and the T5 gateway projection) read blocked attempts
+ * without reaching into the closure. `undefined` when no plugin is applied.
+ */
+export declare function blockedAttempts(ctx: Context): ReadonlyMap<string, BlockedSwitchAttempt> | undefined;
+/**
+ * @internal Test seam (mirrors `blockedAttempts`): the per-agent effective
+ * chain heads recorded by the T2 inject path (source `authorized` |
+ * `injected`) for the plugin applied to `ctx` (spec D4 / T2 M3). Not part
+ * of the plugin's public surface; lets tests and the T5 gateway projection
+ * read the head without reaching into the closure. `undefined` when no
+ * plugin is applied.
+ */
+export declare function chainHeads(ctx: Context): ReadonlyMap<string, EffectiveChainHead> | undefined;
 /**
  * Count durable `llm/retry` events for the current (turn, step, provider) in
  * **always mode** (ADR-2; spec §2 clause 5). Normal-mode retries belong to