/** * Plugin Module for PraisonAI TypeScript SDK * * Python parity with praisonaiagents/plugins module * * Provides: * - Plugin protocols and interfaces * - Plugin manager for discovery and loading * - Plugin hooks and lifecycle * - Single-file plugin support */ /** * Plugin hook points. * Python parity: praisonaiagents/plugins/plugin.py */ export declare enum PluginHook { BEFORE_AGENT = "before_agent", AFTER_AGENT = "after_agent", BEFORE_TOOL = "before_tool", AFTER_TOOL = "after_tool", BEFORE_LLM = "before_llm", AFTER_LLM = "after_llm", ON_ERROR = "on_error", ON_START = "on_start", ON_STOP = "on_stop" } /** * Plugin types. * Python parity: praisonaiagents/plugins/plugin.py */ export declare enum PluginType { TOOL = "tool", HOOK = "hook", AGENT = "agent", LLM = "llm", MEMORY = "memory", FUNCTION = "function" } /** * Plugin metadata. * Python parity: praisonaiagents/plugins/parser.py */ export interface PluginMetadata { name: string; version: string; description?: string; author?: string; hooks?: PluginHook[]; type?: PluginType; dependencies?: string[]; config?: Record; } /** * Plugin info for listing. * Python parity: praisonaiagents/plugins/plugin.py */ export interface PluginInfo { name: string; version: string; description?: string; enabled: boolean; type: PluginType | string; hooks?: PluginHook[]; } /** * Plugin protocol interface. * Python parity: praisonaiagents/plugins/protocols.py */ export interface PluginProtocol { name: string; version: string; description?: string; hooks?: PluginHook[]; initialize?(): void | Promise; shutdown?(): void | Promise; onHook?(hook: PluginHook, ...args: any[]): any | Promise; } /** * Tool plugin protocol. * Python parity: praisonaiagents/plugins/protocols.py */ export interface ToolPluginProtocol extends PluginProtocol { type: 'tool'; execute(input: any): any | Promise; getSchema(): Record; } /** * Hook plugin protocol. * Python parity: praisonaiagents/plugins/protocols.py */ export interface HookPluginProtocol extends PluginProtocol { type: 'hook'; hooks: PluginHook[]; handle(hook: PluginHook, context: any): any | Promise; } /** * Agent plugin protocol. * Python parity: praisonaiagents/plugins/protocols.py */ export interface AgentPluginProtocol extends PluginProtocol { type: 'agent'; beforeAgent?(agentName: string, input: string): string | Promise; afterAgent?(agentName: string, output: string): string | Promise; } /** * LLM plugin protocol. * Python parity: praisonaiagents/plugins/protocols.py */ export interface LLMPluginProtocol extends PluginProtocol { type: 'llm'; beforeLLM?(messages: any[], options: any): any | Promise; afterLLM?(response: any): any | Promise; } /** * Base Plugin class. * Python parity: praisonaiagents/plugins/plugin.py */ export declare class Plugin implements PluginProtocol { name: string; version: string; description?: string; hooks: PluginHook[]; type: PluginType; private _enabled; constructor(config: { name: string; version?: string; description?: string; hooks?: PluginHook[]; type?: PluginType; }); get enabled(): boolean; enable(): void; disable(): void; initialize(): void | Promise; shutdown(): void | Promise; onHook(hook: PluginHook, ...args: any[]): any | Promise; getInfo(): PluginInfo; } /** * Function-based plugin. * Python parity: praisonaiagents/plugins/plugin.py */ export declare class FunctionPlugin extends Plugin { private _handler; constructor(config: { name: string; version?: string; description?: string; hooks?: PluginHook[]; handler: (hook: PluginHook, ...args: any[]) => any; }); onHook(hook: PluginHook, ...args: any[]): any; } /** * Plugin parse error. * Python parity: praisonaiagents/plugins/parser.py */ export declare class PluginParseError extends Error { readonly filePath?: string | undefined; readonly line?: number | undefined; constructor(message: string, filePath?: string | undefined, line?: number | undefined); } /** * Plugin manager for discovery and lifecycle. * Python parity: praisonaiagents/plugins/manager.py */ export declare class PluginManager { private _plugins; private _singleFilePlugins; private _hookHandlers; constructor(); /** * Register a plugin. */ register(plugin: Plugin): void; /** * Unregister a plugin. */ unregister(name: string): boolean; /** * Get a plugin by name. */ get(name: string): Plugin | undefined; /** * Enable a plugin. */ enable(name: string): boolean; /** * Disable a plugin. */ disable(name: string): boolean; /** * Check if a plugin is enabled. */ isEnabled(name: string): boolean; /** * List all plugins. */ listPlugins(): PluginInfo[]; /** * Fire a hook to all registered handlers. */ fireHook(hook: PluginHook, ...args: any[]): Promise; /** * Fire a hook synchronously. */ fireHookSync(hook: PluginHook, ...args: any[]): any; /** * Initialize all plugins. */ initializeAll(): Promise; /** * Shutdown all plugins. */ shutdownAll(): Promise; /** * Auto-discover and load plugins from the default directories. * * Scans `./.praisonai/plugins/` (project level) and `~/.praisonai/plugins/` * (user level), matching Python's `PluginManager.auto_discover_plugins()`. * * Like Python, loading arbitrary files from disk is opt-in: it does nothing * unless `PRAISONAI_ALLOW_PLUGIN_DISCOVERY` is `true`/`1`/`yes`. Unlike the * previous version, "does nothing" is now reported by the return value * instead of being indistinguishable from a successful scan. * * @returns Number of plugins loaded. */ autoDiscoverPlugins(): number; /** * Load plugins from a directory. * * Each candidate file that is not prefixed with `_` is loaded with * synchronous `require()` and inspected for a `createPlugin` factory, a * `plugin` export, or a default export -- the JavaScript analogue of Python's * `create_plugin` convention. Python parity: `PluginManager.load_from_directory()`. * * Only formats `require()` can actually load are considered: `.js`, `.cjs`, * and (under a TypeScript-aware runtime such as ts-node/ts-jest) `.ts`. ESM * `.mjs` files are intentionally skipped rather than advertised and then * failing to load: a synchronous CommonJS loader cannot import them, so * counting them here would report a "load" that never happened. Ship ESM * plugins transpiled to `.cjs`/`.js`. * * @returns Number of plugins loaded. */ loadFromDirectory(path: string): number; } /** * Get the global plugin manager. * Python parity: praisonaiagents/plugins/manager.py */ export declare function getPluginManager(): PluginManager; /** * Get default plugin directories. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function getDefaultPluginDirs(): string[]; /** * Ensure plugin directory exists. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function ensurePluginDir(path: string): boolean; /** * Discover plugins in a directory. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function discoverPlugins(directory: string): PluginMetadata[]; /** * Load a single plugin. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function loadPlugin(path: string): Plugin | null; /** * Discover and load all plugins. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function discoverAndLoadPlugins(directories?: string[]): Plugin[]; /** * Get plugin template. * Python parity: praisonaiagents/plugins/discovery.py */ export declare function getPluginTemplate(name: string): string; /** * Parse plugin header from content. * Python parity: praisonaiagents/plugins/parser.py */ export declare function parsePluginHeader(content: string): PluginMetadata | null; /** * Parse plugin header from file path. * Python parity: praisonaiagents/plugins/parser.py */ export declare function parsePluginHeaderFromFile(filePath: string): PluginMetadata | null; /** * Enable the plugin system. * Python parity: praisonaiagents/plugins/__init__.py */ export declare function enable(plugins?: string[]): void; /** * Disable plugins. * Python parity: praisonaiagents/plugins/__init__.py */ export declare function disable(plugins?: string[]): void; /** * List all plugins. * Python parity: praisonaiagents/plugins/__init__.py */ export declare function listPlugins(): PluginInfo[]; /** * Check if plugins are enabled. * Python parity: praisonaiagents/plugins/__init__.py */ export declare function isEnabled(name?: string): boolean;