@pellux/goodvibes-tui 0.18.4

package/src/plugins/api.ts

@@ -0,0 +1,383 @@
+import type { CommandRegistry, SlashCommand } from '../input/command-registry.ts';
+import type { ModelDefinition, ProviderRegistry, RuntimeProviderRegistration, TokenLimits, ModelTier } from '../providers/registry.ts';
+import type { LLMProvider } from '../providers/interface.ts';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools/registry';
+import type { ToolDefinition } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { RuntimeEventBus, AnyRuntimeEvent, RuntimeEventPayload } from '../runtime/events/index.ts';
+import type { GatewayMethodCatalog, GatewayMethodDescriptor, GatewayMethodHandler } from '../control-plane/index.ts';
+import {
+  type ChannelDeliveryStrategy,
+  type ChannelPlugin,
+} from '../channels/index.ts';
+import type { ChannelDeliveryRouter, ChannelPluginRegistry } from '../channels/index.ts';
+import type { MemoryEmbeddingProvider, MemoryEmbeddingProviderRegistry } from '../state/index.ts';
+import type { VoiceProvider, VoiceProviderRegistry } from '@pellux/goodvibes-sdk/platform/voice/index';
+import type { MediaProvider, MediaProviderRegistry } from '../media/index.ts';
+import type { WebSearchProvider, WebSearchProviderRegistry } from '../web-search/index.ts';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+/**
+ * PluginProviderConfig — minimal config for registering a custom LLM provider
+ * via an OpenAI-compatible endpoint.
+ */
+export interface PluginProviderConfig {
+  /** Base URL for an OpenAI-compatible endpoint (e.g. "http://localhost:8080/v1"). */
+  baseURL: string;
+  /** API key. May be empty string for local/unauthenticated servers. */
+  apiKey?: string;
+  /** Model IDs this provider exposes. */
+  models: string[];
+  /** Optional display label shown in the model picker. */
+  displayName?: string;
+  /** Optional embedding model exposed by the endpoint. */
+  embeddingModel?: string;
+  /** Optional reasoning-format override for compatible endpoints. */
+  reasoningFormat?: 'mercury' | 'openrouter' | 'llamacpp' | 'none';
+  /** Optional context-window metadata for runtime-registered model picker entries. */
+  contextWindow?: number;
+  /** Optional runtime capability hints for the registered model entries. */
+  capabilities?: Partial<ModelDefinition['capabilities']>;
+  /** Optional reasoning effort options surfaced in the picker. */
+  reasoningEffort?: string[];
+  /** Optional provider tier surfaced in the picker. */
+  tier?: ModelTier;
+  /** Optional token limits surfaced in the picker. */
+  tokenLimits?: TokenLimits;
+  /** Optional auth env vars for provider posture. */
+  authEnvVars?: readonly string[];
+  /** Optional service names that expose service-owned OAuth. */
+  serviceNames?: readonly string[];
+  /** Optional subscription-provider identity used for stored OAuth posture. */
+  subscriptionProviderId?: string;
+  /** Optional catalog suppressions for runtime clients. */
+  suppressCatalogModels?: readonly string[];
+}
+
+export interface PluginRuntimeProviderModel {
+  readonly id: string;
+  readonly displayName?: string;
+  readonly description?: string;
+  readonly contextWindow?: number;
+  readonly selectable?: boolean;
+  readonly capabilities?: Partial<ModelDefinition['capabilities']>;
+  readonly reasoningEffort?: string[];
+  readonly tier?: ModelTier;
+  readonly tokenLimits?: TokenLimits;
+}
+
+export interface PluginProviderRegistration {
+  readonly provider: LLMProvider;
+  readonly models?: readonly PluginRuntimeProviderModel[];
+  readonly suppressCatalogModels?: readonly string[];
+  readonly replace?: boolean;
+}
+
+/**
+ * PluginToolSchema — JSON Schema for a tool parameter object.
+ */
+export type PluginToolSchema = Record<string, unknown>;
+
+/**
+ * PluginToolHandler — Called when the LLM invokes a plugin-registered tool.
+ */
+export type PluginToolHandler = (
+  args: Record<string, unknown>,
+) => Promise<{ success: boolean; output?: string; error?: string }>;
+
+/**
+ * PluginCommandHandler — Called when a user runs a plugin-registered slash command.
+ */
+export type PluginCommandHandler = (args: string[]) => void | Promise<void>;
+
+/**
+ * PluginAPI — The constrained API surface exposed to plugins.
+ * Plugins receive an instance of this interface during init; they cannot
+ * access the wider application internals directly.
+ */
+export interface PluginAPI {
+  /** Register a custom slash command. */
+  registerCommand(
+    name: string,
+    description: string,
+    handler: PluginCommandHandler,
+  ): void;
+
+  /** Register a custom LLM provider (OpenAI-compatible endpoint). */
+  registerProvider(name: string, config: PluginProviderConfig): Promise<void>;
+
+  /** Register a fully custom runtime provider instance with optional model entries. */
+  registerProviderInstance(registration: PluginProviderRegistration): void;
+
+  /** Register a custom tool available to the LLM. */
+  registerTool(
+    name: string,
+    schema: PluginToolSchema,
+    handler: PluginToolHandler,
+  ): void;
+
+  /** Register a callable control-plane gateway method. */
+  registerGatewayMethod(
+    descriptor: Omit<GatewayMethodDescriptor, 'source' | 'pluginId'> & Partial<Pick<GatewayMethodDescriptor, 'source' | 'pluginId'>>,
+    handler: GatewayMethodHandler,
+  ): void;
+
+  /** Register a channel plugin for a surface such as Slack, Discord, ntfy, or webhooks. */
+  registerChannelPlugin(plugin: ChannelPlugin): void;
+
+  /** Register an outbound channel delivery strategy. */
+  registerDeliveryStrategy(strategy: ChannelDeliveryStrategy, options?: { readonly replace?: boolean }): void;
+
+  /** Register a memory embedding provider. Sync providers can power sqlite-vec indexing immediately. */
+  registerMemoryEmbeddingProvider(provider: MemoryEmbeddingProvider, options?: { readonly replace?: boolean; readonly makeDefault?: boolean }): void;
+
+  /** Register a TS-only voice provider for TTS, STT, or realtime session negotiation. */
+  registerVoiceProvider(provider: VoiceProvider, options?: { readonly replace?: boolean }): void;
+
+  /** Register a TS-only media provider for analysis, transform, or generation. */
+  registerMediaProvider(provider: MediaProvider, options?: { readonly replace?: boolean }): void;
+
+  /** Register a provider-backed web search adapter. */
+  registerWebSearchProvider(provider: WebSearchProvider, options?: { readonly replace?: boolean }): void;
+
+  /** Subscribe to a typed runtime event. Returns an unsubscribe function. */
+  onEvent<K extends AnyRuntimeEvent['type']>(
+    eventName: K,
+    handler: (payload: RuntimeEventPayload<K>) => void,
+  ): () => void;
+
+  /** Read a plugin-specific config value from the plugin's stored settings. */
+  getConfig(key: string): unknown;
+
+  /** Emit structured log output to the application logger. */
+  log(level: 'info' | 'warn' | 'error' | 'debug', message: string): void;
+}
+
+/**
+ * PluginAPIContext — Internal dependencies passed when creating a PluginAPI instance.
+ * Not exposed to plugins.
+ */
+export interface PluginAPIContext {
+  pluginName: string;
+  runtimeBus: RuntimeEventBus;
+  commandRegistry: CommandRegistry;
+  providerRegistry: ProviderRegistry;
+  toolRegistry: ToolRegistry;
+  gatewayMethods: GatewayMethodCatalog;
+  channelRegistry: ChannelPluginRegistry;
+  channelDeliveryRouter: ChannelDeliveryRouter;
+  memoryEmbeddingRegistry: MemoryEmbeddingProviderRegistry;
+  voiceProviderRegistry: VoiceProviderRegistry;
+  mediaProviderRegistry: MediaProviderRegistry;
+  webSearchProviderRegistry: WebSearchProviderRegistry;
+  /** Plugin-specific config key-value pairs from plugins.json state. */
+  pluginConfig: Record<string, unknown>;
+  /** Collect cleanup callbacks so the manager can teardown on disable/reload. */
+  cleanup: Array<() => void>;
+}
+
+/**
+ * createPluginAPI — Factory that creates a sandboxed PluginAPI for a single plugin.
+ * All registrations are tracked in `ctx.cleanup` so they can be undone on deactivation.
+ */
+export function createPluginAPI(ctx: PluginAPIContext): PluginAPI {
+  return {
+    registerCommand(name, description, handler) {
+      // Namespace commands to avoid collisions: "plugin-<pluginName>-<name>"
+      const cmdName = `plugin-${ctx.pluginName}-${name}`;
+      const cmd: SlashCommand = {
+        name: cmdName,
+        description: `[${ctx.pluginName}] ${description}`,
+        handler: async (args, _context) => {
+          try {
+            await handler(args);
+          } catch (err) {
+            logger.error(`[plugin:${ctx.pluginName}] Command '${name}' threw: ${summarizeError(err)}`);
+          }
+        },
+      };
+      ctx.commandRegistry.register(cmd);
+      ctx.cleanup.push(() => ctx.commandRegistry.unregister(cmdName));
+    },
+
+    async registerProvider(name, config) {
+      // Dynamically import to avoid circular dependency at module load time.
+      try {
+        const { OpenAICompatProvider } = await import('../providers/openai-compat.ts');
+        try {
+          const provider = new OpenAICompatProvider({
+            name,
+            baseURL: config.baseURL,
+            apiKey: config.apiKey ?? '',
+            defaultModel: config.models[0] ?? '',
+            models: config.models,
+            ...(config.embeddingModel ? { embeddingModel: config.embeddingModel } : {}),
+            ...(config.reasoningFormat ? { reasoningFormat: config.reasoningFormat } : {}),
+            ...(config.authEnvVars ? { authEnvVars: config.authEnvVars } : {}),
+            ...(config.serviceNames ? { serviceNames: config.serviceNames } : {}),
+            ...(config.subscriptionProviderId ? { subscriptionProviderId: config.subscriptionProviderId } : {}),
+            ...(config.suppressCatalogModels ? { suppressedModels: config.suppressCatalogModels } : {}),
+          });
+          const unregister = ctx.providerRegistry.registerRuntimeProvider({
+            provider,
+            models: config.models.map((modelId) => ({
+              id: modelId,
+              provider: name,
+              registryKey: `${name}:${modelId}`,
+              displayName: config.displayName ?? modelId,
+              description: `Plugin provider ${name}`,
+              contextWindow: config.contextWindow ?? 8192,
+              selectable: true,
+              capabilities: {
+                toolCalling: config.capabilities?.toolCalling ?? true,
+                codeEditing: config.capabilities?.codeEditing ?? true,
+                reasoning: config.capabilities?.reasoning ?? false,
+                multimodal: config.capabilities?.multimodal ?? false,
+              },
+              ...(config.reasoningEffort ? { reasoningEffort: config.reasoningEffort } : {}),
+              ...(config.tier ? { tier: config.tier } : {}),
+              ...(config.tokenLimits ? { tokenLimits: config.tokenLimits } : {}),
+            })),
+            suppressCatalogModels: config.suppressCatalogModels,
+          });
+          ctx.cleanup.push(unregister);
+          logger.info(`[plugin:${ctx.pluginName}] Registered provider '${name}' with ${config.models.length} model(s)`);
+        } catch (err) {
+          logger.error(`[plugin:${ctx.pluginName}] registerProvider '${name}' failed: ${summarizeError(err)}`);
+          throw err;
+        }
+      } catch (err) {
+        logger.error(`[plugin:${ctx.pluginName}] Could not import OpenAICompatProvider: ${summarizeError(err)}`);
+        throw err;
+      }
+    },
+
+    registerProviderInstance(registration) {
+      const unregister = ctx.providerRegistry.registerRuntimeProvider({
+        provider: registration.provider,
+        models: (registration.models ?? []).map((model) => ({
+          id: model.id,
+          provider: registration.provider.name,
+          registryKey: `${registration.provider.name}:${model.id}`,
+          displayName: model.displayName ?? model.id,
+          description: model.description ?? `Plugin provider ${registration.provider.name}`,
+          contextWindow: model.contextWindow ?? 8192,
+          selectable: model.selectable ?? true,
+          capabilities: {
+            toolCalling: model.capabilities?.toolCalling ?? true,
+            codeEditing: model.capabilities?.codeEditing ?? true,
+            reasoning: model.capabilities?.reasoning ?? false,
+            multimodal: model.capabilities?.multimodal ?? false,
+          },
+          ...(model.reasoningEffort ? { reasoningEffort: model.reasoningEffort } : {}),
+          ...(model.tier ? { tier: model.tier } : {}),
+          ...(model.tokenLimits ? { tokenLimits: model.tokenLimits } : {}),
+        })),
+        suppressCatalogModels: registration.suppressCatalogModels,
+        replace: registration.replace,
+      } satisfies RuntimeProviderRegistration);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered provider instance '${registration.provider.name}'`);
+    },
+
+    registerTool(name, schema, handler) {
+      const toolName = `plugin_${ctx.pluginName}_${name}`;
+      if (ctx.toolRegistry.has(toolName)) {
+        logger.warn(`[plugin:${ctx.pluginName}] Tool '${toolName}' already registered — skipping`);
+        return;
+      }
+      const definition: ToolDefinition = {
+        name: toolName,
+        description: (schema.description as string) ?? `Plugin tool: ${name}`,
+        parameters: schema,
+      };
+      ctx.toolRegistry.register({
+        definition,
+        execute: async (args) => {
+          try {
+            return await handler(args);
+          } catch (err) {
+            return { success: false, error: summarizeError(err) };
+          }
+        },
+      });
+      // ToolRegistry has no unregister method. Track for cleanup awareness.
+      ctx.cleanup.push(() => {
+        logger.warn(`[plugin:${ctx.pluginName}] Tool '${toolName}' cannot be unregistered on deactivate — it persists until process restart`);
+      });
+    },
+
+    registerGatewayMethod(descriptor, handler) {
+      const methodId = descriptor.id.startsWith(`plugin.${ctx.pluginName}.`)
+        ? descriptor.id
+        : `plugin.${ctx.pluginName}.${descriptor.id}`;
+      const unregister = ctx.gatewayMethods.register({
+        ...descriptor,
+        id: methodId,
+        source: 'plugin',
+        pluginId: ctx.pluginName,
+      }, handler);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered gateway method '${methodId}'`);
+    },
+
+    registerChannelPlugin(plugin) {
+      const registry = ctx.channelRegistry;
+      registry.register(plugin);
+      ctx.cleanup.push(() => {
+        if (registry.get(plugin.id) === plugin) registry.unregister(plugin.id);
+      });
+      logger.info(`[plugin:${ctx.pluginName}] Registered channel plugin '${plugin.id}'`);
+    },
+
+    registerDeliveryStrategy(strategy, options = {}) {
+      const router = ctx.channelDeliveryRouter;
+      router.registerStrategy(strategy, options);
+      ctx.cleanup.push(() => {
+        router.unregisterStrategy(strategy.id);
+      });
+      logger.info(`[plugin:${ctx.pluginName}] Registered delivery strategy '${strategy.id}'`);
+    },
+
+    registerMemoryEmbeddingProvider(provider, options = {}) {
+      const unregister = ctx.memoryEmbeddingRegistry.register(provider, options);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered memory embedding provider '${provider.id}'`);
+    },
+
+    registerVoiceProvider(provider, options = {}) {
+      const unregister = ctx.voiceProviderRegistry.register(provider, options);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered voice provider '${provider.id}'`);
+    },
+
+    registerMediaProvider(provider, options = {}) {
+      const unregister = ctx.mediaProviderRegistry.register(provider, options);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered media provider '${provider.id}'`);
+    },
+
+    registerWebSearchProvider(provider, options = {}) {
+      const unregister = ctx.webSearchProviderRegistry.register(provider, options);
+      ctx.cleanup.push(unregister);
+      logger.info(`[plugin:${ctx.pluginName}] Registered web search provider '${provider.id}'`);
+    },
+
+    onEvent(eventName, handler) {
+      const unsub = ctx.runtimeBus.on(
+        eventName,
+        (envelope) => handler(envelope.payload as RuntimeEventPayload<typeof eventName>),
+      );
+      ctx.cleanup.push(unsub);
+      return unsub;
+    },
+
+    getConfig(key) {
+      return ctx.pluginConfig[key];
+    },
+
+    log(level, message) {
+      logger[level](`[plugin:${ctx.pluginName}] ${message}`);
+    },
+  };
+}

package/src/plugins/loader.ts

@@ -0,0 +1,304 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, resolve, isAbsolute } from 'path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { createPluginAPI, type PluginAPIContext } from './api.ts';
+import type { CommandRegistry } from '../input/command-registry.ts';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools/registry';
+import type { RuntimeEventBus } from '../runtime/events/index.ts';
+import type { GatewayMethodCatalog } from '../control-plane/index.ts';
+import type { ChannelDeliveryRouter, ChannelPluginRegistry } from '../channels/index.ts';
+import type { MemoryEmbeddingProviderRegistry } from '../state/index.ts';
+import type { VoiceProviderRegistry } from '@pellux/goodvibes-sdk/platform/voice/index';
+import type { MediaProviderRegistry } from '../media/index.ts';
+import type { WebSearchProviderRegistry } from '../web-search/index.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+export interface PluginPathOptions {
+  readonly cwd: string;
+  readonly homeDir: string;
+}
+
+/**
+ * Plugin search directories in precedence order.
+ * Project-local plugins override global plugins with the same manifest name.
+ */
+export function getUserPluginDirectory(options: PluginPathOptions): string {
+  return join(options.homeDir, '.goodvibes', 'tui', 'plugins');
+}
+
+export function getPluginDirectories(options: PluginPathOptions): string[] {
+  return [
+    join(options.cwd, '.goodvibes', 'plugins'),
+    join(options.cwd, '.goodvibes', 'tui', 'plugins'),
+    getUserPluginDirectory(options),
+  ];
+}
+
+/**
+ * PluginManifest — The structure of a plugin's manifest.json.
+ */
+export interface PluginManifest {
+  /** Unique plugin identifier (no spaces, lowercase-kebab). */
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  /** Entry point relative to plugin directory. Defaults to "index.ts". */
+  main?: string;
+  /** Optional list of runtime event names the plugin subscribes to. */
+  hooks?: string[];
+}
+
+/**
+ * PluginEntryPoint — The exports expected from a plugin's entry file.
+ */
+export interface PluginEntryPoint {
+  /** Called once after the plugin is loaded. Receives the sandboxed PluginAPI. */
+  init(api: ReturnType<typeof createPluginAPI>): void | Promise<void>;
+  /** Optional: called when the plugin is activated (after init). */
+  activate?(): void | Promise<void>;
+  /** Optional: called when the plugin is deactivated (before cleanup). */
+  deactivate?(): void | Promise<void>;
+}
+
+/**
+ * LoadedPlugin — Runtime state of a single loaded plugin.
+ */
+export interface LoadedPlugin {
+  manifest: PluginManifest;
+  /** Absolute path to the plugin directory. */
+  pluginDir: string;
+  /** Whether the plugin is currently active (init + activate completed). */
+  active: boolean;
+  /** Cleanup callbacks accumulated during plugin API use. */
+  cleanup: Array<() => void>;
+  /** The resolved entry point module (available after load). */
+  entry?: PluginEntryPoint;
+}
+
+/**
+ * DiscoveredPlugin — Result of scanning the plugins directory.
+ */
+export interface DiscoveredPlugin {
+  pluginDir: string;
+  manifest: PluginManifest;
+}
+
+/**
+ * discoverPlugins — Scan the configured plugin directories for valid plugin folders.
+ * Each subdirectory with a readable manifest.json is a candidate.
+ */
+function scanPluginDirectory(rootDir: string): DiscoveredPlugin[] {
+  if (!existsSync(rootDir)) return [];
+  const results: DiscoveredPlugin[] = [];
+  let entries: string[];
+  try {
+    entries = readdirSync(rootDir);
+  } catch (err) {
+    logger.warn(`[plugins] Could not read plugins directory '${rootDir}': ${summarizeError(err)}`);
+    return [];
+  }
+
+  for (const entry of entries) {
+    const pluginDir = join(rootDir, entry);
+    try {
+      if (!statSync(pluginDir).isDirectory()) continue;
+
+      const manifestPath = join(pluginDir, 'manifest.json');
+      if (!existsSync(manifestPath)) continue;
+
+      const raw = readFileSync(manifestPath, 'utf-8');
+      const manifest = JSON.parse(raw) as PluginManifest;
+
+      if (!manifest.name || !manifest.version) {
+        logger.warn(`[plugins] ${entry}: manifest.json missing required fields (name, version)`);
+        continue;
+      }
+
+      // Validate manifest field types
+      if (typeof manifest.name !== 'string' || typeof manifest.version !== 'string') {
+        logger.warn(`[plugins] ${entry}: manifest.json 'name' and 'version' must be strings`);
+        continue;
+      }
+      if (manifest.main !== undefined) {
+        if (typeof manifest.main !== 'string') {
+          logger.warn(`[plugins] ${entry}: manifest.json 'main' must be a string`);
+          continue;
+        }
+        if (isAbsolute(manifest.main)) {
+          logger.warn(`[plugins] ${entry}: manifest.json 'main' must be a relative path, not absolute`);
+          continue;
+        }
+      }
+
+      results.push({ pluginDir, manifest });
+    } catch (err) {
+      logger.warn(`[plugins] ${entry}: failed to parse manifest — ${summarizeError(err)}`);
+    }
+  }
+
+  return results;
+}
+
+export function discoverPlugins(options: PluginPathOptions): DiscoveredPlugin[] {
+  const discovered = new Map<string, DiscoveredPlugin>();
+  for (const dir of getPluginDirectories(options)) {
+    for (const plugin of scanPluginDirectory(dir)) {
+      if (!discovered.has(plugin.manifest.name)) {
+        discovered.set(plugin.manifest.name, plugin);
+      }
+    }
+  }
+  return [...discovered.values()];
+}
+
+/**
+ * PluginLoaderDeps — External dependencies injected into the loader.
+ */
+export interface PluginLoaderDeps {
+  runtimeBus: RuntimeEventBus;
+  commandRegistry: CommandRegistry;
+  providerRegistry: ProviderRegistry;
+  toolRegistry: ToolRegistry;
+  gatewayMethods: GatewayMethodCatalog;
+  channelRegistry: ChannelPluginRegistry;
+  channelDeliveryRouter: ChannelDeliveryRouter;
+  memoryEmbeddingRegistry: MemoryEmbeddingProviderRegistry;
+  voiceProviderRegistry: VoiceProviderRegistry;
+  mediaProviderRegistry: MediaProviderRegistry;
+  webSearchProviderRegistry: WebSearchProviderRegistry;
+  /** Returns plugin-specific config given a plugin name. */
+  getPluginConfig(name: string): Record<string, unknown>;
+  /** Returns whether a plugin is enabled in persistent state. */
+  isEnabled(name: string): boolean;
+}
+
+/**
+ * loadPlugin — Load, init, and activate a single plugin.
+ * Returns a LoadedPlugin on success, or null on failure.
+ *
+ * @param cacheBust - Optional timestamp suffix appended to the import URL to bypass
+ *   Bun's module cache. Pass `Date.now()` on reload to force fresh execution.
+ */
+export async function loadPlugin(
+  discovered: DiscoveredPlugin,
+  deps: PluginLoaderDeps,
+  cacheBust?: number,
+): Promise<LoadedPlugin | null> {
+  const { manifest, pluginDir } = discovered;
+  const entryFile = manifest.main ?? 'index.ts';
+  const entryPath = join(pluginDir, entryFile);
+
+  // Path traversal guard: resolved entry must remain within pluginDir
+  const resolvedEntry = resolve(entryPath);
+  const resolvedPluginDir = resolve(pluginDir);
+  if (!resolvedEntry.startsWith(resolvedPluginDir + '/') && resolvedEntry !== resolvedPluginDir) {
+    logger.error(`[plugins] ${manifest.name}: path traversal detected — entry '${entryFile}' resolves outside plugin directory`);
+    return null;
+  }
+
+  if (!existsSync(entryPath)) {
+    logger.warn(`[plugins] ${manifest.name}: entry file not found: ${entryPath}`);
+    return null;
+  }
+
+  // Trust notice — plugins run as trusted code (like VS Code extensions)
+  logger.warn(`[plugins] Loading '${manifest.name}' — plugins are trusted code and run with full application access`);
+
+  const loaded: LoadedPlugin = {
+    manifest,
+    pluginDir,
+    active: false,
+    cleanup: [],
+  };
+
+  try {
+    // Dynamic import — Bun supports TS imports directly.
+    // Append cache-bust query param on reload so Bun re-executes the module.
+    const importPath = cacheBust !== undefined ? `${entryPath}?t=${cacheBust}` : entryPath;
+    const mod = await import(importPath) as unknown;
+
+    // Validate module shape before casting
+    if (!mod || typeof mod !== 'object') {
+      logger.warn(`[plugins] ${manifest.name}: entry file did not export a module object`);
+      return null;
+    }
+    const modObj = mod as Record<string, unknown>;
+    if (typeof modObj['init'] !== 'function') {
+      logger.warn(`[plugins] ${manifest.name}: entry file must export an init() function`);
+      return null;
+    }
+    if (modObj['activate'] !== undefined && typeof modObj['activate'] !== 'function') {
+      logger.warn(`[plugins] ${manifest.name}: entry file 'activate' export must be a function`);
+      return null;
+    }
+    if (modObj['deactivate'] !== undefined && typeof modObj['deactivate'] !== 'function') {
+      logger.warn(`[plugins] ${manifest.name}: entry file 'deactivate' export must be a function`);
+      return null;
+    }
+    const entry = mod as PluginEntryPoint;
+
+    loaded.entry = entry;
+
+    const ctx: PluginAPIContext = {
+      pluginName: manifest.name,
+      runtimeBus: deps.runtimeBus,
+      commandRegistry: deps.commandRegistry,
+      providerRegistry: deps.providerRegistry,
+      toolRegistry: deps.toolRegistry,
+      gatewayMethods: deps.gatewayMethods,
+      channelRegistry: deps.channelRegistry,
+      channelDeliveryRouter: deps.channelDeliveryRouter,
+      memoryEmbeddingRegistry: deps.memoryEmbeddingRegistry,
+      voiceProviderRegistry: deps.voiceProviderRegistry,
+      mediaProviderRegistry: deps.mediaProviderRegistry,
+      webSearchProviderRegistry: deps.webSearchProviderRegistry,
+      pluginConfig: deps.getPluginConfig(manifest.name),
+      cleanup: loaded.cleanup,
+    };
+
+    const api = createPluginAPI(ctx);
+
+    // Lifecycle: init
+    await entry.init(api);
+
+    // Lifecycle: activate
+    if (typeof entry.activate === 'function') {
+      await entry.activate();
+    }
+
+    loaded.active = true;
+    logger.info(`[plugins] ${manifest.name} v${manifest.version} activated`);
+    return loaded;
+  } catch (err) {
+    logger.error(`[plugins] ${manifest.name}: load failed — ${summarizeError(err)}`);
+    // Run cleanup for anything that was registered before the error
+    for (const fn of loaded.cleanup) {
+      try { fn(); } catch { /* best-effort */ }
+    }
+    return null;
+  }
+}
+
+/**
+ * unloadPlugin — Deactivate a plugin and run all cleanup callbacks.
+ */
+export async function unloadPlugin(plugin: LoadedPlugin): Promise<void> {
+  if (!plugin.active) return;
+
+  try {
+    if (typeof plugin.entry?.deactivate === 'function') {
+      await plugin.entry.deactivate();
+    }
+  } catch (err) {
+    logger.warn(`[plugins] ${plugin.manifest.name}: deactivate threw — ${summarizeError(err)}`);
+  }
+
+  for (const fn of plugin.cleanup) {
+    try { fn(); } catch { /* best-effort */ }
+  }
+  plugin.cleanup.length = 0;
+  plugin.active = false;
+  logger.info(`[plugins] ${plugin.manifest.name} deactivated`);
+}