@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/permissions/types.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Core types for the layered permission evaluator.
+ *
+ * These types represent the full evaluation model: modes, decisions, reason
+ * codes, classification, policy rules, and per-step evaluation trace.
+ */
+/**
+ * The active permission mode controlling how the evaluator applies its layers.
+ *
+ * - `default`              — Standard prompt mode; reads auto-approved.
+ * - `plan`                 — Planning mode; write/execute/network blocked.
+ * - `allow-all`            — All tools auto-approved (⚠ use with caution).
+ * - `custom`               — Per-rule policy applies exclusively.
+ * - `background-restricted`— Agent/delegate tools blocked; exec restricted.
+ * - `remote-restricted`    — Network tools blocked; local reads/writes allowed.
+ */
+export type PermissionMode = 'default' | 'plan' | 'allow-all' | 'custom' | 'background-restricted' | 'remote-restricted';
+/**
+ * Semantic classification of a tool call, derived from tool name and args.
+ *
+ * Used by safety checks, mode constraints, and policy rules to reason about
+ * what a tool call actually does.
+ */
+export type CommandClassification = 'read' | 'write' | 'network' | 'destructive' | 'escalation';
+/**
+ * Canonical reason codes emitted with every PermissionDecision.
+ *
+ * Prefix conventions:
+ *   RULE_   — a policy rule matched (allow or deny)
+ *   PROMPT_ — user was prompted and responded
+ *   SAFETY_ — bypass-immune safety guardrail fired
+ *   MODE_   — active permission mode determined the outcome
+ *   DEFAULT_— fallback default policy
+ */
+export type DecisionReason = 'RULE_ALLOW_USER' | 'RULE_ALLOW_MANAGED' | 'RULE_DENY_MANAGED' | 'RULE_DENY_USER' | 'PROMPT_ALLOW_ONCE' | 'PROMPT_ALLOW_SESSION' | 'PROMPT_DENY' | 'SESSION_CACHED_ALLOW' | 'SESSION_CACHED_DENY' | 'SAFETY_DENY_DESTRUCTIVE_PREFIX' | 'SAFETY_DENY_PATH_ESCAPE' | 'SAFETY_DENY_DANGEROUS_PATTERN' | 'SAFETY_DENY_DANGEROUS_SQL' | 'SAFETY_DENY_GUARDRAIL' | 'MODE_ALLOW_ALL' | 'MODE_DENY_PLAN' | 'MODE_DENY_BACKGROUND' | 'MODE_DENY_REMOTE_RESTRICTED' | 'DEFAULT_ALLOW' | 'DEFAULT_DENY';
+/**
+ * Which layer in the evaluation stack produced the final decision.
+ * Layers are evaluated in priority order; first match wins.
+ */
+export type SourceLayer = 'safety' | 'mode' | 'session' | 'policy' | 'default';
+/** A single step recorded during evaluation for audit and debugging. */
+export interface EvaluationStep {
+    /** Evaluation layer where this step occurred. */
+    layer: SourceLayer;
+    /** Human-readable description of what was checked. */
+    check: string;
+    /** Whether this step produced a match (true = this step resolved the decision). */
+    matched: boolean;
+    /** Optional additional context (rule id, pattern, path matched, etc.). */
+    detail?: string;
+}
+/**
+ * The result of a single permission evaluation. Returned by LayeredPolicyEvaluator.
+ *
+ * Contains the final allow/deny outcome, the reason code, the source layer,
+ * the semantic classification of the tool call, and a full evaluation trace
+ * for audit logging and debugging.
+ *
+ * When the evaluator was configured from a signed policy bundle, the
+ * provenance fields `policyBundleId`, `signatureStatus`, and
+ * `provenanceSource` are populated from `BundleProvenance` for audit
+ * trail and UI display (GC-PERM-011).
+ */
+export interface PermissionDecision {
+    /** Whether the tool call is permitted. */
+    allowed: boolean;
+    /** Primary reason code for the decision. */
+    reason: DecisionReason;
+    /** Which layer in the evaluation stack produced this decision. */
+    sourceLayer: SourceLayer;
+    /** The tool being evaluated. */
+    toolName: string;
+    /** Arguments passed to the tool. */
+    args: Record<string, unknown>;
+    /** Semantic classification of this tool call (set by the evaluator). */
+    classification?: CommandClassification;
+    /** Unix epoch milliseconds when the decision was produced. */
+    timestamp: number;
+    /** Full ordered trace of evaluation steps that led to this decision. */
+    evaluationTrace: EvaluationStep[];
+    /**
+     * Opaque identifier of the policy bundle that provided the rules used
+     * for this evaluation. Undefined when no bundle was loaded.
+     */
+    policyBundleId?: string;
+    /**
+     * Signature validation status of the bundle at load time.
+     * Undefined when no bundle was loaded or when the feature flag is disabled.
+     */
+    signatureStatus?: import('./policy-signer.js').SignatureStatus;
+    /**
+     * Where the policy bundle originated from.
+     * Undefined when no bundle was loaded.
+     */
+    provenanceSource?: import('./policy-signer.js').ProvenanceSource;
+}
+/**
+ * Controls how the permission simulator behaves during evaluation.
+ *
+ * - `simulation-only`     — Both evaluators run; only the actual decision is
+ *                           enforced. Divergence is logged silently.
+ * - `warn-on-divergence`  — Both evaluators run; actual enforced. Divergence
+ *                           emits a warning to the decision log.
+ * - `enforce`             — The simulated evaluator becomes the authoritative
+ *                           evaluator. Blocked if the divergence gate fails.
+ */
+export type SimulationMode = 'simulation-only' | 'warn-on-divergence' | 'enforce';
+/**
+ * Categorises how two decisions diverged from one another.
+ *
+ * - `allow-vs-deny`  — Actual allowed; simulated denied.
+ * - `deny-vs-allow`  — Actual denied; simulated allowed.
+ * - `reason-mismatch`— Both produced the same allow/deny but with different
+ *                      reason codes or source layers.
+ */
+export type DivergenceType = 'allow-vs-deny' | 'deny-vs-allow' | 'reason-mismatch';
+/**
+ * The result of a single simulation evaluation — pairing the actual decision
+ * with the simulated decision and describing any observed divergence.
+ */
+export interface SimulationResult {
+    /** Decision produced by the actual (authoritative) evaluator. */
+    actualDecision: PermissionDecision;
+    /** Decision produced by the simulated (candidate) evaluator. */
+    simulatedDecision: PermissionDecision;
+    /**
+     * The decision that should be enforced by the caller.
+     *
+     * - `simulation-only` and `warn-on-divergence` — equals `actualDecision`.
+     * - `enforce` — equals `simulatedDecision` (simulated becomes authoritative).
+     */
+    authoritativeDecision: PermissionDecision;
+    /** Whether the two decisions diverged in any way. */
+    diverged: boolean;
+    /** How the decisions diverged; only set when `diverged` is `true`. */
+    divergenceType?: DivergenceType;
+}
+/**
+ * A single divergence observation recorded for aggregation.
+ *
+ * Stored by `PermissionSimulator` and surfaced via `getDivergenceReport()`.
+ */
+export interface DivergenceRecord {
+    /** Unix epoch milliseconds when the divergence was recorded. */
+    timestamp: number;
+    /** Tool name at the time of divergence. */
+    toolName: string;
+    /** Semantic classification of the tool call. */
+    toolClass: CommandClassification;
+    /** First token of the command/path/url argument, if present. */
+    commandPrefix: string | undefined;
+    /** Active simulation mode at the time of divergence. */
+    mode: SimulationMode;
+    /** How the two decisions diverged. */
+    divergenceType: DivergenceType;
+    /** Reason from the actual decision. */
+    actualReason: DecisionReason;
+    /** Reason from the simulated decision. */
+    simulatedReason: DecisionReason;
+}
+/**
+ * Aggregated statistics for a group of divergence records.
+ */
+export interface DivergenceStats {
+    /** Total number of divergences observed. */
+    total: number;
+    /** Breakdown by divergence type. */
+    byType: Record<DivergenceType, number>;
+    /** Rate: divergences / total evaluations (0–1). */
+    divergenceRate: number;
+    /** Total evaluations against which this rate is computed. */
+    totalEvaluations: number;
+}
+/**
+ * Full report returned by `PermissionSimulator.getDivergenceReport()`.
+ *
+ * Aggregated statistics broken down by tool class and command prefix.
+ */
+export interface DivergenceReport {
+    /** Aggregate statistics across all evaluations. */
+    overall: DivergenceStats;
+    /** Per-tool-class breakdown (keyed by CommandClassification). */
+    byToolClass: Partial<Record<CommandClassification, DivergenceStats>>;
+    /** Per-command-prefix breakdown (keyed by prefix string). */
+    byCommandPrefix: Record<string, DivergenceStats>;
+    /** Per-mode breakdown (keyed by SimulationMode). */
+    byMode: Partial<Record<SimulationMode, DivergenceStats>>;
+    /** Raw divergence records (capped at internal limit). */
+    records: DivergenceRecord[];
+}
+/**
+ * Configuration for `PermissionSimulator`.
+ */
+export interface PermissionSimulatorConfig {
+    /**
+     * Maximum number of divergence records to retain in memory.
+     * Oldest records are evicted when the limit is reached. Defaults to 500.
+     */
+    maxDivergenceRecords?: number;
+    /**
+     * Maximum divergence rate (0–1) allowed before enforcement mode is blocked.
+     * Only relevant when `mode` is `'enforce'`.
+     * Defaults to 0.05 (5%).
+     */
+    divergenceThreshold?: number;
+    /**
+     * Optional callback invoked when a divergence is detected in `warn-on-divergence` mode.
+     *
+     * Receives the full `DivergenceRecord` for the diverging evaluation.
+     * If omitted, warnings are written to `process.stderr` as a fallback.
+     */
+    onWarning?: (record: DivergenceRecord) => void;
+}
+/**
+ * Who authored this rule — affects precedence within the policy layer.
+ * User rules take precedence over managed (system/plugin) rules.
+ */
+export type RuleOrigin = 'user' | 'managed';
+/** Shared metadata present on every policy rule type. */
+interface BaseRule {
+    /** Unique rule identifier (used in trace output and logs). */
+    id: string;
+    /** Human-readable description of what this rule does. */
+    description?: string;
+    /** Who authored this rule. */
+    origin: RuleOrigin;
+    /** Whether the rule grants (allow) or blocks (deny) matching calls. */
+    effect: 'allow' | 'deny';
+}
+/**
+ * PrefixRule — matches tool names and/or command prefixes.
+ *
+ * Example: deny any exec call whose first argument starts with `rm -rf`.
+ */
+export interface PrefixRule extends BaseRule {
+    type: 'prefix';
+    /** Tool name(s) this rule applies to. Use `'*'` for any tool. */
+    toolPattern: string | string[];
+    /**
+     * Prefix pattern(s) matched against the first string argument of the call.
+     * If omitted, the rule matches any call to the specified tool(s).
+     */
+    commandPrefixes?: string[];
+}
+/**
+ * ArgShapeRule — matches against argument shape/content via predicate.
+ *
+ * Example: deny calls where args contain `{ force: true }` combined with a
+ * destructive tool name.
+ */
+export interface ArgShapeRule extends BaseRule {
+    type: 'arg-shape';
+    /** Tool name(s) this rule applies to. Use `'*'` for any tool. */
+    toolPattern: string | string[];
+    /**
+     * Key/value pairs that must ALL be present in `args` for the rule to match.
+     * Values may be the literal expected value or a regex string (prefixed `/`).
+     */
+    argMatchers: Record<string, unknown>;
+}
+/**
+ * PathScopeRule — restricts or allows tool calls based on file path arguments.
+ *
+ * Example: deny any write tool call whose `path` arg escapes the project root.
+ */
+export interface PathScopeRule extends BaseRule {
+    type: 'path-scope';
+    /** Tool name(s) this rule applies to. Use `'*'` for any tool. */
+    toolPattern: string | string[];
+    /**
+     * Allowed or denied path prefixes. Relative paths are resolved against cwd.
+     * Supports glob-style `**` wildcards via micromatch semantics.
+     */
+    pathPatterns: string[];
+}
+/**
+ * NetworkScopeRule — restricts or allows tool calls based on network host/URL.
+ *
+ * Example: deny any fetch call to hosts not in the allowed list.
+ */
+export interface NetworkScopeRule extends BaseRule {
+    type: 'network-scope';
+    /** Tool name(s) this rule applies to. Use `'*'` for any tool. */
+    toolPattern: string | string[];
+    /**
+     * Allowed or denied hostnames/IP patterns. Supports glob wildcards.
+     * Example: `['*.anthropic.com', 'localhost']`.
+     */
+    hostPatterns: string[];
+    /**
+     * Optional port restriction. If set, only the specified ports are matched.
+     * Use `0` to match any port.
+     */
+    ports?: number[];
+}
+/**
+ * ModeConstraintRule — activates only when a specific PermissionMode is active.
+ *
+ * Example: deny all write tools when mode is `'plan'`.
+ */
+export interface ModeConstraintRule extends BaseRule {
+    type: 'mode-constraint';
+    /** Mode(s) in which this rule is active. */
+    activeModes: PermissionMode[];
+    /** Tool name(s) or classifications this rule applies to. */
+    toolPattern: string | string[];
+    /** Optional: restrict by command classification instead of tool name. */
+    classifications?: CommandClassification[];
+}
+/** Discriminated union of all policy rule types. */
+export type PolicyRule = PrefixRule | ArgShapeRule | PathScopeRule | NetworkScopeRule | ModeConstraintRule;
+/** Configuration object passed to `createPermissionEvaluator()`. */
+export interface PermissionsConfig {
+    /** Active permission mode. Defaults to `'default'`. */
+    mode?: PermissionMode;
+    /** Explicit project root used to resolve relative path-scope rules and tool args. */
+    projectRoot?: string;
+    /**
+     * Ordered list of policy rules applied in Layer 4.
+     * User rules are evaluated before managed rules within this layer.
+     */
+    rules?: PolicyRule[];
+    /**
+     * Default decision when no rule or safety check fires.
+     * Defaults to `'allow'` for read tools, `'deny'` for everything else.
+     */
+    defaultEffect?: 'allow' | 'deny';
+    /** Whether to emit structured audit log entries for every decision. Defaults to true. */
+    auditLog?: boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/runtime/permissions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/types.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/runtime/permissions/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core types for the layered permission evaluator.
+ *
+ * These types represent the full evaluation model: modes, decisions, reason
+ * codes, classification, policy rules, and per-step evaluation trace.
+ */
+export {};

package/dist/_internal/platform/runtime/provider-health/data-provider.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ProviderHealthDataProvider — enriched provider health data surface.
+ *
+ * Combines ProviderHealthDomainState and ModelDomainState into a single,
+ * sorted ProviderHealthData snapshot for UI consumption.
+ *
+ * This class is a data provider only — it contains no rendering logic.
+ * Subscribe to change notifications and call getSnapshot() to render.
+ */
+import type { ProviderHealthDomainState } from '../store/domains/provider-health.js';
+import type { ModelDomainState } from '../store/domains/model.js';
+import type { ProviderHealthData } from './types.js';
+/**
+ * ProviderHealthDataProvider produces enriched provider health data snapshots.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new ProviderHealthDataProvider(healthState, modelState);
+ * const unsub = provider.subscribe(() => {
+ *   const data = provider.getSnapshot();
+ *   // render data.entries, data.fallbackChain, etc.
+ * });
+ * // When state changes:
+ * provider.updateHealthState(newHealthState);
+ * provider.updateModelState(newModelState);
+ * // Cleanup:
+ * unsub();
+ * provider.dispose();
+ * ```
+ */
+export declare class ProviderHealthDataProvider {
+    private _healthState;
+    private _modelState;
+    private _snapshot;
+    private readonly _subscribers;
+    /** Per-provider timeline buffers, keyed by providerId. */
+    private readonly _timelines;
+    constructor(healthState: ProviderHealthDomainState, modelState: ModelDomainState);
+    /**
+     * Return the current enriched provider health data snapshot.
+     * Updated synchronously when state changes via update methods.
+     */
+    getSnapshot(): ProviderHealthData;
+    /**
+     * Register a callback invoked whenever the snapshot changes.
+     * @returns An unsubscribe function.
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Update provider health state and rebuild the snapshot.
+     * Appends a new timeline point for each provider.
+     */
+    updateHealthState(healthState: ProviderHealthDomainState): void;
+    /**
+     * Update model domain state (e.g. active model or fallback chain change).
+     * Triggers a snapshot rebuild.
+     */
+    updateModelState(modelState: ModelDomainState): void;
+    /**
+     * Release all subscriber references.
+     * Does not clear internal state — getSnapshot() remains usable after disposal.
+     */
+    dispose(): void;
+    /**
+     * Seed timeline buffers from the initial health state.
+     * Appends one point per known provider to initialize the timeline.
+     */
+    private _seedTimelines;
+    /**
+     * Append a new timeline point for every provider in the updated state.
+     * Creates a new buffer for providers seen for the first time.
+     */
+    private _appendTimelinePoints;
+    /** Append a single timeline point to a buffer, capping at TIMELINE_MAX_POINTS. */
+    private _appendPoint;
+    /** Build a HealthTimeline from a buffer for a given provider. */
+    private _buildTimeline;
+    private _rebuild;
+    private _buildSnapshot;
+    private _notify;
+}
+//# sourceMappingURL=data-provider.d.ts.map

package/dist/_internal/platform/runtime/provider-health/data-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-provider.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/provider-health/data-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,yBAAyB,EAAwB,MAAM,qCAAqC,CAAC;AAC3G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAyBpB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAEpD,WAAW,EAAE,yBAAyB,EAAE,UAAU,EAAE,gBAAgB;IAOhF;;;OAGG;IACI,WAAW,IAAI,kBAAkB;IAIxC;;;OAGG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKlD;;;OAGG;IACI,iBAAiB,CAAC,WAAW,EAAE,yBAAyB,GAAG,IAAI;IAMtE;;;OAGG;IACI,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAK3D;;;OAGG;IACI,OAAO,IAAI,IAAI;IAMtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAQtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAS7B,kFAAkF;IAClF,OAAO,CAAC,YAAY;IAmBpB,iEAAiE;IACjE,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,cAAc;IAoDtB,OAAO,CAAC,OAAO;CAShB"}

package/dist/_internal/platform/runtime/provider-health/data-provider.js

@@ -0,0 +1,197 @@
+import { buildFallbackChainData } from './fallback-visualizer.js';
+/**
+ * Number of timeline points retained per provider.
+ * Each point represents a snapshot at the time of a state update.
+ */
+const TIMELINE_MAX_POINTS = 60;
+/** Status sort priority (lower = shown first in list). */
+const STATUS_ORDER = {
+    degraded: 0,
+    rate_limited: 1,
+    auth_error: 2,
+    unavailable: 3,
+    unknown: 4,
+    healthy: 5,
+};
+/**
+ * ProviderHealthDataProvider produces enriched provider health data snapshots.
+ *
+ * Usage:
+ * ```ts
+ * const provider = new ProviderHealthDataProvider(healthState, modelState);
+ * const unsub = provider.subscribe(() => {
+ *   const data = provider.getSnapshot();
+ *   // render data.entries, data.fallbackChain, etc.
+ * });
+ * // When state changes:
+ * provider.updateHealthState(newHealthState);
+ * provider.updateModelState(newModelState);
+ * // Cleanup:
+ * unsub();
+ * provider.dispose();
+ * ```
+ */
+export class ProviderHealthDataProvider {
+    _healthState;
+    _modelState;
+    _snapshot;
+    _subscribers = new Set();
+    /** Per-provider timeline buffers, keyed by providerId. */
+    _timelines = new Map();
+    constructor(healthState, modelState) {
+        this._healthState = healthState;
+        this._modelState = modelState;
+        this._seedTimelines(healthState);
+        this._snapshot = this._buildSnapshot();
+    }
+    /**
+     * Return the current enriched provider health data snapshot.
+     * Updated synchronously when state changes via update methods.
+     */
+    getSnapshot() {
+        return this._snapshot;
+    }
+    /**
+     * Register a callback invoked whenever the snapshot changes.
+     * @returns An unsubscribe function.
+     */
+    subscribe(callback) {
+        this._subscribers.add(callback);
+        return () => this._subscribers.delete(callback);
+    }
+    /**
+     * Update provider health state and rebuild the snapshot.
+     * Appends a new timeline point for each provider.
+     */
+    updateHealthState(healthState) {
+        this._healthState = healthState;
+        this._appendTimelinePoints(healthState);
+        this._rebuild();
+    }
+    /**
+     * Update model domain state (e.g. active model or fallback chain change).
+     * Triggers a snapshot rebuild.
+     */
+    updateModelState(modelState) {
+        this._modelState = modelState;
+        this._rebuild();
+    }
+    /**
+     * Release all subscriber references.
+     * Does not clear internal state — getSnapshot() remains usable after disposal.
+     */
+    dispose() {
+        this._subscribers.clear();
+    }
+    // ── Private ────────────────────────────────────────────────────────────────
+    /**
+     * Seed timeline buffers from the initial health state.
+     * Appends one point per known provider to initialize the timeline.
+     */
+    _seedTimelines(healthState) {
+        for (const [id, record] of healthState.providers) {
+            const buffer = { points: [] };
+            this._timelines.set(id, buffer);
+            this._appendPoint(buffer, record);
+        }
+    }
+    /**
+     * Append a new timeline point for every provider in the updated state.
+     * Creates a new buffer for providers seen for the first time.
+     */
+    _appendTimelinePoints(healthState) {
+        for (const [id, record] of healthState.providers) {
+            if (!this._timelines.has(id)) {
+                this._timelines.set(id, { points: [] });
+            }
+            this._appendPoint(this._timelines.get(id), record);
+        }
+    }
+    /** Append a single timeline point to a buffer, capping at TIMELINE_MAX_POINTS. */
+    _appendPoint(buffer, record) {
+        const total = record.stats.totalCalls;
+        const successRate = total > 0 ? record.stats.successCalls / total : 1;
+        const errorRate = total > 0 ? record.stats.errorCalls / total : 0;
+        buffer.points.push({
+            ts: Date.now(),
+            successRate,
+            avgLatencyMs: record.stats.avgLatencyMs,
+            errorRate,
+        });
+        if (buffer.points.length > TIMELINE_MAX_POINTS) {
+            // Array.shift() is O(n) but acceptable: TIMELINE_MAX_POINTS is capped at 60,
+            // so the cost is negligible and the simplicity outweighs a ring-buffer implementation.
+            buffer.points.shift();
+        }
+    }
+    /** Build a HealthTimeline from a buffer for a given provider. */
+    _buildTimeline(providerId) {
+        const buffer = this._timelines.get(providerId);
+        const points = buffer ? [...buffer.points] : [];
+        return {
+            providerId,
+            points,
+            length: points.length,
+        };
+    }
+    _rebuild() {
+        this._snapshot = this._buildSnapshot();
+        this._notify();
+    }
+    _buildSnapshot() {
+        const entries = [];
+        for (const [id, record] of this._healthState.providers) {
+            const total = record.stats.totalCalls;
+            const successRate = total > 0 ? record.stats.successCalls / total : 1;
+            const errorRate = total > 0 ? record.stats.errorCalls / total : 0;
+            entries.push({
+                providerId: id,
+                displayName: record.displayName,
+                status: record.status,
+                isActive: record.isActive,
+                isConfigured: record.isConfigured,
+                successRate,
+                errorRate,
+                p95LatencyMs: record.stats.maxLatencyMs,
+                avgLatencyMs: record.stats.avgLatencyMs,
+                totalCalls: total,
+                // cacheHitRate is populated only when cache-capability is wired to the provider record.
+                // Until then this will always be undefined — intentionally unsupported at this stage.
+                cacheHitRate: record.cacheMetrics?.hitRate,
+                cacheReadTokens: record.cacheMetrics?.cacheReadTokens,
+                cacheWriteTokens: record.cacheMetrics?.cacheWriteTokens,
+                lastSuccessAt: record.stats.lastSuccessAt,
+                lastErrorAt: record.stats.lastErrorAt,
+                lastErrorMessage: record.stats.lastErrorMessage,
+                lastCheckedAt: record.lastCheckedAt,
+                rateLimitResetAt: record.rateLimitResetAt,
+                timeline: this._buildTimeline(id),
+            });
+        }
+        // Sort: degraded/unavailable first (needs attention), then healthy, then unknown
+        entries.sort((a, b) => {
+            const diff = (STATUS_ORDER[a.status] ?? 4) - (STATUS_ORDER[b.status] ?? 4);
+            return diff !== 0 ? diff : a.displayName.localeCompare(b.displayName);
+        });
+        const fallbackChain = buildFallbackChainData(this._modelState, this._healthState);
+        return {
+            entries,
+            compositeStatus: this._healthState.compositeStatus,
+            degradedCount: this._healthState.degradedCount,
+            unavailableCount: this._healthState.unavailableCount,
+            fallbackChain,
+            warnings: this._healthState.warnings,
+            snapshotAt: Date.now(),
+        };
+    }
+    _notify() {
+        for (const cb of this._subscribers) {
+            try {
+                cb();
+            }
+            catch {
+                // Non-fatal: subscriber errors must not crash the provider
+            }
+        }
+    }
+}

package/dist/_internal/platform/runtime/provider-health/fallback-visualizer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Fallback chain visualization data builder.
+ *
+ * Converts the raw fallback chain from ModelDomainState and current
+ * provider health records into a structured FallbackChainData snapshot
+ * suitable for UI rendering.
+ */
+import type { ModelDomainState } from '../store/domains/model.js';
+import type { ProviderHealthDomainState } from '../store/domains/provider-health.js';
+import type { FallbackChainData } from './types.js';
+/**
+ * Build a FallbackChainData snapshot from the current model and health state.
+ *
+ * The primary model is always node 0. Each entry in ModelDomainState.fallbackChain
+ * becomes a subsequent node. Health status is enriched from the provider health domain.
+ *
+ * @param modelState - Current model domain state.
+ * @param healthState - Current provider health domain state.
+ * @returns Immutable FallbackChainData for visualization.
+ */
+export declare function buildFallbackChainData(modelState: ModelDomainState, healthState: ProviderHealthDomainState): FallbackChainData;
+//# sourceMappingURL=fallback-visualizer.d.ts.map

package/dist/_internal/platform/runtime/provider-health/fallback-visualizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-visualizer.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/provider-health/fallback-visualizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,YAAY,CAAC;AAEvE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,yBAAyB,GACrC,iBAAiB,CA4CnB"}