@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/health/aggregator.js

@@ -0,0 +1,188 @@
+/**
+ * RuntimeHealthAggregator — tracks health status for all runtime domains and
+ * derives composite system health. Consumers subscribe to health changes or
+ * query current health state.
+ */
+/** Shallow array equality check for string arrays */
+function arraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** All known domains, used to initialize health map on construction */
+const ALL_DOMAINS = [
+    'turn', 'toolExecution', 'permissions', 'tasks', 'agents',
+    'plugins', 'mcp', 'transport', 'session', 'compaction',
+    'conversation', 'model', 'panels', 'overlays', 'providerHealth',
+    'daemon', 'acp', 'integrations', 'telemetry', 'git',
+    'discovery', 'intelligence', 'surfacePerf',
+];
+/** Default maximum recovery attempts before a domain is considered permanently failed */
+const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
+/**
+ * Tracks per-domain health and derives composite system health.
+ * All domains are initialized as 'unknown' at construction time.
+ * Subscribers are notified synchronously on any health change.
+ */
+export class RuntimeHealthAggregator {
+    domainHealth;
+    subscribers;
+    clock;
+    /**
+     * @param clock - Optional injectable clock function (default: Date.now).
+     *   Useful in tests to control time without real clock dependencies.
+     */
+    constructor(clock = Date.now) {
+        this.clock = clock;
+        this.domainHealth = new Map();
+        this.subscribers = new Set();
+        const now = this.clock();
+        for (const domain of ALL_DOMAINS) {
+            this.domainHealth.set(domain, {
+                domain,
+                status: 'unknown',
+                lastTransitionAt: now,
+                recoveryAttempts: 0,
+                maxRecoveryAttempts: DEFAULT_MAX_RECOVERY_ATTEMPTS,
+            });
+        }
+    }
+    /**
+     * Update a domain's health status and optionally override specific fields.
+     * Notifies all subscribers if the status actually changed.
+     */
+    updateDomainHealth(domain, status, details) {
+        const existing = this.domainHealth.get(domain);
+        const now = this.clock();
+        const updated = {
+            domain,
+            status,
+            lastTransitionAt: existing?.status !== status ? now : (existing?.lastTransitionAt ?? now),
+            recoveryAttempts: details?.recoveryAttempts ?? existing?.recoveryAttempts ?? 0,
+            maxRecoveryAttempts: details?.maxRecoveryAttempts ?? existing?.maxRecoveryAttempts ?? DEFAULT_MAX_RECOVERY_ATTEMPTS,
+            degradedCapabilities: details?.degradedCapabilities ?? existing?.degradedCapabilities,
+            failureReason: details?.failureReason ?? (status !== 'failed' ? undefined : existing?.failureReason),
+        };
+        this.domainHealth.set(domain, updated);
+        // Only notify subscribers if something meaningful changed
+        const statusChanged = existing?.status !== status;
+        const capabilitiesChanged = details?.degradedCapabilities !== undefined &&
+            !arraysEqual(details.degradedCapabilities, existing?.degradedCapabilities);
+        const reasonChanged = details?.failureReason !== undefined &&
+            details.failureReason !== existing?.failureReason;
+        if (statusChanged || capabilitiesChanged || reasonChanged) {
+            this.notifySubscribers();
+        }
+    }
+    /**
+     * Get the current health record for a specific domain.
+     * Always returns a record (domains are pre-initialized as 'unknown').
+     */
+    getDomainHealth(domain) {
+        const health = this.domainHealth.get(domain);
+        if (!health) {
+            // Defensive fallback: domain not in ALL_DOMAINS list
+            return {
+                domain,
+                status: 'unknown',
+                lastTransitionAt: this.clock(),
+                recoveryAttempts: 0,
+                maxRecoveryAttempts: DEFAULT_MAX_RECOVERY_ATTEMPTS,
+            };
+        }
+        return health;
+    }
+    /**
+     * Get composite system health derived from all domain states.
+     * Overall: 'failed' if any domain failed, 'degraded' if any degraded, 'healthy' otherwise.
+     * Domains still 'unknown' do not contribute to 'degraded' or 'failed'.
+     */
+    getCompositeHealth() {
+        const failedDomains = [];
+        const degradedDomains = [];
+        let lastUpdatedAt = 0;
+        for (const health of this.domainHealth.values()) {
+            if (health.status === 'failed')
+                failedDomains.push(health.domain);
+            else if (health.status === 'degraded')
+                degradedDomains.push(health.domain);
+            if (health.lastTransitionAt > lastUpdatedAt)
+                lastUpdatedAt = health.lastTransitionAt;
+        }
+        return {
+            overall: this.deriveOverallHealth(),
+            domains: new Map(this.domainHealth),
+            degradedDomains,
+            failedDomains,
+            lastUpdatedAt,
+        };
+    }
+    /**
+     * Check whether a domain is allowed to execute an operation.
+     * A domain is blocked if it is 'failed' or 'degraded' and the optional operation
+     * matches one of the degradedCapabilities for that domain.
+     */
+    canExecute(domain, operation) {
+        const health = this.getDomainHealth(domain);
+        if (health.status === 'failed') {
+            return {
+                allowed: false,
+                reason: health.failureReason ?? `Domain '${domain}' is in failed state`,
+            };
+        }
+        if (health.status === 'degraded' && operation !== undefined) {
+            const blocked = health.degradedCapabilities?.includes(operation) ?? false;
+            if (blocked) {
+                return {
+                    allowed: false,
+                    reason: `Operation '${operation}' is unavailable while domain '${domain}' is degraded`,
+                };
+            }
+        }
+        return { allowed: true };
+    }
+    /**
+     * Subscribe to composite health changes.
+     * The callback is invoked synchronously after every domain health update.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    /** Derive overall health status from all domain states */
+    deriveOverallHealth() {
+        let hasDegraded = false;
+        let allUnknown = true;
+        for (const health of this.domainHealth.values()) {
+            if (health.status === 'failed')
+                return 'failed';
+            if (health.status === 'degraded')
+                hasDegraded = true;
+            if (health.status !== 'unknown')
+                allUnknown = false;
+        }
+        if (allUnknown)
+            return 'unknown';
+        if (hasDegraded)
+            return 'degraded';
+        return 'healthy';
+    }
+    /** Notify all subscribers with current composite health */
+    notifySubscribers() {
+        const composite = this.getCompositeHealth();
+        for (const subscriber of this.subscribers) {
+            subscriber(composite);
+        }
+    }
+}

