@agenticc/core 1.0.0

package/dist/core/plugin-manager.js

@@ -0,0 +1,369 @@
+/**
+ * Plugin Manager
+ *
+ * Manages plugin lifecycle, tool registration, and namespace handling.
+ * Provides dependency injection for plugins through PluginContext.
+ *
+ * @module core/plugin-manager
+ */
+import { DEFAULT_PLUGIN_MANAGER_OPTIONS } from '../types/plugin.js';
+import { toolToDefinition } from '../types/tool.js';
+/**
+ * Error thrown when plugin operations fail
+ */
+export class PluginError extends Error {
+    pluginName;
+    reason;
+    constructor(message, pluginName, reason) {
+        super(message);
+        this.pluginName = pluginName;
+        this.reason = reason;
+        this.name = 'PluginError';
+    }
+}
+/**
+ * Plugin Manager
+ *
+ * Handles plugin loading, unloading, and tool management.
+ * Supports namespace-based tool isolation, dependency injection, and dependency resolution.
+ */
+export class PluginManager {
+    plugins = new Map();
+    allTools = new Map();
+    options;
+    context;
+    loadingPlugins = new Set(); // Track plugins currently being loaded (for circular dependency detection)
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_PLUGIN_MANAGER_OPTIONS, ...options };
+    }
+    /**
+     * Set the plugin context for dependency injection
+     */
+    setContext(context) {
+        this.context = context;
+    }
+    /**
+     * Load a plugin
+     *
+     * @param plugin - The plugin to load
+     * @throws PluginError if loading fails
+     */
+    async load(plugin) {
+        // Validate plugin
+        if (this.options.strictValidation) {
+            this.validatePlugin(plugin);
+        }
+        // Check for duplicate plugin
+        if (this.plugins.has(plugin.name)) {
+            throw new PluginError(`Plugin already loaded: ${plugin.name}`, plugin.name, 'A plugin with this name is already loaded');
+        }
+        // Check for circular dependencies
+        if (this.loadingPlugins.has(plugin.name)) {
+            throw new PluginError(`Circular dependency detected for plugin: ${plugin.name}`, plugin.name, 'Plugin has a circular dependency');
+        }
+        // Load dependencies first
+        if (plugin.dependencies && plugin.dependencies.length > 0) {
+            this.loadingPlugins.add(plugin.name);
+            try {
+                await this.loadDependencies(plugin);
+            }
+            finally {
+                this.loadingPlugins.delete(plugin.name);
+            }
+        }
+        // Create plugin state
+        const state = {
+            plugin,
+            status: 'loading',
+            tools: new Map(),
+        };
+        this.plugins.set(plugin.name, state);
+        try {
+            // Call lifecycle hooks (initialize/onLoad) if defined
+            // Support both naming conventions for backward compatibility
+            const initHook = plugin.initialize || plugin.onLoad;
+            if (initHook && this.context) {
+                await initHook.call(plugin, this.context);
+            }
+            // Register tools with namespace
+            for (const tool of plugin.tools) {
+                const namespacedName = this.getNamespacedToolName(tool.name, plugin.namespace);
+                // Check for conflicts
+                if (this.allTools.has(namespacedName)) {
+                    this.handleConflict(namespacedName, plugin.name);
+                    if (this.options.conflictStrategy === 'skip') {
+                        continue;
+                    }
+                }
+                // Create namespaced tool
+                const namespacedTool = {
+                    ...tool,
+                    name: namespacedName,
+                };
+                state.tools.set(namespacedName, namespacedTool);
+                this.allTools.set(namespacedName, namespacedTool);
+            }
+            state.status = 'loaded';
+        }
+        catch (error) {
+            state.status = 'error';
+            state.error = error instanceof Error ? error.message : String(error);
+            // Cleanup any registered tools
+            for (const toolName of state.tools.keys()) {
+                this.allTools.delete(toolName);
+            }
+            state.tools.clear();
+            throw new PluginError(`Failed to load plugin: ${plugin.name}`, plugin.name, state.error);
+        }
+    }
+    /**
+     * Load plugin dependencies
+     * @private
+     */
+    async loadDependencies(plugin) {
+        if (!plugin.dependencies || plugin.dependencies.length === 0) {
+            return;
+        }
+        for (const depName of plugin.dependencies) {
+            if (!this.plugins.has(depName)) {
+                throw new PluginError(`Missing dependency for plugin ${plugin.name}: ${depName}`, plugin.name, `Plugin ${depName} must be loaded before ${plugin.name}`);
+            }
+            const depState = this.plugins.get(depName);
+            if (depState?.status !== 'loaded') {
+                throw new PluginError(`Dependency not ready for plugin ${plugin.name}: ${depName}`, plugin.name, `Plugin ${depName} is in status ${depState?.status}`);
+            }
+        }
+    }
+    /**
+     * Unload a plugin
+     *
+     * @param pluginName - Name of the plugin to unload
+     * @returns true if unloaded, false if not found
+     */
+    async unload(pluginName) {
+        const state = this.plugins.get(pluginName);
+        if (!state) {
+            return false;
+        }
+        try {
+            // Call lifecycle hooks (cleanup/onUnload) if defined
+            // Support both naming conventions for backward compatibility
+            const cleanupHook = state.plugin.cleanup || state.plugin.onUnload;
+            if (cleanupHook) {
+                await cleanupHook.call(state.plugin);
+            }
+        }
+        catch (error) {
+            // Log but don't throw - we still want to clean up
+            console.error(`Error during plugin unload: ${pluginName}`, error);
+        }
+        // Remove all tools
+        for (const toolName of state.tools.keys()) {
+            this.allTools.delete(toolName);
+        }
+        // Remove plugin
+        this.plugins.delete(pluginName);
+        return true;
+    }
+    /**
+     * Get a plugin by name
+     */
+    getPlugin(name) {
+        return this.plugins.get(name)?.plugin;
+    }
+    /**
+     * Check if a plugin is loaded
+     */
+    hasPlugin(name) {
+        return this.plugins.has(name);
+    }
+    /**
+     * List all loaded plugins
+     */
+    listPlugins() {
+        return Array.from(this.plugins.values()).map((state) => ({
+            name: state.plugin.name,
+            version: state.plugin.version,
+            description: state.plugin.description,
+            namespace: state.plugin.namespace,
+            toolCount: state.tools.size,
+            toolNames: Array.from(state.tools.keys()),
+            status: state.status,
+            error: state.error,
+        }));
+    }
+    /**
+     * Get a tool by name
+     */
+    getTool(name) {
+        return this.allTools.get(name);
+    }
+    /**
+     * Check if a tool exists
+     */
+    hasTool(name) {
+        return this.allTools.has(name);
+    }
+    /**
+     * List all tools
+     */
+    listTools() {
+        return Array.from(this.allTools.values());
+    }
+    /**
+     * List tool names
+     */
+    listToolNames() {
+        return Array.from(this.allTools.keys());
+    }
+    /**
+     * Get tool definitions for LLM Function Calling
+     */
+    getToolDefinitions() {
+        return this.listTools().map((tool) => toolToDefinition(tool));
+    }
+    /**
+     * Get the number of loaded plugins
+     */
+    get pluginCount() {
+        return this.plugins.size;
+    }
+    /**
+     * Get the number of registered tools
+     */
+    get toolCount() {
+        return this.allTools.size;
+    }
+    /**
+     * Clear all plugins
+     */
+    async clear() {
+        const pluginNames = Array.from(this.plugins.keys());
+        for (const name of pluginNames) {
+            await this.unload(name);
+        }
+    }
+    /**
+     * Run health checks on all plugins
+     */
+    async healthCheck() {
+        const results = new Map();
+        for (const [name, state] of this.plugins) {
+            if (state.plugin.healthCheck) {
+                try {
+                    results.set(name, await state.plugin.healthCheck());
+                }
+                catch {
+                    results.set(name, false);
+                }
+            }
+            else {
+                results.set(name, state.status === 'loaded');
+            }
+        }
+        return results;
+    }
+    /**
+     * Get namespaced tool name
+     */
+    getNamespacedToolName(toolName, namespace) {
+        if (!this.options.autoNamespace || !namespace) {
+            return toolName;
+        }
+        return `${namespace}_${toolName}`;
+    }
+    /**
+     * Handle tool name conflict
+     */
+    handleConflict(toolName, pluginName) {
+        switch (this.options.conflictStrategy) {
+            case 'error':
+                throw new PluginError(`Tool name conflict: ${toolName}`, pluginName, 'A tool with this name already exists');
+            case 'replace':
+                // Will be replaced in the calling code
+                break;
+            case 'skip':
+                // Will be skipped in the calling code
+                break;
+        }
+    }
+    /**
+     * Validate plugin definition
+     */
+    validatePlugin(plugin) {
+        if (!plugin.name || typeof plugin.name !== 'string') {
+            throw new PluginError('Invalid plugin name', plugin.name || 'unknown', 'Plugin name must be a non-empty string');
+        }
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(plugin.name)) {
+            throw new PluginError(`Invalid plugin name format: ${plugin.name}`, plugin.name, 'Plugin name must start with a letter and contain only alphanumeric characters, underscores, and hyphens');
+        }
+        if (!plugin.version || typeof plugin.version !== 'string') {
+            throw new PluginError(`Invalid plugin version for ${plugin.name}`, plugin.name, 'Plugin version must be a non-empty string');
+        }
+        if (!plugin.description || typeof plugin.description !== 'string') {
+            throw new PluginError(`Invalid plugin description for ${plugin.name}`, plugin.name, 'Plugin description must be a non-empty string');
+        }
+        if (!Array.isArray(plugin.tools)) {
+            throw new PluginError(`Invalid tools for plugin ${plugin.name}`, plugin.name, 'Plugin tools must be an array');
+        }
+        // Validate each tool
+        for (const tool of plugin.tools) {
+            this.validateTool(tool, plugin.name);
+        }
+        // Validate namespace format if provided
+        if (plugin.namespace && !/^[a-zA-Z][a-zA-Z0-9_]*$/.test(plugin.namespace)) {
+            throw new PluginError(`Invalid namespace format for plugin ${plugin.name}`, plugin.name, 'Namespace must start with a letter and contain only alphanumeric characters and underscores');
+        }
+        // Validate dependencies if provided
+        if (plugin.dependencies) {
+            if (!Array.isArray(plugin.dependencies)) {
+                throw new PluginError(`Invalid dependencies for plugin ${plugin.name}`, plugin.name, 'Plugin dependencies must be an array');
+            }
+            for (const dep of plugin.dependencies) {
+                if (typeof dep !== 'string' || !dep) {
+                    throw new PluginError(`Invalid dependency in plugin ${plugin.name}`, plugin.name, 'Each dependency must be a non-empty string');
+                }
+            }
+        }
+    }
+    /**
+     * Validate tool definition
+     */
+    validateTool(tool, pluginName) {
+        if (!tool.name || typeof tool.name !== 'string') {
+            throw new PluginError(`Invalid tool name in plugin ${pluginName}`, pluginName, 'Tool name must be a non-empty string');
+        }
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(tool.name)) {
+            throw new PluginError(`Invalid tool name format in plugin ${pluginName}: ${tool.name}`, pluginName, 'Tool name must start with a letter and contain only alphanumeric characters, underscores, and hyphens');
+        }
+        if (!tool.description || typeof tool.description !== 'string') {
+            throw new PluginError(`Invalid tool description in plugin ${pluginName}: ${tool.name}`, pluginName, 'Tool description must be a non-empty string');
+        }
+        if (!Array.isArray(tool.parameters)) {
+            throw new PluginError(`Invalid tool parameters in plugin ${pluginName}: ${tool.name}`, pluginName, 'Tool parameters must be an array');
+        }
+        // Validate each parameter
+        for (const param of tool.parameters) {
+            if (!param.name || typeof param.name !== 'string' || param.name.trim() === '') {
+                throw new PluginError(`Invalid parameter name in tool ${tool.name} of plugin ${pluginName}`, pluginName, 'Parameter name must be a non-empty string');
+            }
+            if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(param.name)) {
+                throw new PluginError(`Invalid parameter name format "${param.name}" in tool ${tool.name} of plugin ${pluginName}`, pluginName, 'Parameter name must start with a letter and contain only alphanumeric characters and underscores');
+            }
+            if (!param.type || typeof param.type !== 'string') {
+                throw new PluginError(`Invalid parameter type in tool ${tool.name} of plugin ${pluginName}`, pluginName, 'Parameter type must be a non-empty string');
+            }
+            const validTypes = ['string', 'number', 'boolean', 'object', 'array'];
+            if (!validTypes.includes(param.type)) {
+                throw new PluginError(`Invalid parameter type "${param.type}" in tool ${tool.name} of plugin ${pluginName}`, pluginName, `Parameter type must be one of: ${validTypes.join(', ')}`);
+            }
+            if (typeof param.required !== 'boolean') {
+                throw new PluginError(`Invalid parameter required field in tool ${tool.name} of plugin ${pluginName}`, pluginName, 'Parameter required field must be a boolean');
+            }
+        }
+        if (typeof tool.execute !== 'function') {
+            throw new PluginError(`Invalid tool execute function in plugin ${pluginName}: ${tool.name}`, pluginName, 'Tool execute must be a function');
+        }
+    }
+}
+//# sourceMappingURL=plugin-manager.js.map

