@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/mcp/schema-freshness.d.ts

@@ -0,0 +1,115 @@
+/**
+ * MCP schema freshness tracking.
+ *
+ * Tracks per-server schema cache freshness with TTL-based staleness detection.
+ * Used by McpLifecycleManager to decide when to trigger background re-fetches.
+ */
+import type { SchemaFreshness, McpSchemaRecord, QuarantineReason } from './types.js';
+/**
+ * Tracks schema freshness for every registered MCP server.
+ *
+ * Lifecycle:
+ *   1. `registerServer(name)` — initialised with `unknown` freshness.
+ *   2. `markFresh(name)`      — called after a successful schema fetch.
+ *   3. `markFailed(name, err)` — called after a failed fetch attempt.
+ *   4. `markStale(name)`      — called when a server reconnects (cache invalidated).
+ *   5. `getFreshness(name)`   — returns current freshness, accounting for TTL.
+ *   6. `removeServer(name)`   — drops the record on permanent disconnection.
+ *   7. `markQuarantined(name, reason, detail)` — places schema into quarantine;
+ *      execution is blocked until `approveQuarantine` or a successful refresh.
+ *   8. `approveQuarantine(name, operatorId)` — operator override: acknowledges
+ *      the quarantine and temporarily unblocks execution.
+ */
+export declare class McpSchemaFreshnessTracker {
+    private readonly records;
+    private readonly ttlMs;
+    private readonly quarantineThreshold;
+    /**
+     * @param ttlMs               - TTL in ms before a fresh record becomes stale (default 5 min)
+     * @param quarantineThreshold - consecutive failures before auto-quarantine (default 3)
+     */
+    constructor(ttlMs?: number, quarantineThreshold?: number);
+    /**
+     * Register a new server with `unknown` freshness.
+     * Idempotent — calling again for an already-registered server is a no-op.
+     *
+     * @param serverName - Server identifier
+     */
+    registerServer(serverName: string): void;
+    /**
+     * Remove a server's freshness record.
+     *
+     * @param serverName - Server identifier
+     */
+    removeServer(serverName: string): void;
+    /**
+     * Mark a server's schemas as freshly fetched.
+     * Resets the consecutive failure counter and sets the expiry timestamp.
+     *
+     * @param serverName - Server identifier
+     */
+    markFresh(serverName: string): void;
+    /**
+     * Mark a schema fetch as failed.
+     * Increments consecutive failure counter.
+     *
+     * @param serverName - Server identifier
+     * @param error      - Error message from the failed attempt
+     */
+    markFailed(serverName: string, error: string): void;
+    /**
+     * Mark a server's schemas as stale (e.g. after reconnect or explicit invalidation).
+     *
+     * @param serverName - Server identifier
+     */
+    markStale(serverName: string): void;
+    /**
+     * Place a server's schema into quarantine.
+     *
+     * Quarantine blocks all tool execution on the server until the operator
+     * approves an override (`approveQuarantine`) or a successful schema refresh
+     * occurs (`markFresh`).
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Why quarantine is being applied
+     * @param detail     - Optional human-readable detail shown in the MCP panel
+     */
+    markQuarantined(serverName: string, reason: QuarantineReason, detail?: string): void;
+    /**
+     * Operator override: acknowledge a quarantined schema and temporarily unblock
+     * tool execution without refreshing the schema.
+     *
+     * The quarantine record is preserved (with override metadata) so auditors can
+     * see that execution was approved under a quarantined schema. Freshness
+     * transitions back to `stale` to signal a refresh is still needed.
+     *
+     * @param serverName - Server identifier
+     * @param operatorId - Identifier of the operator acknowledging the override
+     */
+    approveQuarantine(serverName: string, operatorId: string): void;
+    /**
+     * Return the current freshness of a server's schema cache.
+     *
+     * If the stored state is `fresh` but the TTL has elapsed, returns `stale`
+     * and updates the record in-place.
+     *
+     * @param serverName - Server identifier
+     */
+    getFreshness(serverName: string): SchemaFreshness;
+    /**
+     * Returns `true` if the server's schema is quarantined and tool execution
+     * should be blocked.
+     *
+     * @param serverName - Server identifier
+     */
+    isQuarantined(serverName: string): boolean;
+    /**
+     * Return the full schema record for a server, or `null` if not registered.
+     *
+     * @param serverName - Server identifier
+     */
+    getRecord(serverName: string): McpSchemaRecord | null;
+    private _getOrCreate;
+    private _applyQuarantine;
+}
+//# sourceMappingURL=schema-freshness.d.ts.map

