dsh-fallback-router 0.0.0-stage → 0.1.0

package/dist/chains.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Fallback chain resolution (spec §7.2; plan fallbacks-role-runtime Task 1).
+ *
+ * `resolveChain` returns the ordered candidate list for a failing
+ * (provider, model). Candidates come from the role's own chain plus
+ * `rootChain` appended as an inherit-root fallback — **append-not-replace**:
+ * `[...(roleDef.chain ?? []), ...(roleDef.fallback === 'none' ? [] :
+ * rootChain)]` (role entries first, rootChain entries after). The reserved
+ * built-in `inherit` id (INHERIT_ROLE_ID) resolves to `rootChain` silently —
+ * it is the legal no-rule-match role, not a typo'd id. A truly undeclared
+ * role id (defense) resolves to `rootChain` alone + one warn. Chain-key
+ * specificity lookup (`exact` / `provider/*` / role / `default` keys) is
+ * deleted — the two-block config model has no chain keys.
+ *
+ * Wildcard entries (`provider/*`) are resolved against the failing model —
+ * keep the model id, swap only the provider; the "target provider has no
+ * such model id" skip is judged by {@link resolveCandidate} (via
+ * `modelExists`) or by the caller's filter.
+ *
+ * The concatenation itself lives in ONE helper — {@link buildRoleEntries}
+ * (qc1 S-3 SSOT) — shared by {@link resolveChainViews} and
+ * {@link hasWildcardEntry}, so the wildcard probe is exact (qc2 F-003:
+ * `fallback: 'none'` excludes `rootChain`) and can never diverge from the
+ * resolution. Defensive warns (unknown role / undeclared rule target) go
+ * through an injected `warn` callback — the wiring passes the cordis
+ * `logger.warn` (qc2 F-002 / qc3 S-3), with `console.warn` as the
+ * direct-call default.
+ *
+ * Cooldown / failed-set / same-as-current filtering is caller-side;
+ * {@link createCandidateFilter} provides the ready-made predicate. A
+ * `CONTEXT_WINDOW_EXCEEDED` walk adds one more caller-side dimension to the
+ * same predicate — candidates whose disclosed context window is not larger
+ * than the failing model's cannot fit the request either
+ * ({@link fitsContextWindow}; unknown windows keep the candidate).
+ *
+ * @module dsh-fallback-router/chains
+ */
+import { type FallbacksRole } from './config.ts';
+import type { CooldownStore, StepFailureSet } from './cooldown.ts';
+import { type Selector } from './selectors.ts';
+/** The model that just failed — the anchor for chain resolution. */
+export interface FailingModel {
+    provider: string;
+    model: string;
+}
+/**
+ * Resolve one chain entry against the failing model.
+ *
+ * - `provider/model` → that exact selector (not subject to `modelExists` —
+ *   the user explicitly listed it).
+ * - `provider/*` → keeps the failing model id, swaps only the provider; when
+ *   `modelExists` is given and the target provider has no such model id →
+ *   `null` (skip).
+ * - Malformed entries → `null`: they "do not take effect"; the strict throw
+ *   path is {@link parseSelector}, used by the Task 3 config-warning path.
+ */
+export declare function resolveCandidate(entry: string, failing: FailingModel, modelExists?: (provider: string, model: string) => boolean): Selector | null;
+/**
+ * Single-pass chain resolution for the decision path (T1 review Important
+ * #2). Walks the role's concatenated entries ONCE and returns the unfiltered
+ * view — `all` (every resolvable candidate, no filter and no existence
+ * probe: the caller's early-exit / annotation view) — plus the parallel
+ * `wildcard` provenance (`wildcard[i]` = candidate `all[i]` came from a
+ * `provider/*` entry). The caller builds the existence probe from `all` and
+ * then derives the surviving view with {@link selectCandidates}, so the
+ * decision path never resolves the chain twice (and an unknown role warns
+ * at most once per decision).
+ *
+ * The reserved built-in `inherit` id (INHERIT_ROLE_ID) is legal — it
+ * resolves to `rootChain` silently (the no-rule-match role, not a typo'd
+ * id). Only a truly undeclared id (∉ declared ids ∪ {'inherit'}) warns once
+ * (defensive — never crashes) through `warn` (defaults to `console.warn`
+ * for direct-call compatibility; the decision path injects the cordis
+ * `logger.warn` — qc2 F-002 / qc3 S-3). Malformed entries never become
+ * candidates.
+ */
+export declare function resolveChainViews(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string, provider: string, model: string, warn?: (message: string) => void): {
+    all: Selector[];
+    wildcard: boolean[];
+};
+/**
+ * Derive the surviving candidates from a {@link resolveChainViews} pass:
+ * the caller filter plus the wildcard-only existence probe. `modelExists`
+ * applies to `provider/*`-origin candidates only (scoped by the parallel
+ * `wildcard` provenance — T2 review Important #1: exact entries are never
+ * existence-filtered), mirroring how {@link resolveCandidate} receives it.
+ * Order and duplicates are preserved.
+ */
+export declare function selectCandidates(all: readonly Selector[], wildcard: readonly boolean[], filter?: (candidate: Selector) => boolean, modelExists?: (provider: string, model: string) => boolean): Selector[];
+/**
+ * Ordered fallback candidates for the failing (provider, model).
+ *
+ * Candidates are the role's concatenated entries (spec §7.2, see
+ * {@link buildRoleEntries} — the single concatenation SSOT): the declared
+ * role's own `chain` followed by `rootChain` unless `fallback: 'none'`
+ * (append-not-replace — role entries first, rootChain as the tail). The
+ * reserved built-in `inherit` id resolves to `rootChain` silently; a truly
+ * undeclared/unknown `role` id resolves to `rootChain` alone and warns once
+ * (defensive — never crashes). `filter` optionally drops candidates — the
+ * caller owns cooldown/failed-set/same-model filtering (see
+ * {@link createCandidateFilter}). The `modelExists` existence probe is NOT
+ * applied per entry here: {@link resolveChainViews} returns the parallel
+ * `wildcard` provenance, and {@link selectCandidates} applies `modelExists`
+ * to `provider/*`-origin candidates ONLY (qc1 S-2 — exact entries are never
+ * existence-filtered, spec §2 clause 2 / T2 review Important #1
+ * decision-path contract). `warn` forwards to {@link resolveChainViews}
+ * (defaults to `console.warn`; the decision path injects `logger.warn`).
+ *
+ * Single-pass: delegates to {@link resolveChainViews} + {@link selectCandidates}
+ * (one concatenated-entry walk, warn at most once per call).
+ */
+export declare function resolveChain(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string, provider: string, model: string, filter?: (candidate: Selector) => boolean, modelExists?: (provider: string, model: string) => boolean, warn?: (message: string) => void): Selector[];
+/**
+ * Whether any entry of the role's concatenated candidates is a wildcard
+ * (`provider/*`). F-002: {@link resolveChain} resolves wildcard entries to
+ * concrete models, so the wildcard provenance is invisible on the resolved
+ * candidate list — the decision path consults the same concatenation
+ * `resolveChain` walks to decide whether the catalog existence probe is
+ * needed at all.
+ *
+ * The probe walks {@link buildRoleEntries} — the SAME concatenation
+ * {@link resolveChainViews} resolves (qc1 S-3 single SSOT) — so it is
+ * exact, never an over-approximation (qc2 F-003 / qc3 S-1): for
+ * `fallback: 'none'` roles `rootChain` is excluded, and a wildcard that can
+ * never reach the candidate list never builds a catalog probe. No
+ * false-negative is possible: any wildcard the resolution could reach is on
+ * this concatenation by construction. Malformed entries never become
+ * candidates and are skipped.
+ */
+export declare function hasWildcardEntry(roles: readonly FallbacksRole[], rootChain: readonly string[], role: string): boolean;
+/** Inputs for {@link createCandidateFilter}. */
+export interface CandidateFilterOptions {
+    /** The currently active (failing) model — skipped as "same as current". */
+    current: FailingModel;
+    /** Cooldown store: suppressed candidates are skipped (keyed `provider/model`). */
+    cooldown: Pick<CooldownStore, 'isSuppressed'>;
+    /** Failed-set for the current step: already-failed candidates are skipped. */
+    failed: Pick<StepFailureSet, 'has'>;
+    /** Optional existence probe: candidates the target provider lacks are skipped. */
+    modelExists?: (provider: string, model: string) => boolean;
+    /**
+     * The failing model's context window, when known — set only for a
+     * `CONTEXT_WINDOW_EXCEEDED` walk. Candidates whose own known window is not
+     * LARGER than this cannot fit the request either and are skipped.
+     */
+    minContextWindow?: number;
+    /** Context-window lookup for a candidate route; `undefined` = not disclosed. */
+    contextWindowOf?: (provider: string, model: string) => number | undefined;
+}
+/**
+ * The caller-side candidate filter (Task 3): a candidate is usable when it
+ * differs from the current model, is not cooldown-suppressed, has not failed
+ * in this step, can fit the request that overflowed (context-window walks
+ * only — see {@link fitsContextWindow}), and (when `modelExists` is given)
+ * exists on its provider.
+ */
+export declare function createCandidateFilter(options: CandidateFilterOptions): (candidate: Selector) => boolean;
+/**
+ * Why one considered candidate was excluded from the selection (spec §2
+ * 行为可见性). `context-window` is the `CONTEXT_WINDOW_EXCEEDED` walk's
+ * exclusion: the candidate's disclosed window is not larger than the failing
+ * model's, so the request that just overflowed cannot fit there either.
+ */
+export type CandidateSkipReason = 'same-as-current' | 'cooldown' | 'step-failed' | 'context-window' | 'missing-id';
+/** One entry of the ordered, per-candidate annotation (T3 review Minor 1). */
+export interface AnnotatedCandidate {
+    candidate: Selector;
+    /** Why this candidate was excluded; `undefined` = it survived every exclusion. */
+    skip?: CandidateSkipReason;
+}
+/**
+ * Annotate the ordered "considered" candidate list with each candidate's skip
+ * reason (spec §2 行为可见性: the switch log must show the attempt order and
+ * why each candidate was skipped). The selection-relevant view is the
+ * `surviving` list the decision path resolved with filter + existence probe:
+ * a candidate absent from it failed one of the exclusions, and the concrete
+ * reason is derived from the same checks {@link createCandidateFilter}
+ * applies, in the same precedence. `missing-id` therefore only ever labels
+ * entries the existence probe dropped — exact entries are never
+ * existence-probed (T2 contract), so they stay in `surviving` and are
+ * reported as usable, never as missing-id.
+ *
+ * This is the diagnostic counterpart of {@link createCandidateFilter} — pure,
+ * order-preserving, and duplicate-preserving.
+ */
+export declare function annotateCandidates(candidates: readonly Selector[], surviving: readonly Selector[], options: Pick<CandidateFilterOptions, 'current' | 'cooldown' | 'failed' | 'minContextWindow' | 'contextWindowOf'>): AnnotatedCandidate[];