package/dist/_internal/platform/runtime/health/cascade-engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CascadeEngine — evaluates declarative cascade rules against live domain health
+ * and determines which effects need to be applied when a domain state changes.
+ *
+ * The engine is read-only with respect to health state — it evaluates and returns
+ * CascadeResult objects; callers are responsible for applying effects.
+ */
+import type { HealthDomain, HealthStatus, CascadeRule, EvaluateResult } from './types.js';
+import type { RuntimeHealthAggregator } from './aggregator.js';
+/**
+ * Evaluates CascadeRules against live domain health changes.
+ * Use checkUpstreamHealth to gate dispatch before executing domain operations.
+ */
+export declare class CascadeEngine {
+    private readonly rules;
+    private readonly aggregator;
+    private readonly clock;
+    /** Pre-indexed rules by domain for O(1) lookup */
+    private readonly ruleIndex;
+    constructor(rules: CascadeRule[], aggregator: RuntimeHealthAggregator, clock?: () => number);
+    /**
+     * Evaluate all cascade rules for a domain health transition.
+     *
+     * Returns an EvaluateResult with two separate arrays:
+     * - `cascades`: effects that are actionable now and should be applied immediately.
+     * - `pendingRecovery`: rules with recoveryFirst where recovery is still possible;
+     *    callers should not apply these yet.
+     *
+     * @param domain - The domain whose health changed.
+     * @param newStatus - The new health status of the domain.
+     * @param sourceContext - Optional context identifying the entity that triggered
+     *   the change (e.g. `{ pluginId: 'my-plugin' }`). Carried into each CascadeResult.
+     */
+    evaluate(domain: HealthDomain, newStatus: HealthStatus, sourceContext?: Record<string, string>): EvaluateResult;
+    /**
+     * Get all rules that would fire for the given domain + status combination.
+     * Uses the pre-indexed rule map for O(1) domain lookup.
+     * Pure — no side effects.
+     */
+    getRulesForDomain(domain: HealthDomain, status: HealthStatus): CascadeRule[];
+    /**
+     * Check whether a domain's upstream dependencies are healthy enough to allow dispatch.
+     * Traverses the cascade rules in reverse: finds rules whose TARGET is this domain
+     * and whose SOURCE is currently in the triggering state.
+     *
+     * Returns whether dispatch is healthy, which upstream domains are blocking it,
+     * and a human-readable reason if blocked.
+     */
+    checkUpstreamHealth(domain: HealthDomain): {
+        healthy: boolean;
+        blockedBy?: HealthDomain[];
+        reason?: string;
+    };
+}
+//# sourceMappingURL=cascade-engine.d.ts.map

