dsh-llm-fallbacks 0.4.2 → 0.4.3

package/dist/client/locales.d.ts

@@ -111,9 +111,11 @@ export declare const zh: {
     'roles.idPlaceholder': string;
     'roles.persona': string;
     'roles.personaPlaceholder': string;
-    'roles.seedDefault': string;
-    'roles.seedOverride': string;
-    'roles.revertPersona': string;
+    'roles.persona.expand': string;
+    'roles.persona.collapse': string;
+    'roles.persona.empty': string;
+    'roles.seedSource.bundled': string;
+    'roles.seedSource.user': string;
     'roles.seedChainOptional': string;
     'roles.fallback': string;
     'roles.fallback.inherit-root': string;
@@ -182,6 +184,7 @@ export declare const zh: {
     'chat.switch.summary': string;
     'chat.switch.summary.roleInject': string;
     'chat.switch.roleMap': string;
+    'subagentRole.hover': string;
     'defaults.prefix': string;
     save: string;
     'save.saving': string;
@@ -305,9 +308,11 @@ export declare const en: {
     'roles.idPlaceholder': string;
     'roles.persona': string;
     'roles.personaPlaceholder': string;
-    'roles.seedDefault': string;
-    'roles.seedOverride': string;
-    'roles.revertPersona': string;
+    'roles.persona.expand': string;
+    'roles.persona.collapse': string;
+    'roles.persona.empty': string;
+    'roles.seedSource.bundled': string;
+    'roles.seedSource.user': string;
     'roles.seedChainOptional': string;
     'roles.fallback': string;
     'roles.fallback.inherit-root': string;
@@ -376,6 +381,7 @@ export declare const en: {
     'chat.switch.summary': string;
     'chat.switch.summary.roleInject': string;
     'chat.switch.roleMap': string;
+    'subagentRole.hover': string;
     'defaults.prefix': string;
     save: string;
     'save.saving': string;

package/dist/config.d.ts

@@ -91,7 +91,7 @@ export interface FallbacksConfig {
     maxSwitchesPerStep: number;
     alwaysModeRetryCap: number;
     /**
-     * Preset-role injection switch: `'bundled'` declares the 7 preset roles
+     * Preset-role injection switch: `'bundled'` declares the 5 preset roles
      * (spec §9.2) as seed rows on apply; `'none'` disables declaration.
      * Optional on purpose — a required field would break library consumers
      * that construct `FallbacksConfig` literals with the existing 8 keys

package/dist/gateway.d.ts

@@ -2,7 +2,7 @@
  * T1 (plan llm-fallbacks-settings-gateway) + T3 (plan fallbacks-role-seeds) —
  * host-side `fallbacks` config gateway: the `/api/fallbacks/get` +
  * `/api/fallbacks/set` + `/api/fallbacks/reset` + `/api/fallbacks/revert-seed`
- * endpoints.
+ * + `/api/fallbacks/subagent-roles` endpoints.
  *
  * Transport: the typertGateway `/api` interceptor is the single host-wide RPC
  * slot (a plugin must NOT `connection.rpc.intercept('/api')` again — it would
@@ -43,6 +43,11 @@
  * `revert-seed` exposes revert-to-current-seed-default for one id — both
  * delegate to the per-apply `FallbacksSeedManager` passed into the
  * constructor (single point of truth, no copied manager logic).
+ * `subagent-roles` (plan subagent-role-badge T2) is the read-only badge
+ * readback: it projects the per-apply dispatch-resolved role-record map
+ * (same T1 map the inject block writes, via the optional snapshot fn) for a
+ * batch of session ids — unknown ids are omitted, an unwired or throwing
+ * snapshot degrades to `{}`, never an error.
  *
  * The settings service is OPTIONAL (no settings service → the bridge source
  * stays the entry, `get` still works; `set`/`reset` fail with a clear
@@ -126,6 +131,29 @@ export type SubagentPolicySnapshotFn = () => {
         reason: string;
     };
 };
+/**
+ * One dispatch-resolved subagent role record on the wire (plan
+ * subagent-role-badge T2): the role the subagent's dispatch resolved and the
+ * route it actually runs after the inject decision. `model` is optional on
+ * the WIRE type only — the writer (T1) always sets it, but a record without
+ * one still reads back as `{ role, at }` instead of failing the readback.
+ */
+export type SubagentRoleRecord = {
+    role: string;
+    model?: {
+        provider: string;
+        model: string;
+    };
+    at: number;
+};
+/**
+ * Live role-record snapshot the gateway reads through (plan
+ * subagent-role-badge T2) — the `SubagentPolicySnapshotFn` pattern: built in
+ * `apply()` over the SAME T1 map the dispatch inject block writes, no second
+ * record source. Optional: constructors that omit it make the
+ * `/api/fallbacks/subagent-roles` endpoint return `{}`.
+ */
+export type SubagentRolesSnapshotFn = () => ReadonlyMap<string, SubagentRoleRecord>;
 /**
  * The live configuration source for the gateway (guide §7 — the same bridge
  * shape the runtime reads through). `source()` returns the live composed
@@ -184,6 +212,12 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      * used by gateway unit tests stays byte-identical to the pre-T5 payload.
      */
     private readonly subagentPolicy;
+    /**
+     * Optional role-record snapshot (plan subagent-role-badge T2). When omitted
+     * the `subagentRoles` endpoint returns `{}` — every existing constructor
+     * call site keeps its payload byte-identical.
+     */
+    private readonly subagentRolesSnapshot;
     /**
      * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
      * @param bridge - the same `FallbacksSettingsBridge` the runtime reads, so
@@ -193,8 +227,11 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   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.
+     * @param subagentRoles - live dispatch-resolved role-record snapshot from
+     *   `apply()` (plan subagent-role-badge T2); omit to make the
+     *   `subagent-roles` endpoint return `{}`.
      */
-    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager, subagentPolicy?: SubagentPolicySnapshotFn);
+    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager, subagentPolicy?: SubagentPolicySnapshotFn, subagentRoles?: SubagentRolesSnapshotFn);
     /**
      * Read the current composed config (schema defaults → entry base → settings
      * user layer). No hard-gate resolver (ADR-2): the raw composed config is
@@ -253,6 +290,22 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   write channel is unavailable (KD-G5).
      */
     revertSeed(id: string): Promise<FallbacksRevertResult>;
+    /**
+     * Batch readback of dispatch-resolved subagent role records (plan
+     * subagent-role-badge T2) — the read side of the session-header role badge.
+     * Ids are agent ids (≡ session ids: the same id space the dispatch inject
+     * block records under). Unknown/absent ids are OMITTED from the result,
+     * never an error — the badge renders nothing for them. No snapshot wired
+     * (pre-T2 constructors) or a throwing snapshot ⇒ `{}` — degrade-never-crash,
+     * the same fail-closed shape as `projectSubagentPolicy`.
+     * @param ids - the session ids to read (at most
+     *   {@link SUBAGENT_ROLES_MAX_IDS} entries).
+     * @returns a plain JSON object keyed by KNOWN id only, each carrying the
+     *   wire record (`role`, `at`, `model` when the record has one).
+     * @throws TypeError when `ids` is not an array of strings or the batch
+     *   exceeds {@link SUBAGENT_ROLES_MAX_IDS} entries.
+     */
+    subagentRoles(ids: string[]): Record<string, SubagentRoleRecord>;
     /**
      * Read the live composed config and normalize it to the typertGateway JSON
      * wire boundary. Containment (guide §10): a malformed stored user layer

package/dist/index.d.ts

@@ -38,7 +38,7 @@ import { Config } from './schema.ts';
 import { resolveChain } from './chains.ts';
 import { resolveRole } from './roles.ts';
 import { FallbackStateStore, type BlockedSwitchAttempt, type EffectiveChainHead } from './state.ts';
-import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome } from './seeds.ts';
+import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome, type SeedsDeclareOptions } from './seeds.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
 /**
@@ -66,8 +66,14 @@ export interface FallbacksService {
     resolveChain: typeof resolveChain;
     validateFallbacksConfig: typeof validateFallbacksConfig;
     detectLegacyKeys: typeof detectLegacyKeys;
-    /** (a) Declare the companion's FULL current seed set (replacement semantics, spec §9.1). */
-    declareSeeds(seeds: readonly SeedDeclaration[]): Promise<SeedDeclareOutcome>;
+    /**
+     * (a) Declare the companion's FULL current seed set (replacement semantics,
+     * spec §9.1). The optional `options.set` records the batch's registered
+     * provenance set name (read back as the rows' `source`); there is
+     * deliberately no way to label a declare `bundled` — reserved for the
+     * plugin's own preset self-declare.
+     */
+    declareSeeds(seeds: readonly SeedDeclaration[], options?: SeedsDeclareOptions): Promise<SeedDeclareOutcome>;
     /** (b) Sync readback — effective taxonomy with seed annotations. */
     getEffectiveRoles(): EffectiveRolesReadback;
     /** (c) Revert one id to the CURRENT declared seed default. */
@@ -83,14 +89,14 @@ 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, BlockedSwitchAttempt, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+export type { AgentFallbackState, BlockedSwitchAttempt, FallbackStateStore, PendingSwitch, StepFailures, SwitchScope } 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, 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 { FallbacksSeedManager, type EffectiveRole, type EffectiveRolesReadback, type SeedConflict, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertFailReason, type SeedRevertOutcome, type SeedSkipReason, type SeedSource, type SeedsDeclareOptions, type SeedsIo, type SeedsWireStatus, } from './seeds.ts';
 export { presetRoles } from './presets.ts';
 /**
  * @internal Test seam (T3 review Minor 3): the per-agent fallback state store
@@ -116,6 +122,29 @@ export declare function blockedAttempts(ctx: Context): ReadonlyMap<string, Block
  * plugin is applied.
  */
 export declare function chainHeads(ctx: Context): ReadonlyMap<string, EffectiveChainHead> | undefined;
+/**
+ * One dispatch-resolved subagent role record (plan subagent-role-badge T1):
+ * the role `resolveRoleAtDispatch` resolved at the subagent's first request
+ * and the route the subagent will actually run after the inject decision
+ * (the override target when it applies, else the host seed).
+ */
+type SubagentRoleRecord = {
+    role: string;
+    model: {
+        provider: string;
+        model: string;
+    };
+    at: number;
+};
+/**
+ * @internal Test seam (mirrors `chainHeads`): the per-agent dispatch-resolved
+ * role records written by the role-inject block (plan subagent-role-badge T1)
+ * for the plugin applied to `ctx`. Not part of the plugin's public surface;
+ * lets tests read the badge record without reaching into the closure (the
+ * gateway readback closes over the per-apply map directly). `undefined` when
+ * no plugin is applied.
+ */
+export declare function subagentRoleRecords(ctx: Context): ReadonlyMap<string, SubagentRoleRecord> | 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