339 lines
11 KiB
TypeScript
339 lines
11 KiB
TypeScript
/**
|
|
* 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<string, unknown>;
|
|
/** 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<string, unknown>;
|
|
riskLevel: RiskLevel;
|
|
execute: (args: Record<string, unknown>) => Promise<string>;
|
|
}
|
|
|
|
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<string, unknown>) => Promise<string>;
|
|
/** 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/plugins/<name>/) 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<void> {
|
|
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<void> {
|
|
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/<tool-name>.js → .cjs → stub fallback.
|
|
*/
|
|
function makePluginToolExecutor(
|
|
def: PluginToolDef,
|
|
pluginDir?: string,
|
|
): (args: Record<string, unknown>) => Promise<string> {
|
|
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<string, unknown>): Promise<string> => {
|
|
try {
|
|
const mod = await import(toolFile) as { execute?: (a: Record<string, unknown>) => Promise<string | unknown> };
|
|
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<string, PluginRuntime>();
|
|
|
|
/**
|
|
* 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<void> {
|
|
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<string, PluginLifecycleState> {
|
|
const states: Record<string, PluginLifecycleState> = {};
|
|
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'],
|
|
},
|
|
},
|
|
],
|
|
};
|