package/dist/_internal/platform/runtime/health/cascade-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-engine.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/cascade-engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EAEX,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;GAGG;AACH,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;gBAG1C,KAAK,EAAE,WAAW,EAAE,EACpB,UAAU,EAAE,uBAAuB,EACnC,KAAK,GAAE,MAAM,MAAiB;IAWjD;;;;;;;;;;;;OAYG;IACH,QAAQ,CACN,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,YAAY,EACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,cAAc;IAqDjB;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,EAAE;IAK5E;;;;;;;OAOG;IACH,mBAAmB,CACjB,MAAM,EAAE,YAAY,GACnB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAmCrE"}

package/dist/_internal/platform/runtime/health/cascade-engine.js

@@ -0,0 +1,134 @@
+/**
+ * CascadeEngine — evaluates declarative cascade rules against live domain health
+ * and determines which effects need to be applied when a domain state changes.
+ *
+ * The engine is read-only with respect to health state — it evaluates and returns
+ * CascadeResult objects; callers are responsible for applying effects.
+ */
+/**
+ * Evaluates CascadeRules against live domain health changes.
+ * Use checkUpstreamHealth to gate dispatch before executing domain operations.
+ */
+export class CascadeEngine {
+    rules;
+    aggregator;
+    clock;
+    /** Pre-indexed rules by domain for O(1) lookup */
+    ruleIndex;
+    constructor(rules, aggregator, clock = Date.now) {
+        this.rules = rules;
+        this.aggregator = aggregator;
+        this.clock = clock;
+        // Pre-index rules by source domain for O(1) lookups
+        this.ruleIndex = new Map();
+        for (const rule of rules) {
+            const existing = this.ruleIndex.get(rule.source) ?? [];
+            existing.push(rule);
+            this.ruleIndex.set(rule.source, existing);
+        }
+    }
+    /**
+     * Evaluate all cascade rules for a domain health transition.
+     *
+     * Returns an EvaluateResult with two separate arrays:
+     * - `cascades`: effects that are actionable now and should be applied immediately.
+     * - `pendingRecovery`: rules with recoveryFirst where recovery is still possible;
+     *    callers should not apply these yet.
+     *
+     * @param domain - The domain whose health changed.
+     * @param newStatus - The new health status of the domain.
+     * @param sourceContext - Optional context identifying the entity that triggered
+     *   the change (e.g. `{ pluginId: 'my-plugin' }`). Carried into each CascadeResult.
+     */
+    evaluate(domain, newStatus, sourceContext) {
+        const matchingRules = this.getRulesForDomain(domain, newStatus);
+        const cascades = [];
+        const pendingRecovery = [];
+        const now = this.clock();
+        for (const rule of matchingRules) {
+            if (rule.recoveryFirst) {
+                const domainHealth = this.aggregator.getDomainHealth(domain);
+                const exhausted = domainHealth.recoveryAttempts >= domainHealth.maxRecoveryAttempts;
+                if (!exhausted) {
+                    // Recovery still possible — do not cascade yet
+                    pendingRecovery.push({
+                        ruleId: rule.id,
+                        source: domain,
+                        target: rule.target,
+                        effect: rule.effect,
+                        timestamp: now,
+                        recoveryExhausted: false,
+                        sourceContext,
+                    });
+                    continue;
+                }
+                // Recovery exhausted — cascade now, mark recoveryExhausted: true
+                cascades.push({
+                    ruleId: rule.id,
+                    source: domain,
+                    target: rule.target,
+                    effect: rule.effect,
+                    timestamp: now,
+                    recoveryExhausted: true,
+                    sourceContext,
+                });
+                continue;
+            }
+            cascades.push({
+                ruleId: rule.id,
+                source: domain,
+                target: rule.target,
+                effect: rule.effect,
+                timestamp: now,
+                recoveryExhausted: false,
+                sourceContext,
+            });
+        }
+        return { cascades, pendingRecovery };
+    }
+    /**
+     * Get all rules that would fire for the given domain + status combination.
+     * Uses the pre-indexed rule map for O(1) domain lookup.
+     * Pure — no side effects.
+     */
+    getRulesForDomain(domain, status) {
+        const domainRules = this.ruleIndex.get(domain) ?? [];
+        return domainRules.filter((rule) => rule.sourceState === status);
+    }
+    /**
+     * Check whether a domain's upstream dependencies are healthy enough to allow dispatch.
+     * Traverses the cascade rules in reverse: finds rules whose TARGET is this domain
+     * and whose SOURCE is currently in the triggering state.
+     *
+     * Returns whether dispatch is healthy, which upstream domains are blocking it,
+     * and a human-readable reason if blocked.
+     */
+    checkUpstreamHealth(domain) {
+        const blockingDomains = [];
+        for (const rule of this.rules) {
+            // A rule blocks 'domain' if its target is this domain (or ALL)
+            // and the source domain is currently in the rule's triggering state
+            const targetsThisDomain = rule.target === domain || rule.target === 'ALL';
+            if (!targetsThisDomain)
+                continue;
+            // Only blocking effects count as upstream blockers
+            const isBlockingEffect = rule.effect.type === 'BLOCK_DISPATCH' ||
+                rule.effect.type === 'CANCEL_INFLIGHT' ||
+                rule.effect.type === 'BLOCK_NEW';
+            if (!isBlockingEffect)
+                continue;
+            const sourceHealth = this.aggregator.getDomainHealth(rule.source);
+            if (sourceHealth.status === rule.sourceState) {
+                blockingDomains.push(rule.source);
+            }
+        }
+        if (blockingDomains.length === 0) {
+            return { healthy: true };
+        }
+        return {
+            healthy: false,
+            blockedBy: blockingDomains,
+            reason: `Domain '${domain}' is blocked by upstream failure in: ${blockingDomains.join(', ')}`,
+        };
+    }
+}

