# Plugin System Deep Dive This document covers everything about OpenACP's plugin system: the interface, lifecycle, context API, permissions, error isolation, settings, and loading order. --- ## OpenACPPlugin Interface Every plugin exports an object conforming to this interface: ```typescript interface OpenACPPlugin { // === Identity === name: string // '@openacp/security' or '@community/translator' version: string // semver, e.g. '1.0.0' description?: string // shown in plugin list // === Dependencies === pluginDependencies?: Record // name -> semver range optionalPluginDependencies?: Record // used if available // === Override === overrides?: string // replace a built-in plugin entirely // === Permissions === permissions?: PluginPermission[] // defaults to [] (no capabilities) // === Settings === settingsSchema?: ZodSchema // validation for settings.json essential?: boolean // true = needs setup before system can run // === Runtime lifecycle === setup(ctx: PluginContext): Promise // called every boot teardown?(): Promise // called on shutdown // === Install lifecycle === install?(ctx: InstallContext): Promise // first-time setup uninstall?(ctx: InstallContext, opts: { purge: boolean }): Promise configure?(ctx: InstallContext): Promise // reconfigure migrate?(ctx: MigrateContext, oldSettings: unknown, oldVersion: string): Promise } ``` ### Field Details | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Unique identifier. Must match `/^[@a-z0-9][a-z0-9._\/-]*$/` | | `version` | Yes | Semver version string | | `pluginDependencies` | No | Plugins that must load before this one | | `optionalPluginDependencies` | No | Used if available, graceful degrade if not | | `overrides` | No | Name of built-in plugin to replace | | `permissions` | No | Defaults to `[]` -- no capabilities | | `settingsSchema` | No | Zod schema for validating settings | | `essential` | No | If true, plugin needs interactive setup before system can run | | `setup()` | Yes | Called every boot in dependency order (30s timeout) | | `teardown()` | No | Called on shutdown in reverse order (10s timeout) | | `install()` | No | Interactive first-time setup | | `configure()` | No | Interactive reconfiguration | | `migrate()` | No | Non-interactive settings migration on version change | | `uninstall()` | No | Cleanup on removal | --- ## Plugin Lifecycle ``` install ──> [reboot] ──> migrate? ──> setup ──> [running] ──> teardown ──> uninstall | | | First-time setup | Version mismatch detected | Interactive (CLI) | Non-interactive (boot) v v settings.json created settings.json updated ``` ### Lifecycle hooks in detail | Hook | Trigger | Interactive? | Has Services? | |------|---------|-------------|---------------| | `install()` | `openacp plugins install ` or first-run | Yes | No | | `migrate()` | Boot -- stored version differs from plugin version | No | No | | `configure()` | `openacp plugins configure ` | Yes | No | | `setup()` | Every boot, after migrate | No | Yes | | `teardown()` | Shutdown | No | Yes | | `uninstall()` | `openacp plugins uninstall ` | Yes | No | ### Boot sequence for a single plugin ``` Load plugin code from registry -> Check plugins.json: stored version vs plugin.version -> Version mismatch? -> call plugin.migrate(ctx, oldSettings, oldVersion) -> Plugin returns new settings -> written to settings.json -> Update plugins.json version -> Validate settings against settingsSchema (if provided) -> Create PluginContext with settings from settings.json -> Call plugin.setup(pluginContext) ``` --- ## PluginContext API Every plugin receives a `PluginContext` in its `setup()` call. The context is scoped -- methods check permissions and auto-cleanup on teardown. ```typescript interface PluginContext { // Identity pluginName: string pluginConfig: Record // from settings.json // Events (requires 'events:read' / 'events:emit') on(event: string, handler: (...args: unknown[]) => void): void off(event: string, handler: (...args: unknown[]) => void): void emit(event: string, payload: unknown): void // Services (requires 'services:register' / 'services:use') registerService(name: string, implementation: T): void getService(name: string): T | undefined // Middleware (requires 'middleware:register') registerMiddleware( hook: H, opts: MiddlewareOptions ): void // Commands (requires 'commands:register') registerCommand(def: CommandDef): void // Storage (requires 'storage:read' / 'storage:write') storage: PluginStorage // Messaging (requires 'services:use') sendMessage(sessionId: string, content: OutgoingMessage): Promise // Kernel access (requires 'kernel:access') sessions: SessionManager config: ConfigManager eventBus: EventBus // Always available log: Logger } ``` ### PluginStorage Per-plugin key-value store backed by a JSON file at `~/.openacp/plugins/data/{plugin-name}/kv.json`. ```typescript interface PluginStorage { get(key: string): Promise set(key: string, value: T): Promise delete(key: string): Promise list(): Promise getDataDir(): string // returns absolute path, creates dir if needed } ``` Writes are serialized per plugin. The `getDataDir()` method returns an absolute path where the plugin can store anything (SQLite databases, large files, caches, etc.). --- ## Permissions Model Plugins declare required permissions in their `permissions` array. Each `PluginContext` method checks permission before executing. ```typescript type PluginPermission = | 'events:read' // ctx.on() -- subscribe to events | 'events:emit' // ctx.emit() -- emit custom events | 'services:register' // ctx.registerService() | 'services:use' // ctx.getService(), ctx.sendMessage() | 'middleware:register' // ctx.registerMiddleware() | 'commands:register' // ctx.registerCommand() | 'storage:read' // ctx.storage.get/list | 'storage:write' // ctx.storage.set/delete | 'kernel:access' // ctx.sessions, ctx.config, ctx.eventBus ``` If a plugin calls a method without the required permission, a `PluginPermissionError` is thrown immediately. This error counts against the plugin's error budget. Omitting `permissions` entirely defaults to `[]` -- the plugin can only run code in `setup()` and use `ctx.log`. --- ## Error Isolation Every interaction with a plugin is wrapped in error handling. A plugin crash never takes down core or other plugins. ### Error budget Community plugins have an error budget: **10 errors per hour** (configurable). When exceeded: 1. Plugin is auto-disabled for the rest of the runtime 2. All middleware, event handlers, and service calls stop executing 3. Event `plugin:disabled` is emitted 4. Warning logged Built-in plugins are exempt from error budgets -- bugs should be fixed in code. ### Per-call isolation ```typescript async function safeCall( pluginName: string, fn: () => Promise, fallback: T, errorTracker: ErrorTracker, ): Promise { if (errorTracker.isDisabled(pluginName)) return fallback try { return await Promise.race([ fn(), timeout(5000).then(() => { throw new Error('timeout') }), ]) } catch (err) { log.error({ plugin: pluginName, err }, 'Plugin error') errorTracker.increment(pluginName) return fallback } } ``` ### Recovery - Disable is runtime-only -- does NOT persist to config - Next restart re-enables the plugin and resets the budget - Manual re-enable during runtime is not supported in v1 ### Error behavior by context | Context | Behavior | |---------|----------| | Middleware chain | Skip handler, pass original payload to next | | Event handler | Swallow error, other listeners still receive event | | Service call | Throw to caller, caller handles gracefully | | setup() throws | Plugin marked failed, dependents cascade-skipped | | teardown() throws | Logged, continue with next plugin | --- ## Settings System Each plugin has its own `settings.json` file, managed independently. ### Directory structure ``` ~/.openacp/ config.json <- core settings ONLY plugins.json <- Plugin Registry plugins/ @openacp/ telegram/ settings.json <- plugin settings data/ <- plugin data dir security/ settings.json data/ @community/ translator/ settings.json data/ ``` ### SettingsAPI Available in `InstallContext` for interactive lifecycle hooks. ```typescript interface SettingsAPI { get(key: string): Promise set(key: string, value: T): Promise getAll(): Promise> setAll(settings: Record): Promise delete(key: string): Promise clear(): Promise has(key: string): Promise } ``` ### SettingsManager Core module that creates `SettingsAPI` instances per plugin and handles validation. ```typescript class SettingsManager { createAPI(pluginName: string): SettingsAPI loadSettings(pluginName: string): Promise> validateSettings(pluginName: string, settings: unknown, schema?: ZodSchema): ValidationResult } ``` Validation runs after: 1. `migrate()` returns new settings 2. `install()` completes 3. API/Web UI updates settings Validation failure prevents boot -- the plugin is marked as failed. --- ## Plugin Registry Tracks all installed plugins in `~/.openacp/plugins.json`: ```json { "installed": { "@openacp/telegram": { "version": "1.0.0", "installedAt": "2026-03-26T10:00:00Z", "updatedAt": "2026-03-26T10:00:00Z", "source": "builtin", "enabled": true, "settingsPath": "~/.openacp/plugins/@openacp/telegram/settings.json", "description": "Telegram messaging adapter" }, "@community/translator": { "version": "2.1.0", "source": "npm", "enabled": true, "description": "Auto-translate messages" } } } ``` ### PluginRegistry class ```typescript class PluginRegistry { list(): Map get(name: string): PluginEntry | undefined register(name: string, entry: PluginEntry): void remove(name: string): void setEnabled(name: string, enabled: boolean): void updateVersion(name: string, version: string): void listEnabled(): Map listBySource(source: 'builtin' | 'npm' | 'local'): Map } ``` Built-in plugins cannot be uninstalled (source `builtin`). They can only be disabled: ```bash openacp plugins disable @openacp/speech ``` --- ## Plugin Discovery and Loading Order ### Discovery 1. **Built-in plugins**: imported from `src/plugins/*/index.ts`, marked as trusted 2. **Community plugins**: read from `~/.openacp/plugins/package.json` dependencies, checksums verified against `~/.openacp/plugins/checksums.json` ### Filtering - Config `enabled: false` -> skip - No config entry for built-in -> enabled by default - No config entry for community -> disabled by default ### Override resolution If a plugin declares `overrides: '@openacp/security'`, the overridden plugin is removed from the load list entirely. The overriding plugin takes its place. ### Dependency validation 1. Build dependency graph (nodes = plugins, edges = `pluginDependencies`) 2. Detect circular dependencies (DFS) -- skip all plugins in cycle 3. Check missing required dependencies -- skip plugin and all its dependents 4. Check semver ranges -- log warning on mismatch, still attempt to load 5. Optional dependencies: log info if missing, plugin handles `undefined` from `getService()` ### Topological sort ``` Plugins with no dependencies -> depth 0 (load first) Plugins depending on depth-0 plugins -> depth 1 Plugins depending on depth-1 plugins -> depth 2 ... ``` Within the same depth level, load order is determined by registration order. --- ## Legacy Migration When upgrading from pre-plugin config.json (all settings in one file): 1. Core detects: config.json has plugin fields AND plugins.json does not exist 2. Create plugins.json, auto-register all built-in plugins 3. For each built-in: extract legacy config, call `plugin.install()` with `legacyConfig` 4. Plugin reads `legacyConfig` -> saves to settings.json (no interactive prompts) 5. Strip plugin-specific fields from config.json 6. Normal boot continues If migration fails for one plugin, legacy config is kept for retry on next boot. --- ## Further Reading - [Architecture Overview](README.md) -- high-level picture - [Core Design](core-design.md) -- core module details - [Writing Plugins](writing-plugins.md) -- step-by-step plugin development guide - [Built-in Plugins](built-in-plugins.md) -- all 11 built-in plugins documented