package/dist/platform/runtime/mcp/schema-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-freshness.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/mcp/schema-freshness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgBrF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C;;;OAGG;gBACS,KAAK,SAAiB,EAAE,mBAAmB,SAA+B;IAOtF;;;;;OAKG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IASxC;;;;OAIG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMtC;;;;;OAKG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAYnC;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAmBnD;;;;OAIG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAWnC;;;;;;;;;;OAUG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAMpF;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IA4B/D;;;;;;;OAOG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe;IAmBjD;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C;;;;OAIG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAMrD,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,gBAAgB;CASzB"}

package/dist/platform/runtime/mcp/schema-freshness.js

@@ -0,0 +1,231 @@
+import { logger } from '../../utils/logger.js';
+// ── Defaults ──────────────────────────────────────────────────────────────────
+/** Default TTL in ms after which a fresh record becomes stale (5 minutes). */
+const DEFAULT_TTL_MS = 5 * 60 * 1_000;
+/**
+ * Default consecutive failure threshold before auto-quarantine is applied.
+ * After this many consecutive fetch failures the schema is quarantined.
+ */
+const DEFAULT_QUARANTINE_THRESHOLD = 3;
+// ── Tracker ───────────────────────────────────────────────────────────────────
+/**
+ * Tracks schema freshness for every registered MCP server.
+ *
+ * Lifecycle:
+ *   1. `registerServer(name)` — initialised with `unknown` freshness.
+ *   2. `markFresh(name)`      — called after a successful schema fetch.
+ *   3. `markFailed(name, err)` — called after a failed fetch attempt.
+ *   4. `markStale(name)`      — called when a server reconnects (cache invalidated).
+ *   5. `getFreshness(name)`   — returns current freshness, accounting for TTL.
+ *   6. `removeServer(name)`   — drops the record on permanent disconnection.
+ *   7. `markQuarantined(name, reason, detail)` — places schema into quarantine;
+ *      execution is blocked until `approveQuarantine` or a successful refresh.
+ *   8. `approveQuarantine(name, operatorId)` — operator override: acknowledges
+ *      the quarantine and temporarily unblocks execution.
+ */
+export class McpSchemaFreshnessTracker {
+    records = new Map();
+    ttlMs;
+    quarantineThreshold;
+    /**
+     * @param ttlMs               - TTL in ms before a fresh record becomes stale (default 5 min)
+     * @param quarantineThreshold - consecutive failures before auto-quarantine (default 3)
+     */
+    constructor(ttlMs = DEFAULT_TTL_MS, quarantineThreshold = DEFAULT_QUARANTINE_THRESHOLD) {
+        this.ttlMs = ttlMs;
+        this.quarantineThreshold = quarantineThreshold;
+    }
+    // ── Registration ─────────────────────────────────────────────────────────
+    /**
+     * Register a new server with `unknown` freshness.
+     * Idempotent — calling again for an already-registered server is a no-op.
+     *
+     * @param serverName - Server identifier
+     */
+    registerServer(serverName) {
+        if (this.records.has(serverName))
+            return;
+        this.records.set(serverName, {
+            serverName,
+            freshness: 'unknown',
+            consecutiveFailures: 0,
+        });
+    }
+    /**
+     * Remove a server's freshness record.
+     *
+     * @param serverName - Server identifier
+     */
+    removeServer(serverName) {
+        this.records.delete(serverName);
+    }
+    // ── Mutations ────────────────────────────────────────────────────────────
+    /**
+     * Mark a server's schemas as freshly fetched.
+     * Resets the consecutive failure counter and sets the expiry timestamp.
+     *
+     * @param serverName - Server identifier
+     */
+    markFresh(serverName) {
+        const record = this._getOrCreate(serverName);
+        const now = Date.now();
+        record.freshness = 'fresh';
+        record.fetchedAt = now;
+        record.expiresAt = now + this.ttlMs;
+        record.consecutiveFailures = 0;
+        delete record.lastFetchError;
+        delete record.quarantine;
+        logger.debug('McpSchemaFreshnessTracker: marked fresh', { serverName, expiresAt: record.expiresAt });
+    }
+    /**
+     * Mark a schema fetch as failed.
+     * Increments consecutive failure counter.
+     *
+     * @param serverName - Server identifier
+     * @param error      - Error message from the failed attempt
+     */
+    markFailed(serverName, error) {
+        const record = this._getOrCreate(serverName);
+        record.lastFetchError = error;
+        record.consecutiveFailures += 1;
+        if (record.consecutiveFailures >= this.quarantineThreshold) {
+            // Auto-quarantine after threshold exceeded
+            this._applyQuarantine(record, 'stale_threshold', `Schema fetch failed ${record.consecutiveFailures} consecutive times: ${error}`);
+            logger.warn('McpSchemaFreshnessTracker: auto-quarantined after repeated failures', {
+                serverName,
+                consecutiveFailures: record.consecutiveFailures,
+            });
+        }
+        else {
+            record.freshness = 'fetch_failed';
+            logger.debug('McpSchemaFreshnessTracker: fetch failed', { serverName, error, consecutiveFailures: record.consecutiveFailures });
+        }
+    }
+    /**
+     * Mark a server's schemas as stale (e.g. after reconnect or explicit invalidation).
+     *
+     * @param serverName - Server identifier
+     */
+    markStale(serverName) {
+        const record = this._getOrCreate(serverName);
+        // Explicit guard: quarantined records must be released via approveQuarantine or markFresh.
+        if (record.freshness === 'quarantined')
+            return;
+        if (record.freshness === 'fresh') {
+            record.freshness = 'stale';
+            delete record.expiresAt;
+            logger.debug('McpSchemaFreshnessTracker: marked stale', { serverName });
+        }
+    }
+    /**
+     * Place a server's schema into quarantine.
+     *
+     * Quarantine blocks all tool execution on the server until the operator
+     * approves an override (`approveQuarantine`) or a successful schema refresh
+     * occurs (`markFresh`).
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Why quarantine is being applied
+     * @param detail     - Optional human-readable detail shown in the MCP panel
+     */
+    markQuarantined(serverName, reason, detail) {
+        const record = this._getOrCreate(serverName);
+        this._applyQuarantine(record, reason, detail);
+        logger.warn('McpSchemaFreshnessTracker: schema quarantined', { serverName, reason, detail });
+    }
+    /**
+     * Operator override: acknowledge a quarantined schema and temporarily unblock
+     * tool execution without refreshing the schema.
+     *
+     * The quarantine record is preserved (with override metadata) so auditors can
+     * see that execution was approved under a quarantined schema. Freshness
+     * transitions back to `stale` to signal a refresh is still needed.
+     *
+     * @param serverName - Server identifier
+     * @param operatorId - Identifier of the operator acknowledging the override
+     */
+    approveQuarantine(serverName, operatorId) {
+        const record = this.records.get(serverName);
+        if (!record) {
+            logger.debug('McpSchemaFreshnessTracker: approveQuarantine called on unknown server', { serverName });
+            return;
+        }
+        if (record.freshness !== 'quarantined') {
+            logger.debug('McpSchemaFreshnessTracker: approveQuarantine called but not quarantined', { serverName, freshness: record.freshness });
+            return;
+        }
+        const now = Date.now();
+        if (record.quarantine) {
+            record.quarantine.overrideAcknowledgedBy = operatorId;
+            record.quarantine.overrideAcknowledgedAt = now;
+        }
+        // Transition to stale — fresh requires a real schema fetch.
+        // Reset consecutiveFailures so the next transient error does not immediately
+        // re-quarantine and undo the operator's override.
+        record.freshness = 'stale';
+        record.consecutiveFailures = 0;
+        delete record.expiresAt;
+        logger.warn('McpSchemaFreshnessTracker: quarantine override approved', { serverName, operatorId });
+    }
+    // ── Query ────────────────────────────────────────────────────────────────
+    /**
+     * Return the current freshness of a server's schema cache.
+     *
+     * If the stored state is `fresh` but the TTL has elapsed, returns `stale`
+     * and updates the record in-place.
+     *
+     * @param serverName - Server identifier
+     */
+    getFreshness(serverName) {
+        const record = this.records.get(serverName);
+        if (!record)
+            return 'unknown';
+        // Quarantine is sticky — it takes precedence over any TTL check
+        if (record.freshness === 'quarantined')
+            return 'quarantined';
+        if (record.freshness === 'fresh' && record.expiresAt !== undefined) {
+            if (Date.now() > record.expiresAt) {
+                // TTL elapsed — transition to stale in-place
+                record.freshness = 'stale';
+                delete record.expiresAt;
+                logger.debug('McpSchemaFreshnessTracker: TTL elapsed, marked stale', { serverName });
+            }
+        }
+        return record.freshness;
+    }
+    /**
+     * Returns `true` if the server's schema is quarantined and tool execution
+     * should be blocked.
+     *
+     * @param serverName - Server identifier
+     */
+    isQuarantined(serverName) {
+        return this.records.get(serverName)?.freshness === 'quarantined';
+    }
+    /**
+     * Return the full schema record for a server, or `null` if not registered.
+     *
+     * @param serverName - Server identifier
+     */
+    getRecord(serverName) {
+        return this.records.get(serverName) ?? null;
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    _getOrCreate(serverName) {
+        let record = this.records.get(serverName);
+        if (!record) {
+            record = { serverName, freshness: 'unknown', consecutiveFailures: 0 };
+            this.records.set(serverName, record);
+        }
+        return record;
+    }
+    _applyQuarantine(record, reason, detail) {
+        record.freshness = 'quarantined';
+        delete record.expiresAt;
+        record.quarantine = {
+            reason,
+            quarantinedAt: Date.now(),
+            ...(detail !== undefined ? { detail } : {}),
+        };
+    }
+}

package/dist/platform/runtime/mcp/types.d.ts

@@ -0,0 +1,275 @@
+/**
+ * MCP lifecycle core type definitions.
+ *
+ * Referenced by: lifecycle.ts, permissions.ts, schema-freshness.ts, manager.ts
+ * Spec: server state machine and MCP evolution.
+ */
+import type { McpServerConfig } from '../../mcp/config.js';
+/**
+ * All legal states in the MCP server lifecycle state machine.
+ *
+ * Transition diagram:
+ *   configured → connecting → connected → degraded
+ *   connected  → auth_required
+ *   connected  → reconnecting → connected
+ *   connected  → disconnected
+ *   reconnecting → disconnected (max attempts exceeded)
+ *   degraded   → reconnecting
+ *   degraded   → disconnected
+ *   auth_required → connecting (after credentials provided)
+ *   auth_required → disconnected
+ */
+export type McpServerState = 'configured' | 'connecting' | 'connected' | 'degraded' | 'auth_required' | 'reconnecting' | 'disconnected';
+/**
+ * Freshness status of a server's tool/resource schema cache.
+ *
+ * - `fresh`        — fetched recently, within the TTL window
+ * - `stale`        — fetched but TTL has elapsed; re-fetch recommended
+ * - `unknown`      — never fetched or record cleared
+ * - `fetch_failed` — last fetch attempt returned an error
+ * - `quarantined`  — schema is incompatible or stale past threshold; execution
+ *                    blocked until operator refreshes or explicitly acknowledges
+ */
+export type SchemaFreshness = 'fresh' | 'stale' | 'unknown' | 'fetch_failed' | 'quarantined';
+/**
+ * Reason a schema was placed into quarantine.
+ *
+ * - `stale_threshold`   — TTL expired and refresh failed repeatedly
+ * - `incompatible`      — schema version is incompatible with the runtime
+ * - `operator_flagged`  — manually flagged by an operator for review
+ */
+export type QuarantineReason = 'stale_threshold' | 'incompatible' | 'operator_flagged';
+/** Quarantine record attached to a schema when it enters the quarantined state. */
+export interface QuarantineRecord {
+    /** Why the schema was quarantined. */
+    reason: QuarantineReason;
+    /** Epoch ms when quarantine was applied. */
+    quarantinedAt: number;
+    /** Human-readable detail for display in the MCP panel. */
+    detail?: string;
+    /** Operator identifier who acknowledged and approved override, if any. */
+    overrideAcknowledgedBy?: string;
+    /** Epoch ms when the operator acknowledged the quarantine override. */
+    overrideAcknowledgedAt?: number;
+}
+/** Per-server schema record tracking freshness metadata. */
+export interface McpSchemaRecord {
+    /** Server name this record belongs to. */
+    serverName: string;
+    /** Current freshness state. */
+    freshness: SchemaFreshness;
+    /** Epoch ms when schemas were last successfully fetched. */
+    fetchedAt?: number;
+    /** Epoch ms when the next fetch is required (fetchedAt + ttl). */
+    expiresAt?: number;
+    /** Error message from the last failed fetch attempt. */
+    lastFetchError?: string;
+    /** Number of consecutive failed fetch attempts. */
+    consecutiveFailures: number;
+    /** Quarantine metadata, present only when freshness is 'quarantined'. */
+    quarantine?: QuarantineRecord;
+}
+/**
+ * Trust level assigned to an MCP server.
+ *
+ * - `trusted`    — all tools allowed; schema auto-refreshed
+ * - `standard`   — all tools allowed; subject to per-tool overrides
+ * - `restricted` — only explicitly allow-listed tools may be called
+ * - `blocked`    — no tool calls permitted regardless of allow-list
+ */
+export type McpTrustLevel = 'trusted' | 'standard' | 'restricted' | 'blocked';
+/** Runtime trust mode used by the hardened MCP policy layer. */
+export type McpTrustMode = 'constrained' | 'ask-on-risk' | 'allow-all' | 'blocked';
+/** High-level server role used for coherence evaluation. */
+export type McpServerRole = 'general' | 'docs' | 'filesystem' | 'git' | 'database' | 'browser' | 'automation' | 'ops' | 'remote';
+/** Capability classes inferred for MCP tool calls. */
+export type McpCapabilityClass = 'metadata' | 'read_fs' | 'write_fs' | 'exec' | 'network_read' | 'network_write' | 'secret_read' | 'spawn_agent' | 'config_mutation' | 'system_mutation' | 'generic';
+export type McpCoherenceVerdict = 'allow' | 'ask' | 'deny';
+export type McpRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export interface McpTrustProfile {
+    serverName: string;
+    role: McpServerRole;
+    mode: McpTrustMode;
+    allowedPaths: string[];
+    allowedHosts: string[];
+    allowedCapabilities: McpCapabilityClass[];
+    notes?: string;
+    lastModifiedAt: number;
+}
+export interface McpCoherenceAssessment {
+    verdict: McpCoherenceVerdict;
+    riskLevel: McpRiskLevel;
+    capability: McpCapabilityClass;
+    incoherent: boolean;
+    reason: string;
+}
+export interface McpDecisionRecord {
+    serverName: string;
+    toolName: string;
+    verdict: McpCoherenceVerdict;
+    riskLevel: McpRiskLevel;
+    capability: McpCapabilityClass;
+    incoherent: boolean;
+    reason: string;
+    profileMode: McpTrustMode;
+    evaluatedAt: number;
+}
+/** Snapshot of a managed MCP server used for attack-path review. */
+export interface McpSecuritySnapshot {
+    /** Server name. */
+    name: string;
+    /** High-level role used for coherence evaluation. */
+    role: McpServerRole;
+    /** Runtime trust mode. */
+    trustMode: McpTrustMode;
+    /** Allowed filesystem scope. */
+    allowedPaths: readonly string[];
+    /** Allowed network host scope. */
+    allowedHosts: readonly string[];
+    /** Current schema freshness state. */
+    schemaFreshness: SchemaFreshness;
+    /** Active quarantine reason when schema execution is blocked. */
+    quarantineReason?: QuarantineReason;
+    /** Human-readable quarantine detail. */
+    quarantineDetail?: string;
+    /** Whether the server is currently connected. */
+    connected?: boolean;
+}
+/** Type of attack-path finding surfaced by the security review. */
+export type McpAttackPathFindingKind = 'server-posture' | 'recent-decision';
+/** Single MCP attack-path finding. */
+export interface McpAttackPathFinding {
+    /** Finding classification. */
+    kind: McpAttackPathFindingKind;
+    /** Related server name. */
+    serverName: string;
+    /** Human-readable route summary. */
+    route: string;
+    /** Allow/ask/deny posture inferred from the review. */
+    verdict: McpCoherenceVerdict;
+    /** Risk level associated with the route. */
+    severity: McpRiskLevel;
+    /** Whether the finding indicates incoherent or suspicious behavior. */
+    incoherent: boolean;
+    /** Human-readable explanation. */
+    reason: string;
+    /** Evidence strings used to derive the finding. */
+    evidence: readonly string[];
+    /** Optional tool name for recent decision findings. */
+    toolName?: string;
+    /** Optional capability class for recent decision findings. */
+    capability?: McpCapabilityClass;
+    /** Optional timestamp for recent decision findings. */
+    evaluatedAt?: number;
+}
+/** Aggregated attack-path review across all MCP servers and recent decisions. */
+export interface McpAttackPathReview {
+    /** Epoch ms when the review was generated. */
+    reviewedAt: number;
+    /** Total server count included in the review. */
+    totalServers: number;
+    /** Connected server count. */
+    connectedServers: number;
+    /** Servers operating in allow-all mode. */
+    allowAllServers: number;
+    /** Servers operating in ask-on-risk mode. */
+    askOnRiskServers: number;
+    /** Servers operating in constrained mode. */
+    constrainedServers: number;
+    /** Servers blocked entirely. */
+    blockedServers: number;
+    /** Servers with quarantined schemas. */
+    quarantinedServers: number;
+    /** Findings with incoherent posture or behavior. */
+    incoherentFindings: number;
+    /** Findings with high or critical severity. */
+    criticalFindings: number;
+    /** Ordered findings, most severe first. */
+    findings: readonly McpAttackPathFinding[];
+    /** Human-readable summary of the review. */
+    summary: string;
+}
+/** Permission verdict for a single tool invocation. */
+export interface McpPermission {
+    /** Whether the tool call is permitted. */
+    allowed: boolean;
+    /** Human-readable explanation for the verdict. */
+    reason: string;
+    /** Richer verdict used by the hardened trust layer. */
+    verdict?: McpCoherenceVerdict;
+    /** Risk associated with the evaluated tool call. */
+    riskLevel?: McpRiskLevel;
+    /** Inferred capability class. */
+    capability?: McpCapabilityClass;
+    /** Whether the request was flagged as incoherent for its server role. */
+    incoherent?: boolean;
+    /** Effective trust mode when the decision was made. */
+    profileMode?: McpTrustMode;
+}
+/** Per-tool permission override stored in a server's permission record. */
+export interface McpToolPermission {
+    /** Tool name on the server (not qualified). */
+    toolName: string;
+    /** Explicit allow or deny override. */
+    verdict: 'allow' | 'deny';
+    /** Optional note recorded when the override was set. */
+    note?: string;
+}
+/** Complete permission configuration for a single MCP server. */
+export interface McpServerPermissions {
+    /** Server name. */
+    serverName: string;
+    /** Overall trust level governing default tool access. */
+    trustLevel: McpTrustLevel;
+    /** Runtime trust profile used by the coherence engine. */
+    profile: McpTrustProfile;
+    /** Explicit per-tool overrides applied after the trust-level default. */
+    toolOverrides: Map<string, McpToolPermission>;
+    /** Epoch ms when permissions were last modified. */
+    lastModifiedAt: number;
+}
+/**
+ * Full runtime entry for a managed MCP server.
+ *
+ * Held by McpLifecycleManager; drives UI, store, and event emission.
+ */
+export interface McpServerEntry {
+    /** Server name (matches McpServerConfig.name). */
+    name: string;
+    /** Original server configuration. */
+    config: McpServerConfig;
+    /** Current lifecycle state. */
+    state: McpServerState;
+    /** Number of reconnect attempts in the current reconnection cycle. */
+    reconnectAttempts: number;
+    /** Epoch ms of the most recent successful connection. */
+    connectedAt?: number;
+    /** Epoch ms of the most recent disconnection. */
+    disconnectedAt?: number;
+    /** Reason for the most recent disconnection or failure. */
+    lastError?: string;
+    /** Whether a reconnect timer is currently scheduled. */
+    reconnectPending: boolean;
+    /** Auth challenge type if state is auth_required. */
+    authType?: string;
+    /** Tools available from this server (populated on connect). */
+    availableTools: string[];
+    /** Resources available from this server (populated on connect). */
+    availableResources: string[];
+    /** Number of tool calls made to this server this session. */
+    callCount: number;
+    /** Number of tool call failures this session. */
+    errorCount: number;
+}
+/** Configuration for the exponential back-off reconnect strategy. */
+export interface McpReconnectConfig {
+    /** Maximum number of reconnect attempts before moving to disconnected. */
+    maxAttempts: number;
+    /** Base delay in ms (doubled each attempt). */
+    baseDelayMs: number;
+    /** Hard ceiling for any single reconnect delay (ms). */
+    maxDelayMs: number;
+}
+/** Default reconnect configuration. */
+export declare const DEFAULT_RECONNECT_CONFIG: McpReconnectConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/runtime/mcp/types.d.ts.map

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

package/dist/platform/runtime/mcp/types.js

@@ -0,0 +1,6 @@
+/** Default reconnect configuration. */
+export const DEFAULT_RECONNECT_CONFIG = {
+    maxAttempts: 5,
+    baseDelayMs: 1_000,
+    maxDelayMs: 30_000,
+};

package/dist/platform/runtime/notifications/formatters/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Notification formatters — barrel export.
+ */
+export { formatNotificationSummary, formatBatchSummary } from './summary.js';
+export { createPanelJumpAction, createDismissAction } from './panel-jump.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/runtime/notifications/formatters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/notifications/formatters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/platform/runtime/notifications/formatters/index.js

@@ -0,0 +1,5 @@
+/**
+ * Notification formatters — barrel export.
+ */
+export { formatNotificationSummary, formatBatchSummary } from './summary.js';
+export { createPanelJumpAction, createDismissAction } from './panel-jump.js';