package/dist/_internal/platform/runtime/health/cascade-playbook-map.d.ts

@@ -0,0 +1,23 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Cascade rule → remediation playbook mapping.
+ *
+ * Each cascade rule ID maps to one or more playbook IDs that provide
+ * actionable remediation steps for that failure mode.
+ *
+ * This mapping is consumed by:
+ * - CascadeTimer (attaches remediationPlaybookIds to TimedCascadeResult)
+ * - HealthPanel (surfaces remediation actions in the health dashboard)
+ * - Completeness tests (verify every rule has at least one playbook)
+ */
+/**
+ * Map from cascade rule ID → ordered list of remediation playbook IDs.
+ * The first playbook in each array is the primary recommendation.
+ */
+export declare const CASCADE_PLAYBOOK_MAP: ReadonlyMap<string, readonly string[]>;
+/**
+ * All cascade rule IDs that must have at least one playbook mapping.
+ * Derived from cascade-rules.ts — update when rules are added or removed.
+ */
+export declare const ALL_CASCADE_RULE_IDS: readonly string[];
+//# sourceMappingURL=cascade-playbook-map.d.ts.map

package/dist/_internal/platform/runtime/health/cascade-playbook-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-playbook-map.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/cascade-playbook-map.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAyBtE,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EASjD,CAAC"}