package/dist/client/ConversationFallbackSwitch.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Conversation-level fallback-switch visibility (plan fallbacks-aux-seams,
+ * task 2, D1+D2 seam).
+ *
+ * Every `fallbacks/switch` session event becomes its own chat-transcript
+ * node (`fallbacks-switch`), rendered as a compact system-style line at the
+ * switch's event seq — the user sees the recovery happen in place
+ * (provider/model A → B, role · reason), instead of the event existing only
+ * in the raw `sessions.history` event feed (it is NOT a SurfaceEventType,
+ * so the `unknown-surface` fallback never picked it up and the transcript
+ * showed nothing).
+ *
+ * Contract notes (dsh-private, current homes, verified 2026-08-28):
+ * - D1 registry: `ConversationEventRegistry.register(definition)` — the
+ *   client Context's `uiConversation.events` service seat
+ *   (`ui-conversation conversation/event-registry.ts:17-25`); external
+ *   registration precedent `ui-workflow-run/src/client/index.ts:22-26`
+ *   (its inject list declares `uiConversation` for the same direct read).
+ *   The engine feeds EVERY session event to each definition's `match`
+ *   (`ui-conversation conversation/assembler.ts:406-414`) — non-surface
+ *   plugin events included — and live events reach the engine through the
+ *   assembly window pump (`ui-conversation conversation/assembly.ts:97-105`
+ *   `assembler.append`).
+ * - D2 seat: `conversation.chat.node` is a keyed seat dispatched by
+ *   `ChatConversationViewNode.kind` (`ui-chat contract/slots.ts:171-180`;
+ *   `chat/ChatNodeSeat.tsx:212` renderSlot dispatch), externally registrable
+ *   as `{ name, key, locale }` (precedents: ui-tool `tool-call`
+ *   `apply.ts:28-31`, ui-goal `command-input` `index.ts:60-63`,
+ *   ui-workflow-run `workflow-run`).
+ * - Purity: this file only type-imports `@deepseek-ai/dsh-client-ui-chat/client`
+ *   and `@deepseek-ai/dsh-client-ui-conversation/client` (both erased at
+ *   build); the renderer self-draws on `--dsw-alias-*` tokens. Render-only:
+ *   the Definition is a pure view contribution — no message construction,
+ *   no model-context injection (C4 excluded by scope).
+ */
+import type { ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { FallbackSwitchReason } from '../events.ts';
+/** Final chat payload of one decided fallback switch (snapshot of the event). */
+export interface FallbacksSwitchChatData {
+    readonly seq: number;
+    readonly time: number;
+    readonly turn: number;
+    readonly step: number;
+    /** The model the request was using when the switch was decided. */
+    readonly from: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The chain candidate the switch moves to. */
+    readonly to: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    /** The fallback-chain role the decision resolved for the agent. */
+    readonly role: string;
+    readonly reason: FallbackSwitchReason;
+}
+declare module '@deepseek-ai/dsh-client-ui-chat/client' {
+    interface ChatNodeDataMap {
+        /** One decided fallback provider/model switch, rendered at its event seq. */
+        'fallbacks-switch': FallbacksSwitchChatData;
+    }
+}
+/**
+ * One switch event → one chat node. Each `fallbacks/switch` event is its own
+ * Context (id = event seq — the durable unique key), so every match is a
+ * `start`; `update` is a passthrough (no aggregation — D3's per-Turn
+ * counting is a separate, unselected seam).
+ */
+export declare const fallbackSwitchDefinition: ConversationNodeDefinition<FallbacksSwitchChatData>;
+/**
+ * Props delivered by the keyed chat-node seat: runtime share + the `fallbacks` locale seat.
+ */
+export type ConversationFallbackSwitchProps = PropsRuntime<'conversation.chat.node', 'fallbacks-switch'> & PropsLocale<'fallbacks'>;
+/**
+ * Render one fallback switch as a compact system-style transcript line.
+ *
+ * Geometry follows the upstream chat system rows (the compaction boundary
+ * notice: warning-toned title + separator + ellipsized summary —
+ * `chat/MessageItem .module.css:38-122`); every color resolves through a
+ * `--dsw-alias-*` token. A reason outside the current union renders raw (forward-compatible
+ * durable log, same rule as the card/general row summaries). A malformed or
+ * partial payload (version skew) degrades to the title-only line instead of
+ * throwing during interpolation — the transcript slot stays visible with the
+ * warning-toned "model downgraded" title (T1 copy) and no summary details.
+ * @param props - composed keyed seat props.
+ * @returns the switch line element tree.
+ */
+export declare function ConversationFallbackSwitch({ node, t }: ConversationFallbackSwitchProps): ReactNode;

package/dist/client/FallbacksCard.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `llm-router` plugin card on the web Plugins page.
+ *
+ * SCOPE (deliberate, post-merge): the card renders ONE thing — the 模型配置
+ * panel. The legacy fallbacks surface (the global 默认降级链 editor, the
+ * time-slot table, the subagent role list, the advanced scalars) is not
+ * editable here any more:
+ *
+ *   - `rootChain` / `timeSlots` / `namedChains` are COMPILED from the model
+ *     rows by `withCompiledRouter`, so hand-editing them would be overwritten
+ *     on the next read;
+ *   - `roles` / `cooldownMs` / `revertPolicy` / `presets` / `tz` keep whatever
+ *     the composed config already carries — a save writes only `models` and
+ *     `providers`, so nothing is dropped;
+ *   - provider API keys and other credentials belong to the provider plugins
+ *     (`llm-pi-ai`, …) and are never surfaced (let alone made editable) here.
+ *
+ * The card is a thin shell around {@link ModelsPanel}: it loads the store on
+ * mount, renders the channel/error notices, and hands the panel the write
+ * gate. All authoring logic lives in the panel.
+ */
+import { type ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import { FallbacksSettingsController, type FallbacksSettingsState } from './fallbacks-store.ts';
+/** The card store (loaded on mount, refreshed on pushed invalidations). */
+export interface FallbacksCardInjected {
+    controller: FallbacksSettingsController;
+    /** Bare snapshot source the renderer binds as `useSnapshot`. */
+    hooks: {
+        snapshot: import('@deepseek-ai/dsh-client-store').SnapshotStore<FallbacksSettingsState>;
+    };
+}
+/** Props delivered by the slot outlet: runtime share + locale seat + inject face. */
+export type FallbacksCardProps = PropsRuntime<'plugins.bundle.config'> & PropsLocale<'fallbacks'> & InjectFace<FallbacksCardInjected>;
+export declare function FallbacksCard({ controller, useSnapshot }: FallbacksCardProps): ReactNode;

package/dist/client/GeneralFallbacksRow.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { FallbacksSettingsController, FallbacksSettingsState } from './fallbacks-store.ts';
+/** Injected dependencies of {@link GeneralFallbacksRow} (slot `inject`). */
+export interface GeneralFallbacksRowInjected {
+    /** The shared controller (loaded on first mount, refreshed on pushed invalidations). */
+    controller: FallbacksSettingsController;
+    /** uSES subscription hook bound to the store (inject face — advisor pattern). */
+    useSnapshot: SnapshotSelectorHook<FallbacksSettingsState>;
+}
+/** Props delivered by the slot outlet: runtime share + locale seat + inject face. */
+export type GeneralFallbacksRowProps = PropsRuntime<'settings.general.item'> & PropsLocale<'fallbacks'> & GeneralFallbacksRowInjected;
+/**
+ * Render the Fallbacks status row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function GeneralFallbacksRow({ controller, useSnapshot, t }: GeneralFallbacksRowProps): ReactNode;

package/dist/client/ModelsPanel.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 模型配置 (model profiles) panel — the ONLY authoring surface of
+ * dsh-fallback-router.
+ *
+ * Every row is a MODEL CONFIGURATION. Two shapes exist:
+ *
+ * - 单一模型 (`kind: 'route'`) — a `provider/model` route with its own time
+ *   windows (时间区间, either a frozen preset like 梁高峰/梁低谷 or a
+ *   hand-written window), its own fallback policy (官方兜底 / 循环兜底 /
+ *   不兜底), the extra hops it may try (追加兜底路由) and its own failure
+ *   rules (错误码 + 正则 + 结构判定).
+ * - 自由组合 (`kind: 'combo'`) — no route of its own; every 时间区间 names an
+ *   existing configuration (`使用配置`), so 梁高峰 can run config A while
+ *   梁低谷 runs config B without duplicating either one's settings.
+ *
+ * Every provider/model field is a dropdown fed by the host catalog
+ * (`llm/listConfigurableProviders` + `session/modelCatalog`); a value the
+ * catalog does not know is kept as an extra option so a hand-written route is
+ * never silently replaced, and an empty catalog degrades to a text input.
+ *
+ * The host compiles this list down to `rootChain` / `timeSlots` /
+ * `namedChains` (`withCompiledRouter`), so the chain-walking engine keeps
+ * working unchanged.
+ *
+ * The panel owns its own draft and its own Save: it writes ONLY `models` and
+ * `providers`. Everything the legacy card used to expose (the global chain,
+ * the time-slot table, the subagent roles, the advanced scalars) is
+ * deliberately NOT editable here — it is either compiled from these rows or
+ * left at whatever the config already carries.
+ *
+ * @module dsh-fallback-router/client/ModelsPanel
+ */
+import { type ReactNode } from 'react';
+import type { FallbacksConfig } from '../config.ts';
+/** One model the host can dispatch to, as a dropdown shows it. */
+export interface ModelsCatalogModel {
+    id: string;
+    name: string;
+    /** 推理等级 the model advertises (empty when it has none). */
+    efforts?: {
+        id: string;
+        name: string;
+    }[];
+    /** The level the model picks when the request names none. */
+    defaultEffort?: string;
+}
+/** One provider and its models, as the dropdowns show them. */
+export interface ModelsCatalogProvider {
+    id: string;
+    name: string;
+    models: ModelsCatalogModel[];
+}
+/** The dropdown source, as the card passes it in. */
+export type ModelsCatalog = readonly ModelsCatalogProvider[];
+/** Props: the live config, the catalog behind the dropdowns, and the write path. */
+export interface ModelsPanelProps {
+    config: FallbacksConfig;
+    writable: boolean;
+    saving: boolean;
+    onSave: (next: FallbacksConfig) => void;
+    /** Provider/model catalog for the dropdowns; omit to fall back to text inputs. */
+    catalog?: ModelsCatalog;
+}
+export declare function ModelsPanel({ config, writable, saving, onSave, catalog }: ModelsPanelProps): ReactNode;

package/dist/client/SubagentRoleBadge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session-header subagent role/model badge (plan subagent-role-badge T3 +
+ * plan subagent-role-model): a compact read-only pill in
+ * `conversation.session.header.actions` showing the viewed CHILD session's
+ * dispatch role and the model route it runs on, hovering as
+ * `role → provider/model (request route)`.
+ *
+ * Contract notes (re-verified 2026-10-23 against the installed dsh 0.2.1-rc.2):
+ * - The slot is `kind: 'list'`, `scope: 'session'`, owner props an empty marker
+ *   (`ConversationHeaderActionOwnerProps`, `children?: never`) — the header
+ *   renders occupants with `renderSlot(..., {})`, so ALL data flows through the
+ *   session standard kit.
+ * - Every `scope: 'session'` occupant receives the session standard kit, whose
+ *   members this component uses are `sessionId`, `useSessions` (the shared
+ *   Session store) and `useProjection` (the viewed session's projection cut).
+ *   The compiled peer types do not carry that merge into this plugin's
+ *   typecheck program (ui-session is deliberately not a plugin peer), so the
+ *   seats are read STRUCTURALLY and guarded — a version-skewed host without them
+ *   renders nothing, never throws.
+ * - The badge belongs to a CHILD session: `byId[sessionId].origin === 'subagent'`
+ *   is the host's own child-session idiom (`dsh-client-ui-subagent`
+ *   `SubagentCatalogAction`). Root rows omit `origin`, so a root session renders
+ *   nothing even though its own `modelSelection` carries a route — the composer
+ *   owns that control.
+ * - Role data: the host's `fallbacksSubagentRole` projection (Task 3b), folded
+ *   server-side out of the child's own durable log — the ONE role source. The
+ *   session kit binds the hook to the VIEWED session, so no `sessionId`
+ *   plumbing, no effect, no state, and no polling. An absent key (host without
+ *   the unit, or no notice row) omits the role half; `inherit` omits it too.
+ * - Route data: the host's EXISTING `modelSelection` projection, read as
+ *   `next ?? lastUsed` — the route the child's next request will use, falling
+ *   back to the one its latest recorded request ran on. The two halves are
+ *   INDEPENDENT: either alone still renders, and both missing renders nothing.
+ * - Hook order is render-independent (Task 3b L2 review C-1): the seats are real
+ *   hooks, so the three reads are unconditional and only their derived values
+ *   are guarded — a conditional read would change the hook count on the very
+ *   re-render that publishes a running child's role.
+ * - Render-only discipline (C4 pattern, same as `ConversationFallbackSwitch`):
+ *   the badge contributes a view; no message construction, no model-context
+ *   injection. Degrade-never-crash: a missing/foreign projection value renders
+ *   `null` — the actions row collapses cleanly.
+ */
+import type { ReactNode } from 'react';
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** Props delivered by the actions slot outlet: runtime share + locale seat. */
+export type SubagentRoleBadgeProps = PropsRuntime<'conversation.session.header.actions'> & PropsLocale<'fallbacks'>;
+/**
+ * Render the viewed SUBAGENT session's role and model.
+ * @param props - composed slot props (the session-kit `useProjection` /
+ *   `useSessions` seats are read structurally — see the module docblock).
+ * @returns the badge element, or `null` when there is nothing to show.
+ */
+export declare function SubagentRoleBadge(props: SubagentRoleBadgeProps): ReactNode;