@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/runtime/mcp/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * src/runtime/mcp — MCP lifecycle barrel.
+ *
+ * Gated by the `mcp-lifecycle` feature flag.
+ *
+ * Public API:
+ *   - `createMcpLifecycleManager()` — factory function
+ *   - All types from types.ts
+ *   - State machine helpers from lifecycle.ts
+ *   - Permission manager from permissions.ts
+ *   - Schema freshness tracker from schema-freshness.ts
+ *   - Manager from manager.ts
+ */
+export { McpLifecycleManager, type McpEventHandler, type McpLifecycleManagerOptions } from './manager.js';
+export { McpPermissionManager, buildMcpAttackPathReview } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+export { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+export { canTransition, reachableFrom, applyTransition, isOperational, isTerminal, type TransitionResult, } from '@pellux/goodvibes-sdk/platform/runtime/mcp/lifecycle';
+export type { McpServerState, SchemaFreshness, McpSchemaRecord, QuarantineReason, QuarantineRecord, McpTrustLevel, McpTrustMode, McpServerRole, McpCapabilityClass, McpCoherenceVerdict, McpRiskLevel, McpPermission, McpTrustProfile, McpCoherenceAssessment, McpDecisionRecord, McpSecuritySnapshot, McpAttackPathFindingKind, McpAttackPathFinding, McpAttackPathReview, McpToolPermission, McpServerPermissions, McpServerEntry, McpReconnectConfig, } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+export { DEFAULT_RECONNECT_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+import { McpLifecycleManager } from './manager.js';
+import type { McpLifecycleManagerOptions } from './manager.js';
+/**
+ * Factory function for creating a `McpLifecycleManager`.
+ *
+ * Check the `mcp-lifecycle` feature flag before calling this — when the
+ * flag is disabled, the caller should use the standard MCP registry path.
+ *
+ * @param options - Optional configuration overrides
+ */
+export declare function createMcpLifecycleManager(options?: McpLifecycleManagerOptions): McpLifecycleManager;
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,KAAK,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1G,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,wDAAwD,CAAC;AACxH,OAAO,EAAE,yBAAyB,EAAE,MAAM,6DAA6D,CAAC;AACxG,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,KAAK,gBAAgB,GACtB,MAAM,sDAAsD,CAAC;AAC9D,YAAY,EACV,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GACnB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,kDAAkD,CAAC;AAE5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,CAErB"}

package/dist/_internal/platform/runtime/mcp/index.js

@@ -0,0 +1,30 @@
+/**
+ * src/runtime/mcp — MCP lifecycle barrel.
+ *
+ * Gated by the `mcp-lifecycle` feature flag.
+ *
+ * Public API:
+ *   - `createMcpLifecycleManager()` — factory function
+ *   - All types from types.ts
+ *   - State machine helpers from lifecycle.ts
+ *   - Permission manager from permissions.ts
+ *   - Schema freshness tracker from schema-freshness.ts
+ *   - Manager from manager.ts
+ */
+export { McpLifecycleManager } from './manager.js';
+export { McpPermissionManager, buildMcpAttackPathReview } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+export { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+export { canTransition, reachableFrom, applyTransition, isOperational, isTerminal, } from '@pellux/goodvibes-sdk/platform/runtime/mcp/lifecycle';
+export { DEFAULT_RECONNECT_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+import { McpLifecycleManager } from './manager.js';
+/**
+ * Factory function for creating a `McpLifecycleManager`.
+ *
+ * Check the `mcp-lifecycle` feature flag before calling this — when the
+ * flag is disabled, the caller should use the standard MCP registry path.
+ *
+ * @param options - Optional configuration overrides
+ */
+export function createMcpLifecycleManager(options) {
+    return new McpLifecycleManager(options);
+}

package/dist/_internal/platform/runtime/mcp/manager.d.ts

@@ -0,0 +1,158 @@
+import type { McpServerConfig } from '@pellux/goodvibes-sdk/platform/mcp/config';
+import type { McpEvent } from '@pellux/goodvibes-sdk/platform/runtime/events/mcp';
+import type { McpServerState, McpServerEntry, McpReconnectConfig, McpTrustLevel, McpPermission, SchemaFreshness, QuarantineReason, McpTrustMode, McpServerRole, McpServerPermissions } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+/** Callback type for state-change notifications. */
+export type McpEventHandler = (event: McpEvent) => void;
+/** Options for constructing a McpLifecycleManager. */
+export interface McpLifecycleManagerOptions {
+    /** Reconnect back-off configuration. Defaults to DEFAULT_RECONNECT_CONFIG. */
+    reconnect?: Partial<McpReconnectConfig>;
+    /** Schema freshness TTL in ms. Defaults to 5 minutes. */
+    schemaTtlMs?: number;
+}
+/**
+ * McpLifecycleManager — manages the full lifecycle of all configured MCP servers.
+ *
+ * Usage:
+ * ```ts
+ * const mgr = createMcpLifecycleManager();
+ * mgr.onEvent((e) => store.dispatch(e));
+ * await mgr.startAll(configs);
+ * // ...
+ * await mgr.stopAll();
+ * ```
+ */
+export declare class McpLifecycleManager {
+    private readonly servers;
+    private readonly clients;
+    private readonly permissions;
+    private readonly freshness;
+    private readonly reconnectConfig;
+    private readonly eventHandlers;
+    private readonly reconnectTimers;
+    constructor(options?: McpLifecycleManagerOptions);
+    /**
+     * Register an event handler called on every lifecycle transition.
+     *
+     * @param handler - Callback receiving McpEvent on each transition
+     */
+    onEvent(handler: McpEventHandler): void;
+    /**
+     * Register and start all provided server configs.
+     *
+     * Connection errors on individual servers are logged but do not abort the
+     * overall startup.
+     *
+     * @param configs - Array of server configurations to start
+     */
+    startAll(configs: McpServerConfig[]): Promise<void>;
+    /**
+     * Register and start a single server.
+     *
+     * @param config - Server configuration
+     */
+    startServer(config: McpServerConfig): Promise<void>;
+    /**
+     * Disconnect all servers and cancel pending reconnect timers.
+     */
+    stopAll(): Promise<void>;
+    /**
+     * Disconnect a single server by name.
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Optional reason for disconnection
+     */
+    stopServer(serverName: string, reason?: string): Promise<void>;
+    /**
+     * Check whether a tool call is permitted for the given server.
+     *
+     * Quarantined schemas unconditionally block execution — the freshness check
+     * runs before the permission check so a quarantined schema cannot be bypassed
+     * by a permissive trust level.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name on the server (not qualified)
+     */
+    isToolAllowed(serverName: string, toolName: string): McpPermission;
+    /**
+     * Update the trust level for a server.
+     *
+     * @param serverName - Server identifier
+     * @param level      - New trust level
+     */
+    setTrustLevel(serverName: string, level: McpTrustLevel): void;
+    setTrustMode(serverName: string, mode: McpTrustMode): void;
+    setServerRole(serverName: string, role: McpServerRole): void;
+    /**
+     * Explicitly allow a tool for a server.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name
+     * @param note       - Optional note
+     */
+    allowTool(serverName: string, toolName: string, note?: string): void;
+    /**
+     * Explicitly deny a tool for a server.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name
+     * @param note       - Optional note
+     */
+    denyTool(serverName: string, toolName: string, note?: string): void;
+    getServerPermissions(serverName: string): McpServerPermissions | null;
+    listTrustProfiles(): Array<McpServerPermissions['profile']>;
+    /**
+     * Return the schema freshness for a server.
+     *
+     * @param serverName - Server identifier
+     */
+    getSchemaFreshness(serverName: string): SchemaFreshness;
+    /**
+     * Returns `true` if the server's schema is quarantined.
+     *
+     * When quarantined, `isToolAllowed` will block all tool execution until the
+     * schema is refreshed (`markFresh` via a successful schema fetch) or an
+     * operator approves a temporary override via `approveSchemaQuarantine`.
+     *
+     * @param serverName - Server identifier
+     */
+    isSchemaQuarantined(serverName: string): boolean;
+    /**
+     * Manually quarantine a server's schema.
+     *
+     * Intended for operator-initiated quarantine (e.g. after detecting schema
+     * incompatibility). Emits `MCP_SCHEMA_QUARANTINED`.
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Why quarantine is being applied
+     * @param detail     - Optional detail for the MCP panel display
+     */
+    quarantineSchema(serverName: string, reason: QuarantineReason, detail?: string): void;
+    /**
+     * Operator override: approve a quarantined schema so tool execution can
+     * proceed temporarily without a full schema refresh.
+     *
+     * The quarantine record is preserved for audit purposes. Freshness transitions
+     * to `stale`. Emits `MCP_SCHEMA_QUARANTINE_APPROVED`.
+     *
+     * @param serverName - Server identifier
+     * @param operatorId - Identifier of the approving operator
+     */
+    approveSchemaQuarantine(serverName: string, operatorId: string): void;
+    /** Return the current lifecycle state for a server, or `null` if unknown. */
+    getState(serverName: string): McpServerState | null;
+    /** Return all server entries as a read-only snapshot. */
+    getServers(): ReadonlyMap<string, McpServerEntry>;
+    /** Return the entry for a single server, or `null`. */
+    getServer(serverName: string): McpServerEntry | null;
+    /** Names of all servers currently in an operational state (connected/degraded). */
+    get operationalServerNames(): string[];
+    private _startServer;
+    private _connect;
+    private _stopServer;
+    private _scheduleReconnect;
+    private _cancelReconnect;
+    private _setState;
+    private _emit;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/_internal/platform/runtime/mcp/manager.d.ts.map

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

package/dist/_internal/platform/runtime/mcp/manager.js

@@ -0,0 +1,422 @@
+/**
+ * McpLifecycleManager — drives the MCP server state machine.
+ *
+ * Gated by the `mcp-lifecycle` feature flag. When the flag is disabled
+ * callers should use the standard MCP registry path instead.
+ *
+ * Responsibilities:
+ *   - Track per-server McpServerEntry state
+ *   - Orchestrate McpClient connect/disconnect
+ *   - Drive lifecycle state transitions via lifecycle.ts
+ *   - Emit McpEvent on every transition
+ *   - Schedule reconnects with exponential back-off
+ *   - Delegate permission checks to McpPermissionManager
+ *   - Delegate schema freshness to McpSchemaFreshnessTracker
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { McpClient } from '../../mcp/client.js';
+import { applyTransition, isOperational, } from '@pellux/goodvibes-sdk/platform/runtime/mcp/lifecycle';
+import { McpPermissionManager } from '@pellux/goodvibes-sdk/platform/runtime/mcp/permissions';
+import { McpSchemaFreshnessTracker } from '@pellux/goodvibes-sdk/platform/runtime/mcp/schema-freshness';
+import { DEFAULT_RECONNECT_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+// ── Manager ───────────────────────────────────────────────────────────────────
+/**
+ * McpLifecycleManager — manages the full lifecycle of all configured MCP servers.
+ *
+ * Usage:
+ * ```ts
+ * const mgr = createMcpLifecycleManager();
+ * mgr.onEvent((e) => store.dispatch(e));
+ * await mgr.startAll(configs);
+ * // ...
+ * await mgr.stopAll();
+ * ```
+ */
+export class McpLifecycleManager {
+    servers = new Map();
+    clients = new Map();
+    permissions;
+    freshness;
+    reconnectConfig;
+    eventHandlers = [];
+    reconnectTimers = new Map();
+    constructor(options = {}) {
+        this.reconnectConfig = {
+            ...DEFAULT_RECONNECT_CONFIG,
+            ...options.reconnect,
+        };
+        this.permissions = new McpPermissionManager();
+        this.freshness = new McpSchemaFreshnessTracker(options.schemaTtlMs);
+    }
+    // ── Event subscription ────────────────────────────────────────────────────
+    /**
+     * Register an event handler called on every lifecycle transition.
+     *
+     * @param handler - Callback receiving McpEvent on each transition
+     */
+    onEvent(handler) {
+        this.eventHandlers.push(handler);
+    }
+    // ── Server management ─────────────────────────────────────────────────────
+    /**
+     * Register and start all provided server configs.
+     *
+     * Connection errors on individual servers are logged but do not abort the
+     * overall startup.
+     *
+     * @param configs - Array of server configurations to start
+     */
+    async startAll(configs) {
+        await Promise.allSettled(configs.map((c) => this._startServer(c)));
+    }
+    /**
+     * Register and start a single server.
+     *
+     * @param config - Server configuration
+     */
+    async startServer(config) {
+        await this._startServer(config);
+    }
+    /**
+     * Disconnect all servers and cancel pending reconnect timers.
+     */
+    async stopAll() {
+        const names = Array.from(this.servers.keys());
+        await Promise.allSettled(names.map((n) => this._stopServer(n, 'stopAll called')));
+    }
+    /**
+     * Disconnect a single server by name.
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Optional reason for disconnection
+     */
+    async stopServer(serverName, reason) {
+        await this._stopServer(serverName, reason);
+    }
+    // ── Permission delegation ─────────────────────────────────────────────────
+    /**
+     * Check whether a tool call is permitted for the given server.
+     *
+     * Quarantined schemas unconditionally block execution — the freshness check
+     * runs before the permission check so a quarantined schema cannot be bypassed
+     * by a permissive trust level.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name on the server (not qualified)
+     */
+    isToolAllowed(serverName, toolName) {
+        if (this.freshness.isQuarantined(serverName)) {
+            const record = this.freshness.getRecord(serverName);
+            const detail = record?.quarantine?.detail ?? 'schema is quarantined';
+            return {
+                allowed: false,
+                reason: `Schema quarantined (${record?.quarantine?.reason ?? 'unknown'}): ${detail}. Refresh schema or request operator approval to proceed.`,
+            };
+        }
+        return this.permissions.isToolAllowed(serverName, toolName);
+    }
+    /**
+     * Update the trust level for a server.
+     *
+     * @param serverName - Server identifier
+     * @param level      - New trust level
+     */
+    setTrustLevel(serverName, level) {
+        this.permissions.setTrustLevel(serverName, level);
+    }
+    setTrustMode(serverName, mode) {
+        this.permissions.setTrustMode(serverName, mode);
+    }
+    setServerRole(serverName, role) {
+        this.permissions.setServerRole(serverName, role);
+    }
+    /**
+     * Explicitly allow a tool for a server.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name
+     * @param note       - Optional note
+     */
+    allowTool(serverName, toolName, note) {
+        this.permissions.allowTool(serverName, toolName, note);
+    }
+    /**
+     * Explicitly deny a tool for a server.
+     *
+     * @param serverName - Server identifier
+     * @param toolName   - Tool name
+     * @param note       - Optional note
+     */
+    denyTool(serverName, toolName, note) {
+        this.permissions.denyTool(serverName, toolName, note);
+    }
+    getServerPermissions(serverName) {
+        return this.permissions.getServerPermissions(serverName);
+    }
+    listTrustProfiles() {
+        return this.permissions.listProfiles();
+    }
+    // ── Schema freshness ──────────────────────────────────────────────────────
+    /**
+     * Return the schema freshness for a server.
+     *
+     * @param serverName - Server identifier
+     */
+    getSchemaFreshness(serverName) {
+        return this.freshness.getFreshness(serverName);
+    }
+    /**
+     * Returns `true` if the server's schema is quarantined.
+     *
+     * When quarantined, `isToolAllowed` will block all tool execution until the
+     * schema is refreshed (`markFresh` via a successful schema fetch) or an
+     * operator approves a temporary override via `approveSchemaQuarantine`.
+     *
+     * @param serverName - Server identifier
+     */
+    isSchemaQuarantined(serverName) {
+        return this.freshness.isQuarantined(serverName);
+    }
+    /**
+     * Manually quarantine a server's schema.
+     *
+     * Intended for operator-initiated quarantine (e.g. after detecting schema
+     * incompatibility). Emits `MCP_SCHEMA_QUARANTINED`.
+     *
+     * @param serverName - Server identifier
+     * @param reason     - Why quarantine is being applied
+     * @param detail     - Optional detail for the MCP panel display
+     */
+    quarantineSchema(serverName, reason, detail) {
+        this.freshness.markQuarantined(serverName, reason, detail);
+        this._emit({
+            type: 'MCP_SCHEMA_QUARANTINED',
+            serverId: serverName,
+            reason,
+            detail,
+        });
+        logger.warn('McpLifecycleManager: schema quarantined', { server: serverName, reason, detail });
+    }
+    /**
+     * Operator override: approve a quarantined schema so tool execution can
+     * proceed temporarily without a full schema refresh.
+     *
+     * The quarantine record is preserved for audit purposes. Freshness transitions
+     * to `stale`. Emits `MCP_SCHEMA_QUARANTINE_APPROVED`.
+     *
+     * @param serverName - Server identifier
+     * @param operatorId - Identifier of the approving operator
+     */
+    approveSchemaQuarantine(serverName, operatorId) {
+        if (!this.freshness.isQuarantined(serverName)) {
+            logger.debug('McpLifecycleManager: approveSchemaQuarantine called but not quarantined', { server: serverName });
+            return;
+        }
+        this.freshness.approveQuarantine(serverName, operatorId);
+        this._emit({
+            type: 'MCP_SCHEMA_QUARANTINE_APPROVED',
+            serverId: serverName,
+            operatorId,
+        });
+        logger.warn('McpLifecycleManager: quarantine override approved', { server: serverName, operatorId });
+    }
+    // ── Inspection ────────────────────────────────────────────────────────────
+    /** Return the current lifecycle state for a server, or `null` if unknown. */
+    getState(serverName) {
+        return this.servers.get(serverName)?.state ?? null;
+    }
+    /** Return all server entries as a read-only snapshot. */
+    getServers() {
+        return this.servers;
+    }
+    /** Return the entry for a single server, or `null`. */
+    getServer(serverName) {
+        return this.servers.get(serverName) ?? null;
+    }
+    /** Names of all servers currently in an operational state (connected/degraded). */
+    get operationalServerNames() {
+        return Array.from(this.servers.entries())
+            .filter(([, entry]) => isOperational(entry.state))
+            .map(([name]) => name);
+    }
+    // ── Private: start ────────────────────────────────────────────────────────
+    async _startServer(config) {
+        const { name } = config;
+        if (this.servers.has(name)) {
+            logger.info('McpLifecycleManager: server already registered', { name });
+            return;
+        }
+        // Register in subsystems
+        this.permissions.registerServer(name, 'standard', {
+            role: config.role ?? 'general',
+            mode: config.trustMode ?? 'ask-on-risk',
+            allowedPaths: config.allowedPaths ?? [],
+            allowedHosts: config.allowedHosts ?? [],
+        });
+        this.freshness.registerServer(name);
+        // Create entry in configured state
+        const entry = {
+            name,
+            config,
+            state: 'configured',
+            reconnectAttempts: 0,
+            reconnectPending: false,
+            availableTools: [],
+            availableResources: [],
+            callCount: 0,
+            errorCount: 0,
+        };
+        this.servers.set(name, entry);
+        this._emit({ type: 'MCP_CONFIGURED', serverId: name, transport: 'stdio' });
+        // Begin connection attempt
+        await this._connect(name);
+    }
+    async _connect(serverName) {
+        const entry = this.servers.get(serverName);
+        if (!entry)
+            return;
+        const toConnecting = applyTransition(entry.state, 'connecting');
+        if (!toConnecting.success) {
+            logger.debug('McpLifecycleManager: cannot transition to connecting', {
+                server: serverName,
+                reason: toConnecting.reason,
+            });
+            return;
+        }
+        this._setState(entry, 'connecting');
+        this._emit({ type: 'MCP_CONNECTING', serverId: serverName });
+        try {
+            const client = new McpClient(entry.config);
+            await client.connect();
+            this.clients.set(serverName, client);
+            // Load tool list
+            const tools = await client.listTools().catch((err) => {
+                logger.debug('McpLifecycleManager: listTools failed', { server: serverName, err: summarizeError(err) });
+                return [];
+            });
+            entry.availableTools = tools.map((t) => t.name);
+            entry.connectedAt = Date.now();
+            entry.reconnectAttempts = 0;
+            entry.reconnectPending = false;
+            this._setState(entry, 'connected');
+            this.freshness.markStale(serverName); // invalidate on (re)connect
+            this._emit({
+                type: 'MCP_CONNECTED',
+                serverId: serverName,
+                toolCount: entry.availableTools.length,
+                resourceCount: entry.availableResources.length,
+            });
+            logger.info('McpLifecycleManager: server connected', {
+                server: serverName,
+                tools: entry.availableTools.length,
+            });
+        }
+        catch (err) {
+            const message = summarizeError(err);
+            entry.lastError = message;
+            logger.error('McpLifecycleManager: connection failed', { server: serverName, err: message });
+            this._scheduleReconnect(serverName);
+        }
+    }
+    // ── Private: stop ─────────────────────────────────────────────────────────
+    async _stopServer(serverName, reason) {
+        this._cancelReconnect(serverName);
+        const entry = this.servers.get(serverName);
+        if (!entry)
+            return;
+        const client = this.clients.get(serverName);
+        if (client) {
+            try {
+                await client.disconnect();
+            }
+            catch (err) {
+                // Non-fatal — we are stopping regardless
+                logger.debug('McpLifecycleManager: disconnect error (suppressed)', { server: serverName, err: summarizeError(err) });
+            }
+            this.clients.delete(serverName);
+        }
+        entry.disconnectedAt = Date.now();
+        entry.lastError = reason;
+        this._setState(entry, 'disconnected');
+        this._emit({ type: 'MCP_DISCONNECTED', serverId: serverName, reason, willRetry: false });
+    }
+    // ── Private: reconnect ────────────────────────────────────────────────────
+    _scheduleReconnect(serverName) {
+        const entry = this.servers.get(serverName);
+        if (!entry)
+            return;
+        if (entry.reconnectAttempts >= this.reconnectConfig.maxAttempts) {
+            logger.info('McpLifecycleManager: max reconnect attempts reached', {
+                server: serverName,
+                attempts: entry.reconnectAttempts,
+            });
+            entry.disconnectedAt = Date.now();
+            this._setState(entry, 'disconnected');
+            this._emit({
+                type: 'MCP_DISCONNECTED',
+                serverId: serverName,
+                reason: `max reconnect attempts (${this.reconnectConfig.maxAttempts}) exceeded`,
+                willRetry: false,
+            });
+            return;
+        }
+        const attempt = entry.reconnectAttempts + 1;
+        const delay = Math.min(this.reconnectConfig.baseDelayMs * Math.pow(2, attempt - 1), this.reconnectConfig.maxDelayMs);
+        this._setState(entry, 'reconnecting');
+        entry.reconnectPending = true;
+        entry.reconnectAttempts = attempt;
+        this._emit({
+            type: 'MCP_RECONNECTING',
+            serverId: serverName,
+            attempt,
+            maxAttempts: this.reconnectConfig.maxAttempts,
+        });
+        logger.info('McpLifecycleManager: scheduling reconnect', { server: serverName, attempt, delayMs: delay });
+        const timer = setTimeout(() => {
+            this.reconnectTimers.delete(serverName);
+            const current = this.servers.get(serverName);
+            if (!current || current.state !== 'reconnecting')
+                return;
+            current.reconnectPending = false;
+            void this._connect(serverName);
+        }, delay);
+        this.reconnectTimers.set(serverName, timer);
+    }
+    _cancelReconnect(serverName) {
+        const timer = this.reconnectTimers.get(serverName);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.reconnectTimers.delete(serverName);
+            const entry = this.servers.get(serverName);
+            if (entry)
+                entry.reconnectPending = false;
+        }
+    }
+    // ── Private: state helpers ────────────────────────────────────────────────
+    _setState(entry, next) {
+        const result = applyTransition(entry.state, next);
+        if (!result.success) {
+            logger.debug('McpLifecycleManager: invalid transition (ignored)', {
+                server: entry.name,
+                from: entry.state,
+                to: next,
+                reason: result.reason,
+            });
+            return;
+        }
+        entry.state = next;
+    }
+    // ── Private: event emission ───────────────────────────────────────────────
+    _emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                // Non-fatal: handler errors must not crash the manager
+                logger.debug('McpLifecycleManager: event handler threw', { event: event.type, err: summarizeError(err) });
+            }
+        }
+    }
+}

package/dist/_internal/platform/runtime/network/inbound.d.ts

@@ -0,0 +1,27 @@
+import type { ConfigManager } from '../../config/manager.js';
+export type InboundTlsMode = 'off' | 'proxy' | 'direct';
+export type InboundServerSurface = 'controlPlane' | 'httpListener';
+export interface InboundTlsSnapshot {
+    readonly surface: InboundServerSurface;
+    readonly host: string;
+    readonly port: number;
+    readonly mode: InboundTlsMode;
+    readonly scheme: 'http' | 'https';
+    readonly trustProxy: boolean;
+    readonly certFile?: string;
+    readonly keyFile?: string;
+    readonly usingDefaultPaths: boolean;
+    readonly ready: boolean;
+    readonly errors: readonly string[];
+    readonly keyPermissions?: {
+        readonly available: boolean;
+        readonly safe?: boolean;
+        readonly mode?: string;
+    };
+}
+export interface ResolvedInboundTlsContext extends InboundTlsSnapshot {
+    readonly tls?: Bun.TLSOptions;
+}
+export declare function inspectInboundTls(configManager: ConfigManager, surface: InboundServerSurface): InboundTlsSnapshot;
+export declare function resolveInboundTlsContext(configManager: ConfigManager, surface: InboundServerSurface): ResolvedInboundTlsContext;
+//# sourceMappingURL=inbound.d.ts.map