package/dist/_internal/platform/runtime/health/cascade-playbook-map.js

@@ -0,0 +1,49 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Cascade rule → remediation playbook mapping.
+ *
+ * Each cascade rule ID maps to one or more playbook IDs that provide
+ * actionable remediation steps for that failure mode.
+ *
+ * This mapping is consumed by:
+ * - CascadeTimer (attaches remediationPlaybookIds to TimedCascadeResult)
+ * - HealthPanel (surfaces remediation actions in the health dashboard)
+ * - Completeness tests (verify every rule has at least one playbook)
+ */
+/**
+ * Map from cascade rule ID → ordered list of remediation playbook IDs.
+ * The first playbook in each array is the primary recommendation.
+ */
+export const CASCADE_PLAYBOOK_MAP = new Map([
+    // turn-failed-cancels-tools: stuck turn is the primary remediation path
+    ['turn-failed-cancels-tools', ['stuck-turn']],
+    // tool-failed-errors-turn: stuck turn playbook covers tool deadlock and recovery
+    ['tool-failed-errors-turn', ['stuck-turn']],
+    // mcp-disconnected-blocks-mcp-tools: reconnect failure playbook
+    ['mcp-disconnected-blocks-mcp-tools', ['reconnect-failure']],
+    // agent-failed-marks-child-tasks: stuck turn covers turn/task lifecycle recovery
+    ['agent-failed-marks-child-tasks', ['stuck-turn']],
+    // plugin-error-deregisters-tools: plugin degradation playbook
+    ['plugin-error-deregisters-tools', ['plugin-degradation']],
+    // transport-disconnected-blocks-remote-tasks: reconnect failure is primary;
+    // stuck turn is secondary for any blocked tasks
+    ['transport-disconnected-blocks-remote-tasks', ['reconnect-failure', 'stuck-turn']],
+    // session-recovery-failed-unrecoverable: dedicated session unrecoverable playbook
+    ['session-recovery-failed-unrecoverable', ['session-unrecoverable']],
+    // compaction-failed-blocks-new-turns: dedicated compaction failure playbook
+    ['compaction-failed-blocks-new-turns', ['compaction-failure']],
+]);
+/**
+ * All cascade rule IDs that must have at least one playbook mapping.
+ * Derived from cascade-rules.ts — update when rules are added or removed.
+ */
+export const ALL_CASCADE_RULE_IDS = [
+    'turn-failed-cancels-tools',
+    'tool-failed-errors-turn',
+    'mcp-disconnected-blocks-mcp-tools',
+    'agent-failed-marks-child-tasks',
+    'plugin-error-deregisters-tools',
+    'transport-disconnected-blocks-remote-tasks',
+    'session-recovery-failed-unrecoverable',
+    'compaction-failed-blocks-new-turns',
+];

package/dist/_internal/platform/runtime/health/cascade-rules.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declarative cascade rules table for the goodvibes-sdk runtime.
+ * Cross-machine error propagation rules.
+ *
+ * Each entry is pure data — adding a new cascade rule means adding a new object to this array.
+ * The CascadeEngine consumes this table; no logic lives here.
+ */
+import type { CascadeRule } from './types.js';
+/**
+ * All cascade rules that govern cross-domain health propagation.
+ * Rules are evaluated by the CascadeEngine whenever a domain health changes.
+ */
+export declare const CASCADE_RULES: CascadeRule[];
+//# sourceMappingURL=cascade-rules.d.ts.map

package/dist/_internal/platform/runtime/health/cascade-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-rules.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/cascade-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EA6EtC,CAAC"}

package/dist/_internal/platform/runtime/health/cascade-rules.js

