@agenticc/core 1.0.0

package/dist/core/tool-executor.js

@@ -0,0 +1,354 @@
+/**
+ * Tool Executor
+ *
+ * Handles the execution of tools with parameter validation,
+ * context injection, and error handling.
+ *
+ * @module core/tool-executor
+ */
+import { ToolNotFoundError } from './tool-registry.js';
+/**
+ * Error thrown when tool parameter validation fails
+ */
+export class ToolValidationError extends Error {
+    toolName;
+    parameterName;
+    reason;
+    constructor(message, toolName, parameterName, reason) {
+        super(message);
+        this.toolName = toolName;
+        this.parameterName = parameterName;
+        this.reason = reason;
+        this.name = 'ToolValidationError';
+    }
+}
+/**
+ * Error thrown when tool execution fails
+ */
+export class ToolExecutionError extends Error {
+    toolName;
+    cause;
+    constructor(message, toolName, cause) {
+        super(message);
+        this.toolName = toolName;
+        this.cause = cause;
+        this.name = 'ToolExecutionError';
+    }
+}
+/**
+ * Error thrown when tool execution times out
+ */
+export class ToolTimeoutError extends Error {
+    toolName;
+    timeoutMs;
+    constructor(toolName, timeoutMs) {
+        super(`Tool execution timed out after ${timeoutMs}ms: ${toolName}`);
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ToolTimeoutError';
+    }
+}
+/**
+ * Default logger implementation
+ */
+const defaultLogger = {
+    info: (message, data) => {
+        console.log(`[INFO] ${message}`, data ?? '');
+    },
+    warn: (message, data) => {
+        console.warn(`[WARN] ${message}`, data ?? '');
+    },
+    error: (message, data) => {
+        console.error(`[ERROR] ${message}`, data ?? '');
+    },
+    debug: (message, data) => {
+        console.debug(`[DEBUG] ${message}`, data ?? '');
+    },
+};
+/**
+ * Validates a single parameter value against its definition
+ */
+function validateParameterValue(param, value, toolName) {
+    // Check required parameters
+    if (param.required && (value === undefined || value === null)) {
+        throw new ToolValidationError(`Missing required parameter: ${param.name}`, toolName, param.name, 'Parameter is required but was not provided');
+    }
+    // Skip validation for optional parameters that are not provided
+    if (value === undefined || value === null) {
+        return;
+    }
+    // Type validation
+    const actualType = Array.isArray(value) ? 'array' : typeof value;
+    // Handle type mapping
+    const expectedType = param.type;
+    if (expectedType === 'object' && actualType === 'object' && !Array.isArray(value)) {
+        // Valid object
+    }
+    else if (expectedType === 'array' && Array.isArray(value)) {
+        // Valid array
+    }
+    else if (expectedType === actualType) {
+        // Direct type match
+    }
+    else {
+        throw new ToolValidationError(`Invalid type for parameter ${param.name}: expected ${param.type}, got ${actualType}`, toolName, param.name, `Expected type ${param.type} but received ${actualType}`);
+    }
+    // Enum validation
+    if (param.enum && param.enum.length > 0) {
+        if (!param.enum.includes(String(value))) {
+            throw new ToolValidationError(`Invalid value for parameter ${param.name}: must be one of [${param.enum.join(', ')}]`, toolName, param.name, `Value must be one of: ${param.enum.join(', ')}`);
+        }
+    }
+}
+/**
+ * Validates all parameters for a tool
+ */
+function validateParameters(tool, args) {
+    const validatedArgs = {};
+    // Validate each defined parameter
+    for (const param of tool.parameters) {
+        const value = args[param.name];
+        validateParameterValue(param, value, tool.name);
+        // Use provided value or default
+        if (value !== undefined && value !== null) {
+            validatedArgs[param.name] = value;
+        }
+        else if (param.default !== undefined) {
+            validatedArgs[param.name] = param.default;
+        }
+    }
+    // Check for unknown parameters
+    const knownParams = new Set(tool.parameters.map((p) => p.name));
+    for (const key of Object.keys(args)) {
+        if (!knownParams.has(key)) {
+            // Include unknown parameters but log a warning
+            validatedArgs[key] = args[key];
+        }
+    }
+    return validatedArgs;
+}
+/**
+ * Creates a promise that rejects after a timeout
+ */
+function createTimeout(ms, toolName) {
+    return new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new ToolTimeoutError(toolName, ms));
+        }, ms);
+    });
+}
+/**
+ * Tool Executor
+ *
+ * Executes tools with parameter validation, context injection,
+ * timeout handling, and error management.
+ */
+export class ToolExecutor {
+    registry;
+    options;
+    contextProvider;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.options = {
+            defaultTimeout: options.defaultTimeout ?? 30000,
+            strictValidation: options.strictValidation ?? true,
+        };
+    }
+    /**
+     * Set the context provider for tool execution
+     */
+    setContextProvider(provider) {
+        this.contextProvider = provider;
+    }
+    /**
+     * Create a tool context from the provider or defaults
+     */
+    createContext(sessionId) {
+        if (this.contextProvider) {
+            return {
+                knowledgeBase: this.contextProvider.getKnowledgeBase(),
+                sessionId: sessionId ?? this.contextProvider.getSessionId(),
+                logger: this.contextProvider.getLogger(),
+            };
+        }
+        // Return a minimal context if no provider is set
+        return {
+            knowledgeBase: {
+                addDocument: async () => '',
+                getDocument: async () => null,
+                deleteDocument: async () => false,
+                search: async () => [],
+                listCategories: async () => [],
+                getDocumentsByCategory: async () => [],
+            },
+            sessionId: sessionId ?? 'default',
+            logger: defaultLogger,
+        };
+    }
+    /**
+     * Execute a tool by name with the given arguments
+     *
+     * @param toolName - Name of the tool to execute
+     * @param args - Arguments to pass to the tool
+     * @param options - Execution options
+     * @returns The execution result
+     */
+    async execute(toolName, args, options) {
+        const startTime = Date.now();
+        const timeout = options?.timeout ?? this.options.defaultTimeout;
+        // Get the tool
+        const tool = this.registry.get(toolName);
+        if (!tool) {
+            const error = new ToolNotFoundError(toolName);
+            return {
+                result: {
+                    success: false,
+                    content: `Tool not found: ${toolName}`,
+                    error: {
+                        code: 'TOOL_NOT_FOUND',
+                        message: error.message,
+                    },
+                },
+                toolName,
+                arguments: args,
+                durationMs: Date.now() - startTime,
+                success: false,
+                error,
+            };
+        }
+        // Validate parameters
+        let validatedArgs;
+        try {
+            validatedArgs = this.options.strictValidation ? validateParameters(tool, args) : args;
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError) {
+                return {
+                    result: {
+                        success: false,
+                        content: error.message,
+                        error: {
+                            code: 'VALIDATION_ERROR',
+                            message: error.message,
+                            details: {
+                                parameter: error.parameterName,
+                                reason: error.reason,
+                            },
+                        },
+                    },
+                    toolName,
+                    arguments: args,
+                    durationMs: Date.now() - startTime,
+                    success: false,
+                    error,
+                };
+            }
+            throw error;
+        }
+        // Create context
+        const context = this.createContext(options?.sessionId);
+        // Execute with timeout
+        try {
+            const result = await Promise.race([
+                tool.execute(validatedArgs, context),
+                createTimeout(timeout, toolName),
+            ]);
+            return {
+                result,
+                toolName,
+                arguments: validatedArgs,
+                durationMs: Date.now() - startTime,
+                success: result.success,
+            };
+        }
+        catch (error) {
+            const execError = error instanceof Error ? error : new Error(String(error));
+            // Handle timeout
+            if (error instanceof ToolTimeoutError) {
+                return {
+                    result: {
+                        success: false,
+                        content: `Tool execution timed out after ${timeout}ms`,
+                        error: {
+                            code: 'TIMEOUT',
+                            message: execError.message,
+                        },
+                    },
+                    toolName,
+                    arguments: validatedArgs,
+                    durationMs: Date.now() - startTime,
+                    success: false,
+                    error: execError,
+                };
+            }
+            // Handle other errors
+            return {
+                result: {
+                    success: false,
+                    content: `Tool execution failed: ${execError.message}`,
+                    error: {
+                        code: 'EXECUTION_ERROR',
+                        message: execError.message,
+                        details: execError.stack,
+                    },
+                },
+                toolName,
+                arguments: validatedArgs,
+                durationMs: Date.now() - startTime,
+                success: false,
+                error: new ToolExecutionError(`Tool execution failed: ${execError.message}`, toolName, execError),
+            };
+        }
+    }
+    /**
+     * Execute multiple tools in sequence
+     *
+     * @param calls - Array of tool calls to execute
+     * @param options - Execution options
+     * @returns Array of execution results
+     */
+    async executeSequence(calls, options) {
+        const results = [];
+        const stopOnError = options?.stopOnError ?? false;
+        for (const call of calls) {
+            const result = await this.execute(call.toolName, call.args, {
+                sessionId: options?.sessionId,
+                timeout: options?.timeout,
+            });
+            results.push(result);
+            if (stopOnError && !result.success) {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Execute multiple tools in parallel
+     *
+     * @param calls - Array of tool calls to execute
+     * @param options - Execution options
+     * @returns Array of execution results
+     */
+    async executeParallel(calls, options) {
+        const promises = calls.map((call) => this.execute(call.toolName, call.args, {
+            sessionId: options?.sessionId,
+            timeout: options?.timeout,
+        }));
+        return Promise.all(promises);
+    }
+    /**
+     * Check if a tool requires confirmation before execution
+     */
+    requiresConfirmation(toolName) {
+        const tool = this.registry.get(toolName);
+        return tool?.requiresConfirmation ?? false;
+    }
+    /**
+     * Get the risk level of a tool
+     */
+    getRiskLevel(toolName) {
+        const tool = this.registry.get(toolName);
+        return tool?.riskLevel;
+    }
+}
+//# sourceMappingURL=tool-executor.js.map

package/dist/core/tool-executor.js.map

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

package/dist/core/tool-registry.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Tool Registry
+ *
+ * Manages registration and retrieval of tools for the Agent.
+ * Validates tool definitions and provides Function Calling format conversion.
+ *
+ * @module core/tool-registry
+ */
+import type { Tool, ToolDefinition } from '../types/tool.js';
+/**
+ * Error thrown when tool registration fails
+ */
+export declare class ToolRegistrationError extends Error {
+    readonly toolName: string;
+    readonly reason: string;
+    constructor(message: string, toolName: string, reason: string);
+}
+/**
+ * Error thrown when a tool is not found
+ */
+export declare class ToolNotFoundError extends Error {
+    constructor(toolName: string);
+}
+/**
+ * Options for tool registration behavior
+ */
+export interface ToolRegistryOptions {
+    /** Whether to allow replacing existing tools (default: false) */
+    allowReplace?: boolean;
+    /** Whether to validate tool definitions strictly (default: true) */
+    strictValidation?: boolean;
+}
+/**
+ * Registry for managing Agent tools
+ *
+ * Provides methods to register, retrieve, and list tools.
+ * Ensures tool uniqueness and validates definitions.
+ */
+export declare class ToolRegistry {
+    private tools;
+    private options;
+    constructor(options?: ToolRegistryOptions);
+    /**
+     * Register a tool with the registry
+     *
+     * @param tool - The tool to register
+     * @throws ToolRegistrationError if validation fails or tool already exists
+     */
+    register(tool: Tool): void;
+    /**
+     * Register multiple tools at once
+     *
+     * @param tools - Array of tools to register
+     * @throws ToolRegistrationError if any tool fails validation
+     */
+    registerAll(tools: Tool[]): void;
+    /**
+     * Get a tool by name
+     *
+     * @param name - The tool name
+     * @returns The tool if found, undefined otherwise
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Get a tool by name, throwing if not found
+     *
+     * @param name - The tool name
+     * @returns The tool
+     * @throws ToolNotFoundError if tool doesn't exist
+     */
+    getOrThrow(name: string): Tool;
+    /**
+     * Check if a tool is registered
+     *
+     * @param name - The tool name
+     * @returns true if the tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a tool from the registry
+     *
+     * @param name - The tool name
+     * @returns true if the tool was removed, false if it didn't exist
+     */
+    unregister(name: string): boolean;
+    /**
+     * List all registered tools
+     *
+     * @returns Array of all registered tools
+     */
+    list(): Tool[];
+    /**
+     * List tool names
+     *
+     * @returns Array of registered tool names
+     */
+    listNames(): string[];
+    /**
+     * List tools by category
+     *
+     * @param category - The category to filter by
+     * @returns Array of tools in the specified category
+     */
+    listByCategory(category: string): Tool[];
+    /**
+     * Get all unique categories
+     *
+     * @returns Array of unique category names
+     */
+    getCategories(): string[];
+    /**
+     * Get tool definitions in Function Calling format
+     *
+     * @returns Array of tool definitions for LLM APIs
+     */
+    getDefinitions(): ToolDefinition[];
+    /**
+     * Get tool definitions for specific tools
+     *
+     * @param names - Array of tool names to get definitions for
+     * @returns Array of tool definitions
+     */
+    getDefinitionsFor(names: string[]): ToolDefinition[];
+    /**
+     * Get the number of registered tools
+     */
+    get size(): number;
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/core/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/core/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAiB,MAAM,kBAAkB,CAAC;AAG5E;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAKjC;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,QAAQ,EAAE,MAAM;CAI7B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AA4HD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,OAAO,CAAgC;gBAEnC,OAAO,GAAE,mBAAwB;IAO7C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAoB1B;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAMhC;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAInC;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;OAIG;IACH,IAAI,IAAI,IAAI,EAAE;IAId;;;;OAIG;IACH,SAAS,IAAI,MAAM,EAAE;IAIrB;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE;IAIxC;;;;OAIG;IACH,aAAa,IAAI,MAAM,EAAE;IAUzB;;;;OAIG;IACH,cAAc,IAAI,cAAc,EAAE;IAIlC;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE;IAOpD;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}