@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/runtime/permissions/policy-runtime.js

@@ -0,0 +1,121 @@
+import { PolicyRegistry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+import { DivergencePanel } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/panels/divergence';
+import { PolicyPanel as PolicyDiagnosticsPanel } from '../diagnostics/panels/policy.js';
+import { lintPolicyConfig } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+const MAX_PERMISSION_AUDIT = 100;
+export class PolicyRuntimeState {
+    _registry;
+    _dashboard = null;
+    _divergencePanel = null;
+    _recentPermissionAudit = [];
+    _lastSimulationSummary = null;
+    _lastPreflightReview = null;
+    _subscribers = new Set();
+    constructor(registry = new PolicyRegistry()) {
+        this._registry = registry;
+    }
+    getRegistry() {
+        return this._registry;
+    }
+    getDashboard() {
+        return this._dashboard;
+    }
+    getDivergencePanel() {
+        return this._divergencePanel;
+    }
+    setDashboard(dashboard) {
+        this._divergencePanel?.dispose();
+        this._dashboard = dashboard;
+        this._divergencePanel = dashboard ? new DivergencePanel(dashboard) : null;
+        this.notify();
+    }
+    recordTrendEntry() {
+        this._divergencePanel?.recordTrendEntry();
+        this.notify();
+    }
+    getSnapshot() {
+        const current = this._registry.getCurrent();
+        const candidate = this._registry.getCandidate();
+        const lintFindings = [
+            ...(current ? lintPolicyConfig({ mode: 'custom', rules: current.rules }) : []),
+            ...(candidate ? lintPolicyConfig({ mode: 'custom', rules: candidate.rules }) : []),
+        ];
+        const panel = new PolicyDiagnosticsPanel(this._registry, this._divergencePanel, this._recentPermissionAudit, lintFindings, this._lastSimulationSummary, this._lastPreflightReview);
+        return panel.getSnapshot();
+    }
+    recordSimulationSummary(summary) {
+        this._lastSimulationSummary = summary;
+        this.notify();
+    }
+    recordPreflightReview(review) {
+        this._lastPreflightReview = review;
+        this.notify();
+    }
+    recordPermissionRequest(params) {
+        this._upsertPermissionAudit({
+            callId: params.callId,
+            tool: params.tool,
+            category: params.category,
+            riskLevel: params.analysis.riskLevel,
+            classification: params.analysis.classification,
+            summary: params.analysis.summary,
+            reasons: params.analysis.reasons,
+            target: params.analysis.target,
+            host: params.analysis.host,
+            requestedAt: Date.now(),
+        });
+        this.notify();
+    }
+    recordPermissionDecision(params) {
+        this._upsertPermissionAudit({
+            callId: params.callId,
+            tool: params.tool,
+            category: params.category,
+            approved: params.result.approved,
+            sourceLayer: params.result.sourceLayer,
+            reasonCode: params.result.reasonCode,
+            riskLevel: params.result.analysis.riskLevel,
+            classification: params.result.analysis.classification,
+            summary: params.result.analysis.summary,
+            reasons: params.result.analysis.reasons,
+            target: params.result.analysis.target,
+            host: params.result.analysis.host,
+            requestedAt: Date.now(),
+            decidedAt: Date.now(),
+            persisted: params.result.persisted,
+        });
+        this.notify();
+    }
+    subscribe(callback) {
+        this._subscribers.add(callback);
+        return () => {
+            this._subscribers.delete(callback);
+        };
+    }
+    notify() {
+        for (const cb of this._subscribers) {
+            try {
+                cb();
+            }
+            catch {
+                // Panel/runtime subscribers must not break policy state propagation.
+            }
+        }
+    }
+    _upsertPermissionAudit(entry) {
+        const existingIndex = this._recentPermissionAudit.findIndex((candidate) => candidate.callId === entry.callId);
+        if (existingIndex >= 0) {
+            this._recentPermissionAudit[existingIndex] = {
+                ...this._recentPermissionAudit[existingIndex],
+                ...entry,
+                requestedAt: this._recentPermissionAudit[existingIndex].requestedAt,
+            };
+        }
+        else {
+            this._recentPermissionAudit.unshift(entry);
+            if (this._recentPermissionAudit.length > MAX_PERMISSION_AUDIT) {
+                this._recentPermissionAudit.length = MAX_PERMISSION_AUDIT;
+            }
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { GoodVibesConfig, DeepReadonly } from '../../config/index.js';
+import type { PolicyLintFinding } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+import type { McpServerRole, McpTrustMode } from '@pellux/goodvibes-sdk/platform/runtime/mcp/types';
+export type PolicyPreflightStatus = 'pass' | 'warn' | 'block';
+export interface PolicyPreflightServer {
+    readonly serverName: string;
+    readonly trustMode: McpTrustMode;
+    readonly role: McpServerRole;
+    readonly allowedPaths: readonly string[];
+    readonly allowedHosts: readonly string[];
+}
+export interface PolicyPreflightIssue {
+    readonly severity: 'info' | 'warn' | 'error';
+    readonly source: 'policy' | 'runtime' | 'mcp';
+    readonly message: string;
+    readonly detail?: string;
+    readonly serverName?: string;
+}
+export interface PolicyPreflightReview {
+    readonly generatedAt: string;
+    readonly status: PolicyPreflightStatus;
+    readonly summary: string;
+    readonly issueCount: number;
+    readonly issues: readonly PolicyPreflightIssue[];
+}
+export declare function buildPolicyPreflightReview(params: {
+    config: DeepReadonly<GoodVibesConfig>;
+    lintFindings: readonly PolicyLintFinding[];
+    mcpServers: readonly PolicyPreflightServer[];
+}): PolicyPreflightReview;
+//# sourceMappingURL=preflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/preflight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAC;AACjG,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kDAAkD,CAAC;AAEpG,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAcD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;IACtC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC9C,GAAG,qBAAqB,CAsDxB"}

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

@@ -0,0 +1,62 @@
+function summarize(status, issues) {
+    if (issues.length === 0) {
+        return 'No blocking or warning conditions detected for the current policy state.';
+    }
+    const errors = issues.filter((issue) => issue.severity === 'error').length;
+    const warnings = issues.filter((issue) => issue.severity === 'warn').length;
+    if (status === 'block') {
+        return `${errors} blocking issue${errors === 1 ? '' : 's'} and ${warnings} warning${warnings === 1 ? '' : 's'} require attention before high-risk runs.`;
+    }
+    return `${warnings} warning${warnings === 1 ? '' : 's'} detected in the current policy posture.`;
+}
+export function buildPolicyPreflightReview(params) {
+    const issues = [];
+    for (const finding of params.lintFindings) {
+        issues.push({
+            severity: finding.severity === 'error' ? 'error' : finding.severity === 'warn' ? 'warn' : 'info',
+            source: 'policy',
+            message: finding.message,
+            detail: finding.ruleId ? `rule=${finding.ruleId}` : undefined,
+        });
+    }
+    if (params.config.permissions.mode === 'allow-all') {
+        issues.push({
+            severity: 'error',
+            source: 'runtime',
+            message: 'Permission mode is allow-all.',
+            detail: 'All runtime permission checks are bypassed for local tools.',
+        });
+    }
+    for (const server of params.mcpServers) {
+        if (server.trustMode === 'allow-all') {
+            issues.push({
+                severity: 'error',
+                source: 'mcp',
+                serverName: server.serverName,
+                message: `MCP server "${server.serverName}" is in allow-all mode.`,
+                detail: `role=${server.role} paths=${server.allowedPaths.length} hosts=${server.allowedHosts.length}`,
+            });
+        }
+        else if (server.trustMode === 'ask-on-risk') {
+            issues.push({
+                severity: 'warn',
+                source: 'mcp',
+                serverName: server.serverName,
+                message: `MCP server "${server.serverName}" requires approval for risky actions.`,
+                detail: `role=${server.role} paths=${server.allowedPaths.length} hosts=${server.allowedHosts.length}`,
+            });
+        }
+    }
+    const status = issues.some((issue) => issue.severity === 'error')
+        ? 'block'
+        : issues.some((issue) => issue.severity === 'warn')
+            ? 'warn'
+            : 'pass';
+    return {
+        generatedAt: new Date().toISOString(),
+        status,
+        summary: summarize(status, issues),
+        issueCount: issues.length,
+        issues,
+    };
+}

package/dist/_internal/platform/runtime/permissions/rule-suggestions.d.ts

@@ -0,0 +1,10 @@
+import type { PermissionAuditEntry } from './policy-runtime.js';
+export interface PermissionRuleSuggestion {
+    readonly id: string;
+    readonly tool: string;
+    readonly command: string;
+    readonly summary: string;
+    readonly reason: string;
+}
+export declare function buildPermissionRuleSuggestions(audit: readonly PermissionAuditEntry[]): PermissionRuleSuggestion[];
+//# sourceMappingURL=rule-suggestions.d.ts.map

package/dist/_internal/platform/runtime/permissions/rule-suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-suggestions.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/rule-suggestions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,wBAAwB,EAAE,CAuB5B"}

package/dist/_internal/platform/runtime/permissions/rule-suggestions.js

@@ -0,0 +1,24 @@
+export function buildPermissionRuleSuggestions(audit) {
+    const denied = audit.filter((entry) => entry.approved === false);
+    const grouped = new Map();
+    for (const entry of denied) {
+        const key = `${entry.tool}:${entry.target ?? entry.host ?? entry.summary}`;
+        const list = grouped.get(key) ?? [];
+        list.push(entry);
+        grouped.set(key, list);
+    }
+    return [...grouped.entries()]
+        .filter(([, entries]) => entries.length >= 2)
+        .map(([key, entries]) => {
+        const sample = entries[0];
+        const target = sample.target ?? sample.host ?? sample.summary;
+        return {
+            id: key,
+            tool: sample.tool,
+            command: `/policy simulate ${sample.tool}${target ? ` --target ${JSON.stringify(target)}` : ''}`,
+            summary: `Repeated denials for ${sample.tool}`,
+            reason: `${entries.length} denials suggest a durable scoped rule or policy review may be appropriate.`,
+        };
+    })
+        .sort((a, b) => a.tool.localeCompare(b.tool));
+}

package/dist/_internal/platform/runtime/plugins/hot-reload.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Safe hot-reload protocol for plugins.
+ *
+ * Implements the 6-phase hot-reload sequence:
+ *   1. Quiesce   — stop accepting new work from the plugin
+ *   2. Unregister — remove plugin's registrations (commands, tools, hooks)
+ *   3. Unload    — deactivate and clean up the old plugin instance
+ *   4. Reload    — load the new version with a cache-bust timestamp
+ *   5. Re-register — new instance calls init/activate (registers naturally)
+ *   6. Health check → active (healthy) or degraded (unhealthy)
+ */
+import type { PluginLoaderDeps } from '../../plugins/loader.js';
+import type { LoadedPlugin } from '../../plugins/loader.js';
+import type { PluginHealthCheckResult, PluginManifestV2 } from './types.js';
+import type { PluginLifecycleManager } from './manager.js';
+/**
+ * Options for a single plugin hot-reload operation.
+ */
+export interface HotReloadOptions {
+    /**
+     * Callback to retrieve the current loaded plugin instance by name.
+     * Used to call deactivate() and run cleanup before unloading.
+     */
+    getLoadedPlugin: (name: string) => LoadedPlugin | undefined;
+    /**
+     * Callback to remove a plugin's loaded instance from the host's registry.
+     * Called after unload to clean up the host-side reference.
+     */
+    removeLoadedPlugin: (name: string) => void;
+    /**
+     * Callback to store the newly loaded plugin instance in the host's registry.
+     * Called after a successful reload.
+     */
+    storeLoadedPlugin: (name: string, plugin: LoadedPlugin) => void;
+    /**
+     * Optional health check callback invoked after re-registration.
+     * Return a PluginHealthCheckResult to indicate whether the plugin is healthy.
+     * Defaults to a trivial healthy check.
+     */
+    healthCheck?: (name: string) => Promise<PluginHealthCheckResult>;
+    /**
+     * Maximum time (ms) to wait for the health check before timing out.
+     * Defaults to 5000ms.
+     */
+    healthCheckTimeoutMs?: number;
+}
+/**
+ * Result of a hot-reload operation.
+ */
+export interface HotReloadResult {
+    /** Whether the reload completed successfully and the plugin is healthy. */
+    success: boolean;
+    /** Phase that failed (if success === false). */
+    failedPhase?: 'quiesce' | 'unregister' | 'unload' | 'reload' | 're-register' | 'health-check';
+    /** Error message (if success === false). */
+    error?: string;
+    /** Duration of the reload in milliseconds. */
+    durationMs: number;
+    /** Whether the plugin ended in degraded state (partial success). */
+    degraded: boolean;
+}
+/**
+ * runHotReload — Execute the safe 6-phase hot-reload protocol for a single
+ * plugin.
+ *
+ * @param name      - Plugin name.
+ * @param manifest  - Current manifest for the plugin.
+ * @param pluginDir - Absolute path to the plugin directory.
+ * @param deps      - Loader dependencies (runtime bus, registries, etc.).
+ * @param lcm       - PluginLifecycleManager to track state transitions.
+ * @param options   - Host-side callbacks and configuration.
+ * @returns HotReloadResult describing the outcome.
+ */
+export declare function runHotReload(name: string, manifest: PluginManifestV2, pluginDir: string, deps: PluginLoaderDeps, lcm: PluginLifecycleManager, options: HotReloadOptions): Promise<HotReloadResult>;
+//# sourceMappingURL=hot-reload.d.ts.map

package/dist/_internal/platform/runtime/plugins/hot-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-reload.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/plugins/hot-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IAE5D;;;OAGG;IACH,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3C;;;OAGG;IACH,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAEhE;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAEjE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,cAAc,CAAC;IAC9F,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,sBAAsB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAyG1B"}

package/dist/_internal/platform/runtime/plugins/hot-reload.js

@@ -0,0 +1,146 @@
+/**
+ * Safe hot-reload protocol for plugins.
+ *
+ * Implements the 6-phase hot-reload sequence:
+ *   1. Quiesce   — stop accepting new work from the plugin
+ *   2. Unregister — remove plugin's registrations (commands, tools, hooks)
+ *   3. Unload    — deactivate and clean up the old plugin instance
+ *   4. Reload    — load the new version with a cache-bust timestamp
+ *   5. Re-register — new instance calls init/activate (registers naturally)
+ *   6. Health check → active (healthy) or degraded (unhealthy)
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/** Default trivial health check — always returns healthy. */
+async function defaultHealthCheck(name) {
+    return {
+        healthy: true,
+        message: `${name}: health check passed (default)`,
+        durationMs: 0,
+    };
+}
+/**
+ * runHotReload — Execute the safe 6-phase hot-reload protocol for a single
+ * plugin.
+ *
+ * @param name      - Plugin name.
+ * @param manifest  - Current manifest for the plugin.
+ * @param pluginDir - Absolute path to the plugin directory.
+ * @param deps      - Loader dependencies (runtime bus, registries, etc.).
+ * @param lcm       - PluginLifecycleManager to track state transitions.
+ * @param options   - Host-side callbacks and configuration.
+ * @returns HotReloadResult describing the outcome.
+ */
+export async function runHotReload(name, manifest, pluginDir, deps, lcm, options) {
+    const startTs = Date.now();
+    const healthCheck = options.healthCheck ?? defaultHealthCheck;
+    const timeoutMs = options.healthCheckTimeoutMs ?? 5000;
+    const record = lcm.getRecord(name);
+    if (!record) {
+        return {
+            success: false,
+            failedPhase: 'quiesce',
+            error: `Plugin '${name}' is not tracked by the lifecycle manager`,
+            durationMs: Date.now() - startTs,
+            degraded: false,
+        };
+    }
+    logger.info(`[plugin-hot-reload] ${name}: starting hot-reload`);
+    // ── Phase 1: Quiesce ────────────────────────────────────────────────────
+    // Mark the plugin as reloading to signal to callers to defer new work.
+    // (The PluginLifecycleRecord.reloading flag is set, but state is not changed.)
+    // In a future implementation this phase could drain in-flight requests.
+    try {
+        // Access via cast since reloading is a mutable field on the record.
+        const mutableRecord = record;
+        mutableRecord.reloading = true;
+        logger.debug(`[plugin-hot-reload] ${name}: phase 1/6 quiesced`);
+    }
+    catch (err) {
+        return failure('quiesce', summarizeError(err), startTs);
+    }
+    // ── Phase 2: Prepare unregister ──────────────────────────────────────────
+    // The existing plugin's cleanup callbacks handle un-registration during
+    // unload, so there is no separate hook dispatch here.
+    logger.debug(`[plugin-hot-reload] ${name}: phase 2/6 unregister scheduled with unload cleanup`);
+    // ── Phase 3: Unload ─────────────────────────────────────────────────────
+    try {
+        const loaded = options.getLoadedPlugin(name);
+        if (loaded) {
+            const { unloadPlugin } = await import('../../plugins/loader.js');
+            await unloadPlugin(loaded);
+        }
+        options.removeLoadedPlugin(name);
+        logger.debug(`[plugin-hot-reload] ${name}: phase 3/6 unloaded`);
+    }
+    catch (err) {
+        return failure('unload', summarizeError(err), startTs);
+    }
+    // ── Phase 4 + 5: Reload + Re-register ──────────────────────────────────
+    // loadPlugin calls init() and activate() which re-registers everything.
+    let reloadedPlugin = null;
+    try {
+        const { loadPlugin } = await import('../../plugins/loader.js');
+        const cacheBust = Date.now();
+        reloadedPlugin = await loadPlugin({ manifest, pluginDir }, deps, cacheBust);
+        if (!reloadedPlugin) {
+            return failure('reload', 'loadPlugin returned null', startTs);
+        }
+        options.storeLoadedPlugin(name, reloadedPlugin);
+        logger.debug(`[plugin-hot-reload] ${name}: phases 4+5/6 reloaded + re-registered`);
+    }
+    catch (err) {
+        return failure('reload', summarizeError(err), startTs);
+    }
+    // ── Phase 6: Health check ────────────────────────────────────────────────
+    let healthResult;
+    try {
+        healthResult = await Promise.race([
+            healthCheck(name),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`health check timed out after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
+    }
+    catch (err) {
+        healthResult = {
+            healthy: false,
+            message: summarizeError(err),
+            durationMs: Date.now() - startTs,
+        };
+    }
+    // Clear reloading flag.
+    try {
+        const mutableRecord = lcm.getRecord(name);
+        if (mutableRecord)
+            mutableRecord.reloading = false;
+    }
+    catch { /* non-fatal */ }
+    if (healthResult.healthy) {
+        logger.info(`[plugin-hot-reload] ${name}: hot-reload complete — active (${Date.now() - startTs}ms)`);
+        return {
+            success: true,
+            durationMs: Date.now() - startTs,
+            degraded: false,
+        };
+    }
+    else {
+        // Plugin loaded but health check failed → degraded.
+        lcm.degradePlugin(name, `Health check failed: ${healthResult.message}`);
+        logger.warn(`[plugin-hot-reload] ${name}: hot-reload complete — degraded (${healthResult.message})`);
+        return {
+            success: true, // reload succeeded; just in degraded state
+            durationMs: Date.now() - startTs,
+            degraded: true,
+        };
+    }
+}
+/** Build a failure result for a named phase. */
+function failure(phase, error, startTs) {
+    logger.error(`[plugin-hot-reload] phase '${String(phase)}' failed: ${error}`);
+    return {
+        success: false,
+        failedPhase: phase,
+        error,
+        durationMs: Date.now() - startTs,
+        degraded: false,
+    };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Plugin lifecycle system — barrel export and factory.
+ *
+ * Gated by the `plugin-lifecycle` feature flag. Import and call
+ * `createPluginLifecycleManager()` at startup after the feature flag
+ * manager has been initialised.
+ *
+ * @example
+ * ```ts
+ * import { createPluginLifecycleManager } from './src/runtime/plugins/index.js';
+ *
+ * const lcm = createPluginLifecycleManager({ sessionId: session.id, runtimeBus });
+ * lcm.scanAndRegister();
+ * ```
+ */
+export type { PluginCapability, PluginCapabilityManifest, PluginManifestV2, PluginTransition, TransitionResult, PluginHealthCheckResult, PluginLifecycleRecord, PluginLifecycleManagerOptions, PluginLifecycleState, } from './types.js';
+export { ALL_CAPABILITIES, MAX_TRANSITION_HISTORY } from './types.js';
+export { VALID_TRANSITIONS, canTransition, applyTransition, isOperational, isReloadable, isTerminal, } from './lifecycle.js';
+export { resolveCapabilityManifest, hasCapability, validateManifestV2, } from './manifest.js';
+export { PluginLifecycleManager } from './manager.js';
+import { PluginLifecycleManager } from './manager.js';
+export type { PluginTrustTier, PluginTrustRecord, SignatureValidationResult, } from './trust.js';
+export { PluginTrustStore, validatePluginSignature, filterCapabilitiesByTrust, SAFE_CAPABILITIES, } from './trust.js';
+export type { QuarantineRecord } from './quarantine.js';
+export { PluginQuarantineEngine } from './quarantine.js';
+export { isHighRiskCapability } from './manifest.js';
+export type { HotReloadOptions, HotReloadResult } from './hot-reload.js';
+export { runHotReload } from './hot-reload.js';
+/**
+ * createPluginLifecycleManager — Factory function for the PluginLifecycleManager.
+ *
+ * Intended as the primary entry point for consumers. Respects the
+ * `plugin-lifecycle` feature flag — callers should check the flag before
+ * invoking if they want to gate the entire system.
+ *
+ * @param options - Optional manager configuration.
+ * @returns A new PluginLifecycleManager instance.
+ */
+export declare function createPluginLifecycleManager(options?: import('./types.js').PluginLifecycleManagerOptions): PluginLifecycleManager;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,qBAAqB,EACrB,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,aAAa,EACb,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGtD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,OAAO,YAAY,EAAE,6BAAkC,GAC/D,sBAAsB,CAExB"}

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

@@ -0,0 +1,37 @@
+/**
+ * Plugin lifecycle system — barrel export and factory.
+ *
+ * Gated by the `plugin-lifecycle` feature flag. Import and call
+ * `createPluginLifecycleManager()` at startup after the feature flag
+ * manager has been initialised.
+ *
+ * @example
+ * ```ts
+ * import { createPluginLifecycleManager } from './src/runtime/plugins/index.js';
+ *
+ * const lcm = createPluginLifecycleManager({ sessionId: session.id, runtimeBus });
+ * lcm.scanAndRegister();
+ * ```
+ */
+export { ALL_CAPABILITIES, MAX_TRANSITION_HISTORY } from './types.js';
+export { VALID_TRANSITIONS, canTransition, applyTransition, isOperational, isReloadable, isTerminal, } from './lifecycle.js';
+export { resolveCapabilityManifest, hasCapability, validateManifestV2, } from './manifest.js';
+export { PluginLifecycleManager } from './manager.js';
+import { PluginLifecycleManager } from './manager.js';
+export { PluginTrustStore, validatePluginSignature, filterCapabilitiesByTrust, SAFE_CAPABILITIES, } from './trust.js';
+export { PluginQuarantineEngine } from './quarantine.js';
+export { isHighRiskCapability } from './manifest.js';
+export { runHotReload } from './hot-reload.js';
+/**
+ * createPluginLifecycleManager — Factory function for the PluginLifecycleManager.
+ *
+ * Intended as the primary entry point for consumers. Respects the
+ * `plugin-lifecycle` feature flag — callers should check the flag before
+ * invoking if they want to gate the entire system.
+ *
+ * @param options - Optional manager configuration.
+ * @returns A new PluginLifecycleManager instance.
+ */
+export function createPluginLifecycleManager(options = {}) {
+    return new PluginLifecycleManager(options);
+}

package/dist/_internal/platform/runtime/plugins/lifecycle.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Plugin lifecycle state machine.
+ *
+ * Defines the valid state transitions for the 8-state plugin lifecycle
+ * and provides pure guard/transition functions with no side effects.
+ *
+ * States:
+ *   discovered → loading → loaded → active ↔ degraded
+ *                                          ↓
+ *                                        error → (unloading | disabled)
+ *                    active/loaded/degraded/error → unloading → disabled
+ *                    any → error (non-fatal)
+ *                    disabled → loading (re-enable)
+ */
+import type { PluginLifecycleState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/plugins';
+import type { TransitionResult } from './types.js';
+/**
+ * Adjacency map: from state → set of valid target states.
+ *
+ * Encoded as a plain Record so it is safe to evaluate at module load time
+ * with no external dependencies.
+ */
+export declare const VALID_TRANSITIONS: Readonly<Record<PluginLifecycleState, ReadonlyArray<PluginLifecycleState>>>;
+/**
+ * Returns whether a transition from `from` → `to` is permitted by the
+ * state machine.
+ */
+export declare function canTransition(from: PluginLifecycleState, to: PluginLifecycleState): boolean;
+/**
+ * Attempts a state transition and returns a typed result.
+ *
+ * This is a pure function — it has no side effects. The caller is responsible
+ * for updating the plugin record and emitting events.
+ *
+ * @param from - Current state.
+ * @param to   - Desired target state.
+ * @returns `{ ok: true, from, to }` on success or `{ ok: false, reason }` on
+ *          invalid transition.
+ */
+export declare function applyTransition(from: PluginLifecycleState, to: PluginLifecycleState): TransitionResult;
+/**
+ * Returns whether a plugin in the given state is considered "operational"
+ * (i.e. actively servicing requests, possibly in a degraded capacity).
+ */
+export declare function isOperational(state: PluginLifecycleState): boolean;
+/**
+ * Returns whether a plugin in the given state can be safely hot-reloaded.
+ * A hot reload requires the plugin to be quiesceable.
+ */
+export declare function isReloadable(state: PluginLifecycleState): boolean;
+/**
+ * Returns whether the plugin's current state represents a terminal failure
+ * that requires operator intervention (disabled or persistent error).
+ */
+export declare function isTerminal(state: PluginLifecycleState): boolean;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/_internal/platform/runtime/plugins/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/plugins/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACzG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CACtC,MAAM,CAAC,oBAAoB,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAUzD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,oBAAoB,EAC1B,EAAE,EAAE,oBAAoB,GACvB,OAAO,CAET;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,oBAAoB,EAC1B,EAAE,EAAE,oBAAoB,GACvB,gBAAgB,CAQlB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAElE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAEjE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAE/D"}