@@ -0,0 +1,89 @@
+/**
+ * Declarative cascade rules table for the goodvibes-sdk runtime.
+ * Cross-machine error propagation rules.
+ *
+ * Each entry is pure data — adding a new cascade rule means adding a new object to this array.
+ * The CascadeEngine consumes this table; no logic lives here.
+ */
+/**
+ * All cascade rules that govern cross-domain health propagation.
+ * Rules are evaluated by the CascadeEngine whenever a domain health changes.
+ */
+export const CASCADE_RULES = [
+    {
+        id: 'turn-failed-cancels-tools',
+        source: 'turn',
+        sourceState: 'failed',
+        target: 'toolExecution',
+        effect: { type: 'CANCEL_INFLIGHT', scope: 'all-tools' },
+        description: 'When the turn lifecycle fails, cancel all in-flight tool executions.',
+        recoveryFirst: false,
+    },
+    {
+        id: 'tool-failed-errors-turn',
+        source: 'toolExecution',
+        sourceState: 'failed',
+        target: 'turn',
+        effect: { type: 'EMIT_EVENT', eventType: 'TOOL_DISPATCH_ERROR' },
+        description: 'When tool execution fails, transition the turn lifecycle to the tool_dispatch error path.',
+        recoveryFirst: true,
+    },
+    {
+        id: 'mcp-disconnected-blocks-mcp-tools',
+        source: 'mcp',
+        sourceState: 'failed',
+        target: 'toolExecution',
+        effect: { type: 'BLOCK_DISPATCH', scope: 'mcp-tools', queueable: true },
+        description: 'When MCP server disconnects, block MCP tool dispatch (queue pending calls).',
+        recoveryFirst: true,
+    },
+    {
+        id: 'agent-failed-marks-child-tasks',
+        source: 'agents',
+        sourceState: 'failed',
+        target: 'tasks',
+        effect: { type: 'MARK_CHILDREN', status: 'failed', notifyParent: true },
+        description: 'When an agent lifecycle fails, mark all owned child tasks as failed and notify the parent.',
+        recoveryFirst: false,
+    },
+    {
+        id: 'plugin-error-deregisters-tools',
+        source: 'plugins',
+        sourceState: 'failed',
+        target: 'toolExecution',
+        // NOTE: To deregister only the failing plugin's tools (not all plugins),
+        // pass sourceContext: { pluginId: '<the-plugin-id>' } when calling evaluate().
+        // The CascadeEngine propagates sourceContext into CascadeResult, so callers
+        // can read result.sourceContext?.pluginId to scope the DEREGISTER_TOOLS effect.
+        effect: { type: 'DEREGISTER_TOOLS' },
+        description: 'When a plugin enters error state, deregister its tools and fail any in-flight plugin tool calls.',
+        recoveryFirst: false,
+    },
+    {
+        id: 'transport-disconnected-blocks-remote-tasks',
+        source: 'transport',
+        sourceState: 'failed',
+        target: 'tasks',
+        effect: { type: 'BLOCK_DISPATCH', scope: 'remote-tasks', queueable: false },
+        description: 'When ACP/daemon transport disconnects, mark remote tasks blocked and initiate reconnect.',
+        recoveryFirst: true,
+    },
+    {
+        id: 'session-recovery-failed-unrecoverable',
+        source: 'session',
+        sourceState: 'failed',
+        target: 'ALL',
+        effect: { type: 'EMIT_EVENT', eventType: 'SESSION_UNRECOVERABLE' },
+        description: 'When session recovery fails, emit SESSION_UNRECOVERABLE to all machines.',
+        recoveryFirst: false,
+    },
+    {
+        id: 'compaction-failed-blocks-new-turns',
+        source: 'compaction',
+        sourceState: 'failed',
+        target: 'turn',
+        effect: { type: 'BLOCK_NEW', scope: 'new-turns' },
+        description: 'When compaction fails, block new turns from starting.',
+        recoveryFirst: true,
+    },
+];

package/dist/_internal/platform/runtime/health/cascade-timing.d.ts

