@pellux/goodvibes-tui 0.18.4

package/src/runtime/permissions/policy-runtime.ts

@@ -0,0 +1,175 @@
+import { PolicyRegistry } from '@pellux/goodvibes-sdk/platform/runtime/permissions/policy-registry';
+import { DivergencePanel } from '@pellux/goodvibes-sdk/platform/runtime/diagnostics/panels/divergence';
+import type { PolicyPanelSnapshot } from '../diagnostics/panels/policy.ts';
+import { PolicyPanel as PolicyDiagnosticsPanel } from '../diagnostics/panels/policy.ts';
+import type { DivergenceDashboard } from '@pellux/goodvibes-sdk/platform/runtime/permissions/divergence-dashboard';
+import type { PermissionCheckResult } from '@pellux/goodvibes-sdk/platform/permissions/types';
+import { lintPolicyConfig } from '@pellux/goodvibes-sdk/platform/runtime/permissions/lint';
+import type { PolicySimulationSummary } from '@pellux/goodvibes-sdk/platform/runtime/permissions/simulation-scenarios';
+import type { PolicyPreflightReview } from './preflight.ts';
+
+const MAX_PERMISSION_AUDIT = 100;
+
+export interface PermissionAuditEntry {
+  readonly callId: string;
+  readonly tool: string;
+  readonly category: string;
+  readonly approved?: boolean;
+  readonly sourceLayer?: string;
+  readonly reasonCode?: string;
+  readonly riskLevel: string;
+  readonly classification: string;
+  readonly summary: string;
+  readonly reasons: readonly string[];
+  readonly target?: string;
+  readonly host?: string;
+  readonly requestedAt: number;
+  readonly decidedAt?: number;
+  readonly persisted?: boolean;
+}
+
+export class PolicyRuntimeState {
+  private readonly _registry: PolicyRegistry;
+  private _dashboard: DivergenceDashboard | null = null;
+  private _divergencePanel: DivergencePanel | null = null;
+  private readonly _recentPermissionAudit: PermissionAuditEntry[] = [];
+  private _lastSimulationSummary: PolicySimulationSummary | null = null;
+  private _lastPreflightReview: PolicyPreflightReview | null = null;
+  private readonly _subscribers = new Set<() => void>();
+
+  public constructor(registry: PolicyRegistry = new PolicyRegistry()) {
+    this._registry = registry;
+  }
+
+  public getRegistry(): PolicyRegistry {
+    return this._registry;
+  }
+
+  public getDashboard(): DivergenceDashboard | null {
+    return this._dashboard;
+  }
+
+  public getDivergencePanel(): DivergencePanel | null {
+    return this._divergencePanel;
+  }
+
+  public setDashboard(dashboard: DivergenceDashboard | null): void {
+    this._divergencePanel?.dispose();
+    this._dashboard = dashboard;
+    this._divergencePanel = dashboard ? new DivergencePanel(dashboard) : null;
+    this.notify();
+  }
+
+  public recordTrendEntry(): void {
+    this._divergencePanel?.recordTrendEntry();
+    this.notify();
+  }
+
+  public getSnapshot(): PolicyPanelSnapshot {
+    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();
+  }
+
+  public recordSimulationSummary(summary: PolicySimulationSummary): void {
+    this._lastSimulationSummary = summary;
+    this.notify();
+  }
+
+  public recordPreflightReview(review: PolicyPreflightReview): void {
+    this._lastPreflightReview = review;
+    this.notify();
+  }
+
+  public recordPermissionRequest(params: {
+    callId: string;
+    tool: string;
+    category: string;
+    analysis: PermissionCheckResult['analysis'];
+  }): void {
+    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();
+  }
+
+  public recordPermissionDecision(params: {
+    callId: string;
+    tool: string;
+    category: string;
+    result: PermissionCheckResult;
+  }): void {
+    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();
+  }
+
+  public subscribe(callback: () => void): () => void {
+    this._subscribers.add(callback);
+    return () => {
+      this._subscribers.delete(callback);
+    };
+  }
+
+  public notify(): void {
+    for (const cb of this._subscribers) {
+      try {
+        cb();
+      } catch {
+        // Panel/runtime subscribers must not break policy state propagation.
+      }
+    }
+  }
+
+  private _upsertPermissionAudit(entry: PermissionAuditEntry): void {
+    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/src/runtime/permissions/preflight.ts

@@ -0,0 +1,101 @@
+import type { GoodVibesConfig, DeepReadonly } from '../../config/index.ts';
+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[];
+}
+
+function summarize(status: PolicyPreflightStatus, issues: readonly PolicyPreflightIssue[]): string {
+  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: {
+  config: DeepReadonly<GoodVibesConfig>;
+  lintFindings: readonly PolicyLintFinding[];
+  mcpServers: readonly PolicyPreflightServer[];
+}): PolicyPreflightReview {
+  const issues: PolicyPreflightIssue[] = [];
+
+  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: PolicyPreflightStatus = 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/src/runtime/permissions/rule-suggestions.ts

@@ -0,0 +1,36 @@
+import type { PermissionAuditEntry } from './policy-runtime.ts';
+
+export interface PermissionRuleSuggestion {
+  readonly id: string;
+  readonly tool: string;
+  readonly command: string;
+  readonly summary: string;
+  readonly reason: string;
+}
+
+export function buildPermissionRuleSuggestions(
+  audit: readonly PermissionAuditEntry[],
+): PermissionRuleSuggestion[] {
+  const denied = audit.filter((entry) => entry.approved === false);
+  const grouped = new Map<string, PermissionAuditEntry[]>();
+  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.`,
+      } satisfies PermissionRuleSuggestion;
+    })
+    .sort((a, b) => a.tool.localeCompare(b.tool));
+}

package/src/runtime/plugins/hot-reload.ts

@@ -0,0 +1,221 @@
+/**
+ * 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 type { PluginLoaderDeps } from '../../plugins/loader.ts';
+import type { LoadedPlugin } from '../../plugins/loader.ts';
+import type { PluginHealthCheckResult, PluginManifestV2 } from './types.ts';
+import type { PluginLifecycleManager } from './manager.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+/**
+ * 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;
+}
+
+/** Default trivial health check — always returns healthy. */
+async function defaultHealthCheck(name: string): Promise<PluginHealthCheckResult> {
+  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: string,
+  manifest: PluginManifestV2,
+  pluginDir: string,
+  deps: PluginLoaderDeps,
+  lcm: PluginLifecycleManager,
+  options: HotReloadOptions,
+): Promise<HotReloadResult> {
+  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 as { reloading: boolean };
+    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.ts');
+      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: import('../../plugins/loader.ts').LoadedPlugin | null = null;
+  try {
+    const { loadPlugin } = await import('../../plugins/loader.ts');
+    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: PluginHealthCheckResult;
+  try {
+    healthResult = await Promise.race([
+      healthCheck(name),
+      new Promise<PluginHealthCheckResult>((_, 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) as { reloading: boolean } | undefined;
+    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: HotReloadResult['failedPhase'],
+  error: string,
+  startTs: number,
+): HotReloadResult {
+  logger.error(`[plugin-hot-reload] phase '${String(phase)}' failed: ${error}`);
+  return {
+    success: false,
+    failedPhase: phase,
+    error,
+    durationMs: Date.now() - startTs,
+    degraded: false,
+  };
+}

package/src/runtime/plugins/index.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.ts';
+ *
+ * const lcm = createPluginLifecycleManager({ sessionId: session.id, runtimeBus });
+ * lcm.scanAndRegister();
+ * ```
+ */
+
+export type {
+  PluginCapability,
+  PluginCapabilityManifest,
+  PluginManifestV2,
+  PluginTransition,
+  TransitionResult,
+  PluginHealthCheckResult,
+  PluginLifecycleRecord,
+  PluginLifecycleManagerOptions,
+  PluginLifecycleState,
+} from './types.ts';
+
+export { ALL_CAPABILITIES, MAX_TRANSITION_HISTORY } from './types.ts';
+
+export {
+  VALID_TRANSITIONS,
+  canTransition,
+  applyTransition,
+  isOperational,
+  isReloadable,
+  isTerminal,
+} from './lifecycle.ts';
+
+export {
+  resolveCapabilityManifest,
+  hasCapability,
+  validateManifestV2,
+} from './manifest.ts';
+
+export { PluginLifecycleManager } from './manager.ts';
+import { PluginLifecycleManager } from './manager.ts';
+
+// Trust framework.
+export type {
+  PluginTrustTier,
+  PluginTrustRecord,
+  SignatureValidationResult,
+} from './trust.ts';
+export {
+  PluginTrustStore,
+  validatePluginSignature,
+  filterCapabilitiesByTrust,
+  SAFE_CAPABILITIES,
+} from './trust.ts';
+
+export type { QuarantineRecord } from './quarantine.ts';
+export { PluginQuarantineEngine } from './quarantine.ts';
+
+export { isHighRiskCapability } from './manifest.ts';
+
+export type { HotReloadOptions, HotReloadResult } from './hot-reload.ts';
+export { runHotReload } from './hot-reload.ts';
+
+/**
+ * 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: import('./types.ts').PluginLifecycleManagerOptions = {},
+): PluginLifecycleManager {
+  return new PluginLifecycleManager(options);
+}