/** * Plugin runtime lifecycle management for Waggle plugins. * * Provides an in-memory state machine for plugin lifecycle (installed → enabled → active → disabled) * and tool/skill auto-registration. No filesystem interaction — that's PluginManager's job. */ import { EventEmitter } from 'events'; import { existsSync } from 'fs'; import { join } from 'path'; import { RISK_LEVELS, riskAtLeast, type RiskLevel } from '@waggle/shared'; import type { PluginManifest } from './plugin-manifest.js'; // --------------------------------------------------------------------------- // Types // --------------------------------------------------------------------------- /** Lifecycle states for a plugin runtime */ export type PluginLifecycleState = 'installed' | 'enabled' | 'active' | 'disabled' | 'error'; /** Tool definition contributed by a plugin (mirrors agent ToolDefinition shape) */ export interface PluginToolDef { name: string; description: string; parameters: Record; /** Optional declaration; runtime normalization enforces a medium floor. */ riskLevel?: RiskLevel; } /** A fully-hydrated tool with an execute function, created during activation */ export interface PluginTool { name: string; description: string; parameters: Record; riskLevel: RiskLevel; execute: (args: Record) => Promise; } function normalizePluginToolRisk(value: unknown): RiskLevel { if ((RISK_LEVELS as readonly unknown[]).includes(value)) { const declared = value as RiskLevel; if (riskAtLeast(declared, 'medium')) return declared; } return 'medium'; } /** Extended manifest that includes tool declarations */ export interface PluginManifestWithTools extends PluginManifest { tools?: PluginToolDef[]; } /** Optional dependencies passed to activation */ export interface ActivationDependencies { /** Custom tool executor factory — given a PluginToolDef, return an execute function */ toolExecutor?: (def: PluginToolDef) => (args: Record) => Promise; /** Required capabilities that must be present for activation to succeed */ requiredCapabilities?: string[]; /** Capabilities available in the current environment */ availableCapabilities?: string[]; /** Path to the plugin directory (e.g., ~/.waggle-community/plugins//) for resolving tool implementations */ pluginDir?: string; } /** Events emitted by PluginRuntime */ export interface PluginRuntimeEvents { stateChange: (event: { plugin: string; from: PluginLifecycleState; to: PluginLifecycleState }) => void; error: (event: { plugin: string; error: Error }) => void; } // --------------------------------------------------------------------------- // PluginRuntime — single plugin lifecycle // --------------------------------------------------------------------------- export class PluginRuntime extends EventEmitter { private state: PluginLifecycleState = 'installed'; private readonly manifest: PluginManifestWithTools; private readonly deps: ActivationDependencies; private contributedTools: PluginTool[] = []; private contributedSkills: string[] = []; constructor(manifest: PluginManifestWithTools, deps?: ActivationDependencies) { super(); this.manifest = manifest; this.deps = deps ?? {}; } /** Current lifecycle state */ getState(): PluginLifecycleState { return this.state; } /** The plugin manifest */ getManifest(): PluginManifestWithTools { return this.manifest; } /** Tools contributed by this plugin (only populated when active) */ getContributedTools(): PluginTool[] { return [...this.contributedTools]; } /** Skills contributed by this plugin (only populated when active) */ getContributedSkills(): string[] { return [...this.contributedSkills]; } /** * Enable the plugin and attempt activation. * Transitions: installed|disabled|error → enabled → active (or error). */ async enable(): Promise { if (this.state === 'active' || this.state === 'enabled') { // Already active or mid-activation — no-op return; } if (this.state !== 'installed' && this.state !== 'disabled' && this.state !== 'error') { throw new Error(`Cannot enable plugin "${this.manifest.name}" from state "${this.state}"`); } this.transition('enabled'); await this.activate(); } /** * Activate the plugin — register tools and skills. * Called internally by enable(). Transitions enabled → active or enabled → error. */ private async activate(): Promise { try { // Check required capabilities const required = this.deps.requiredCapabilities ?? []; const available = this.deps.availableCapabilities ?? []; for (const cap of required) { if (!available.includes(cap)) { throw new Error(`Missing required capability: ${cap}`); } } // Build contributed tools const toolDefs = this.manifest.tools ?? []; const executor = this.deps.toolExecutor ?? ((d: PluginToolDef) => makePluginToolExecutor(d, this.deps.pluginDir)); this.contributedTools = toolDefs.map((def) => ({ name: def.name, description: def.description, parameters: def.parameters, riskLevel: normalizePluginToolRisk(def.riskLevel), execute: executor(def), })); // Register contributed skills this.contributedSkills = [...(this.manifest.skills ?? [])]; this.transition('active'); } catch (err) { const error = err instanceof Error ? err : new Error(String(err)); this.transition('error'); this.emit('error', { plugin: this.manifest.name, error }); throw error; } } /** * Disable the plugin — remove tools and skills. * Transitions: active|enabled|error → disabled. */ disable(): void { if (this.state === 'disabled' || this.state === 'installed') { // Already disabled or never enabled — no-op return; } this.contributedTools = []; this.contributedSkills = []; this.transition('disabled'); } private transition(to: PluginLifecycleState): void { const from = this.state; this.state = to; this.emit('stateChange', { plugin: this.manifest.name, from, to }); } } // --------------------------------------------------------------------------- // Default tool executor (stub — returns plugin-name-prefixed acknowledgement) // --------------------------------------------------------------------------- /** * Build a real tool executor for a plugin. * Resolution: pluginDir/tools/.js → .cjs → stub fallback. */ function makePluginToolExecutor( def: PluginToolDef, pluginDir?: string, ): (args: Record) => Promise { if (pluginDir) { const slug = def.name.replace(/[^a-zA-Z0-9_-]/g, '-'); const candidates = [ join(pluginDir, 'tools', `${slug}.js`), join(pluginDir, 'tools', `${slug}.cjs`), join(pluginDir, 'tools', `${def.name}.js`), ]; const toolFile = candidates.find(f => existsSync(f)); if (toolFile) { return async (args: Record): Promise => { try { const mod = await import(toolFile) as { execute?: (a: Record) => Promise }; if (typeof mod.execute !== 'function') return JSON.stringify({ error: `Tool "${def.name}" does not export execute()` }); const result = await mod.execute(args); return typeof result === 'string' ? result : JSON.stringify(result); } catch (err) { return JSON.stringify({ error: `Tool "${def.name}" failed: ${(err as Error).message}` }); } }; } } // Stub fallback return async (args) => JSON.stringify({ tool: def.name, args, status: 'executed' }); } // --------------------------------------------------------------------------- // PluginRuntimeManager — manages multiple plugin runtimes // --------------------------------------------------------------------------- export class PluginRuntimeManager extends EventEmitter { private readonly plugins = new Map(); /** * Register a plugin in the `installed` state. * Returns the created PluginRuntime. */ register(manifest: PluginManifestWithTools, deps?: ActivationDependencies): PluginRuntime { if (this.plugins.has(manifest.name)) { throw new Error(`Plugin "${manifest.name}" is already registered`); } const runtime = new PluginRuntime(manifest, deps); // Forward events runtime.on('stateChange', (event) => this.emit('stateChange', event)); runtime.on('error', (event) => this.emit('error', event)); this.plugins.set(manifest.name, runtime); return runtime; } /** * Enable a plugin by name. */ async enable(name: string): Promise { const runtime = this.getRuntime(name); await runtime.enable(); } /** * Disable a plugin by name. */ disable(name: string): void { const runtime = this.getRuntime(name); runtime.disable(); } /** * Return all active plugin runtimes. */ getActive(): PluginRuntime[] { return [...this.plugins.values()].filter((p) => p.getState() === 'active'); } /** * Aggregate tools from all active plugins. */ getAllTools(): PluginTool[] { return this.getActive().flatMap((p) => p.getContributedTools()); } /** * Aggregate skills from all active plugins. */ getAllSkills(): string[] { return this.getActive().flatMap((p) => p.getContributedSkills()); } /** * Return state summary for all registered plugins. */ getPluginStates(): Record { const states: Record = {}; for (const [name, runtime] of this.plugins) { states[name] = runtime.getState(); } return states; } /** * Get a specific plugin runtime by name. */ getRuntime(name: string): PluginRuntime { const runtime = this.plugins.get(name); if (!runtime) { throw new Error(`Plugin "${name}" is not registered`); } return runtime; } } // --------------------------------------------------------------------------- // Flagship plugin fixture — web-research // --------------------------------------------------------------------------- /** Web research plugin manifest (test fixture / example) */ export const webResearchPluginManifest: PluginManifestWithTools = { name: 'web-research', version: '1.0.0', description: 'Web research tools for scraping and summarizing web content', skills: ['web-research'], tools: [ { name: 'web_scrape', description: 'Scrape content from a given URL and return the text', parameters: { type: 'object', properties: { url: { type: 'string', description: 'The URL to scrape' }, selector: { type: 'string', description: 'Optional CSS selector to extract specific content' }, }, required: ['url'], }, }, { name: 'web_summarize', description: 'Summarize the content of a web page given its URL', parameters: { type: 'object', properties: { url: { type: 'string', description: 'The URL to summarize' }, maxLength: { type: 'number', description: 'Maximum summary length in characters' }, }, required: ['url'], }, }, ], };