@@ -0,0 +1,79 @@
+/**
+ * CascadeTimer — timing instrumentation for cascade rule evaluations.
+ *
+ * Wraps CascadeEngine.evaluate() to measure evaluation latency and attach
+ * timing metadata (latencyMs, severity, remediationPlaybookIds) to each
+ * CascadeResult before returning them to callers.
+ *
+ * The timer is transparent to the cascade engine — it delegates evaluation
+ * and annotates results without modifying engine state.
+ */
+import type { HealthDomain, HealthStatus, CascadeResult } from './types.js';
+import type { CascadeEngine } from './cascade-engine.js';
+/**
+ * Severity tier derived from cascaded effect type and recovery state.
+ *
+ * - 'critical': session unrecoverable or all-domain block
+ * - 'high':     blocking or cancellation effects without recovery first
+ * - 'medium':   blocking effects with recovery exhausted
+ * - 'low':      emit-only or informational effects
+ */
+export type CascadeSeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Derive a severity level from a cascade result's effect type and recovery state.
+ */
+export declare function deriveCascadeSeverity(result: CascadeResult): CascadeSeverity;
+/**
+ * A CascadeResult annotated with timing and remediation metadata.
+ */
+export interface TimedCascadeResult extends CascadeResult {
+    /** Wall-clock latency of the cascade rule evaluation in milliseconds. */
+    readonly latencyMs: number;
+    /** Severity tier derived from the cascade effect and recovery state. */
+    readonly severity: CascadeSeverity;
+    /** Playbook IDs that provide remediation for this cascade type. */
+    readonly remediationPlaybookIds: readonly string[];
+}
+/**
+ * EvaluateResult variant where all results carry timing metadata.
+ */
+export interface TimedEvaluateResult {
+    readonly cascades: TimedCascadeResult[];
+    readonly pendingRecovery: TimedCascadeResult[];
+    /** Total wall-clock latency of the full evaluation in milliseconds. */
+    readonly totalLatencyMs: number;
+}
+/**
+ * CascadeTimer — instruments CascadeEngine.evaluate() with latency tracking.
+ *
+ * Wrap the cascade engine with this class to get TimedCascadeResult objects
+ * that include per-result latency, severity, and remediation playbook IDs.
+ *
+ * @example
+ * ```ts
+ * const timer = new CascadeTimer(cascadeEngine);
+ * const { cascades, totalLatencyMs } = timer.evaluate('mcp', 'failed');
+ * // cascades[0].latencyMs — evaluation latency
+ * // cascades[0].severity  — 'high' | 'critical' etc.
+ * // cascades[0].remediationPlaybookIds — ['reconnect-failure']
+ * ```
+ */
+export declare class CascadeTimer {
+    private readonly engine;
+    private readonly clock;
+    constructor(engine: CascadeEngine, clock?: () => number);
+    /**
+     * Evaluate cascade rules for a domain health transition, measuring latency.
+     *
+     * Each returned result is annotated with:
+     * - `latencyMs`: wall-clock cost of evaluating this specific domain+status pair
+     * - `severity`: derived criticality tier
+     * - `remediationPlaybookIds`: playbook IDs mapped for this rule
+     *
+     * @param domain - The domain whose health changed.
+     * @param newStatus - The new health status.
+     * @param sourceContext - Optional entity context (e.g. `{ pluginId }`).
+     */
+    evaluate(domain: HealthDomain, newStatus: HealthStatus, sourceContext?: Record<string, string>): TimedEvaluateResult;
+}
+//# sourceMappingURL=cascade-timing.d.ts.map

package/dist/_internal/platform/runtime/health/cascade-timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-timing.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/cascade-timing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAC5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErE;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CA+B5E;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,kBAAkB,EAAE,CAAC;IAC/C,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAcD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,MAAM,EAAE,aAAa,EACrB,KAAK,GAAE,MAAM,MAAiB;IAGjD;;;;;;;;;;;OAWG;IACH,QAAQ,CACN,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,YAAY,EACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,mBAAmB;CAYvB"}