package/dist/core/plugin-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manager.js","sourceRoot":"","sources":["../../src/core/plugin-manager.ts"],"names":[],"mappings":"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"}

package/dist/core/response-handler.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Response Handler
+ *
+ * Generates appropriate responses based on execution results,
+ * knowledge assessment, and user interaction needs.
+ *
+ * _Requirements: 1.4, 5.1-5.5_
+ */
+import type { LLMManager } from '../llm/manager.js';
+import type { ChatMessage } from '../llm/adapter.js';
+import type { AgentResponse, ExecuteResponse, ToolCallRecord } from '../types/response.js';
+import type { KnowledgeAssessment, SearchResult } from '../types/knowledge.js';
+import type { ToolExecutionResult } from './tool-executor.js';
+import type { ExecutionPlan } from './plan-generator.js';
+import type { DetailedIntent } from './intent-parser.js';
+/**
+ * Response handler configuration
+ */
+export interface ResponseHandlerConfig {
+    /** System prompt for response generation */
+    systemPrompt?: string;
+    /** Whether to include tool call details in responses */
+    includeToolDetails?: boolean;
+    /** Maximum response length */
+    maxResponseLength?: number;
+}
+/**
+ * Context for response generation
+ */
+export interface ResponseContext {
+    /** Original user message */
+    userMessage: string;
+    /** Parsed intent */
+    intent: DetailedIntent;
+    /** Knowledge assessment */
+    knowledgeAssessment?: KnowledgeAssessment;
+    /** Search results */
+    searchResults?: SearchResult[];
+    /** Execution plan */
+    plan?: ExecutionPlan;
+    /** Tool execution results */
+    executionResults?: ToolExecutionResult[];
+    /** Conversation history */
+    history?: ChatMessage[];
+}
+/**
+ * Response Handler
+ *
+ * Determines the appropriate response type and generates responses
+ * based on the current state of agent processing.
+ */
+export declare class ResponseHandler {
+    private llmManager;
+    private config;
+    constructor(llmManager: LLMManager, config?: ResponseHandlerConfig);
+    /**
+     * Generate an appropriate response based on context
+     */
+    generateResponse(context: ResponseContext): Promise<AgentResponse>;
+    /**
+     * Check if knowledge request is needed
+     */
+    private shouldRequestKnowledge;
+    /**
+     * Check if clarification is needed
+     */
+    private shouldRequestClarification;
+    /**
+     * Check if confirmation is needed
+     */
+    private shouldRequestConfirmation;
+    /**
+     * Check if options should be presented
+     */
+    private shouldPresentOptions;
+    /**
+     * Create a knowledge request response
+     */
+    private createKnowledgeRequestResponse;
+    /**
+     * Create a clarify response
+     */
+    private createClarifyResponse;
+    /**
+     * Generate clarifying questions using LLM
+     */
+    private generateClarifyingQuestions;
+    /**
+     * Create a confirm response
+     */
+    private createConfirmResponse;
+    /**
+     * Generate a preview of the execution plan
+     */
+    private generatePlanPreview;
+    /**
+     * Create an options response
+     */
+    private createOptionsResponse;
+    /**
+     * Create an execute response
+     */
+    private createExecuteResponse;
+    /**
+     * Build tool call records from execution results
+     */
+    private buildToolCallRecords;
+    /**
+     * Generate execute response message using LLM
+     */
+    private generateExecuteMessage;
+    /**
+     * Build prompt for execute message generation
+     */
+    private buildExecuteMessagePrompt;
+    /**
+     * Generate message when no action was taken
+     */
+    private generateNoActionMessage;
+    /**
+     * Generate fallback message when LLM fails
+     */
+    private generateFallbackMessage;
+    /**
+     * Collect data from execution results
+     */
+    private collectExecutionData;
+    /**
+     * Create a simple execute response without LLM
+     */
+    createSimpleExecuteResponse(message: string, data?: unknown, toolCalls?: ToolCallRecord[]): ExecuteResponse;
+    /**
+     * Create an error response
+     */
+    createErrorResponse(error: Error | string): ExecuteResponse;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<ResponseHandlerConfig>;
+}
+//# sourceMappingURL=response-handler.d.ts.map

package/dist/core/response-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-handler.d.ts","sourceRoot":"","sources":["../../src/core/response-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAKf,cAAc,EAGf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAOD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,2BAA2B;IAC3B,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,qBAAqB;IACrB,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,qBAAqB;IACrB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,6BAA6B;IAC7B,gBAAgB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACzC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAkC;gBAEpC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,qBAAqB;IASlE;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCxE;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAmBlC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,8BAA8B;IA0CtC;;OAEG;YACW,qBAAqB;IAUnC;;OAEG;YACW,2BAA2B;IAoCzC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;OAEG;YACW,qBAAqB;IAkBnC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;YACW,sBAAsB;IAiCpC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA0BjC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;IACH,2BAA2B,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,cAAc,EAAE,GAC3B,eAAe;IASlB;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,eAAe;IAS3D;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC;CAG7C"}