@codebolt/agent 1.1.0 → 2.2.2

package/dist/composablepattern/memory.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Memory and Storage implementations for Composable Agent Pattern
+ * @description Provides memory management and various storage providers for agent conversations
+ */
+import type { MemoryConfig, StorageProvider, Message } from './types';
+import { type CodeBoltStoreConfig } from './codebolt-storage';
+/**
+ * Memory management for agent conversations
+ */
+export declare class Memory {
+    private storage;
+    private maxMessages;
+    private autoSave;
+    private conversationKey;
+    constructor(config: MemoryConfig);
+    /**
+     * Save messages to storage
+     *
+     * @param messages - Array of messages to save
+     * @param key - Optional key for storage (defaults to conversation_history)
+     */
+    saveMessages(messages: Message[], key?: string): Promise<void>;
+    /**
+     * Load messages from storage
+     *
+     * @param key - Optional key for storage (defaults to conversation_history)
+     * @returns Array of loaded messages
+     */
+    loadMessages(key?: string): Promise<Message[]>;
+    /**
+     * Add a message to the conversation and optionally save
+     *
+     * @param message - Message to add
+     * @param messages - Current messages array
+     * @param save - Whether to auto-save to storage
+     * @returns Updated messages array
+     */
+    addMessage(message: Message, messages: Message[], save?: boolean): Promise<Message[]>;
+    /**
+     * Clear conversation history
+     *
+     * @param key - Optional key for storage (defaults to conversation_history)
+     */
+    clearMessages(key?: string): Promise<void>;
+    /**
+     * Get storage provider for custom operations
+     */
+    getStorage(): StorageProvider;
+    /**
+     * Set conversation key for multi-conversation support
+     *
+     * @param key - New conversation key
+     */
+    setConversationKey(key: string): void;
+    /**
+     * List all conversation keys
+     *
+     * @returns Array of conversation keys
+     */
+    listConversations(): Promise<string[]>;
+}
+/**
+ * Create a Memory instance with CodeBolt backend storage
+ *
+ * @param config - CodeBolt storage configuration
+ * @returns Memory instance
+ */
+export declare function createCodeBoltMemory(config: CodeBoltStoreConfig): Memory;
+/**
+ * Create a Memory instance with CodeBolt agent state storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+export declare function createCodeBoltAgentMemory(prefix?: string): Memory;
+/**
+ * Create a Memory instance with CodeBolt project state storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+export declare function createCodeBoltProjectMemory(prefix?: string): Memory;
+/**
+ * Create a Memory instance with CodeBolt memory database storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+export declare function createCodeBoltDbMemory(prefix?: string): Memory;

package/dist/composablepattern/memory.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * @fileoverview Memory and Storage implementations for Composable Agent Pattern
+ * @description Provides memory management and various storage providers for agent conversations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Memory = void 0;
+exports.createCodeBoltMemory = createCodeBoltMemory;
+exports.createCodeBoltAgentMemory = createCodeBoltAgentMemory;
+exports.createCodeBoltProjectMemory = createCodeBoltProjectMemory;
+exports.createCodeBoltDbMemory = createCodeBoltDbMemory;
+const codebolt_storage_1 = require("./codebolt-storage");
+/**
+ * Memory management for agent conversations
+ */
+class Memory {
+    constructor(config) {
+        var _a;
+        this.conversationKey = 'conversation_history';
+        this.storage = config.storage;
+        this.maxMessages = config.maxMessages || 100;
+        this.autoSave = (_a = config.autoSave) !== null && _a !== void 0 ? _a : true;
+    }
+    /**
+     * Save messages to storage
+     *
+     * @param messages - Array of messages to save
+     * @param key - Optional key for storage (defaults to conversation_history)
+     */
+    async saveMessages(messages, key) {
+        const storageKey = key || this.conversationKey;
+        // Trim messages if they exceed max limit
+        const trimmedMessages = this.maxMessages > 0 && messages.length > this.maxMessages
+            ? messages.slice(-this.maxMessages)
+            : messages;
+        await this.storage.set(storageKey, trimmedMessages);
+    }
+    /**
+     * Load messages from storage
+     *
+     * @param key - Optional key for storage (defaults to conversation_history)
+     * @returns Array of loaded messages
+     */
+    async loadMessages(key) {
+        const storageKey = key || this.conversationKey;
+        const messages = await this.storage.get(storageKey);
+        return Array.isArray(messages) ? messages : [];
+    }
+    /**
+     * Add a message to the conversation and optionally save
+     *
+     * @param message - Message to add
+     * @param messages - Current messages array
+     * @param save - Whether to auto-save to storage
+     * @returns Updated messages array
+     */
+    async addMessage(message, messages, save = this.autoSave) {
+        const updatedMessages = [...messages, message];
+        if (save) {
+            await this.saveMessages(updatedMessages);
+        }
+        return updatedMessages;
+    }
+    /**
+     * Clear conversation history
+     *
+     * @param key - Optional key for storage (defaults to conversation_history)
+     */
+    async clearMessages(key) {
+        const storageKey = key || this.conversationKey;
+        await this.storage.delete(storageKey);
+    }
+    /**
+     * Get storage provider for custom operations
+     */
+    getStorage() {
+        return this.storage;
+    }
+    /**
+     * Set conversation key for multi-conversation support
+     *
+     * @param key - New conversation key
+     */
+    setConversationKey(key) {
+        this.conversationKey = key;
+    }
+    /**
+     * List all conversation keys
+     *
+     * @returns Array of conversation keys
+     */
+    async listConversations() {
+        const allKeys = await this.storage.keys();
+        return allKeys.filter(key => key.includes('conversation') || key.includes('history'));
+    }
+}
+exports.Memory = Memory;
+/**
+ * Create a Memory instance with CodeBolt backend storage
+ *
+ * @param config - CodeBolt storage configuration
+ * @returns Memory instance
+ */
+function createCodeBoltMemory(config) {
+    return new Memory({
+        storage: (0, codebolt_storage_1.createCodeBoltStore)(config)
+    });
+}
+/**
+ * Create a Memory instance with CodeBolt agent state storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+function createCodeBoltAgentMemory(prefix) {
+    return new Memory({
+        storage: (0, codebolt_storage_1.createCodeBoltStore)({ type: 'agent', prefix })
+    });
+}
+/**
+ * Create a Memory instance with CodeBolt project state storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+function createCodeBoltProjectMemory(prefix) {
+    return new Memory({
+        storage: (0, codebolt_storage_1.createCodeBoltStore)({ type: 'project', prefix })
+    });
+}
+/**
+ * Create a Memory instance with CodeBolt memory database storage
+ *
+ * @param prefix - Optional prefix for storage keys
+ * @returns Memory instance
+ */
+function createCodeBoltDbMemory(prefix) {
+    return new Memory({
+        storage: (0, codebolt_storage_1.createCodeBoltStore)({ type: 'memory', prefix })
+    });
+}

package/dist/composablepattern/tool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Tool creation and management for Composable Agent Pattern
+ * @description Provides utilities for creating and managing tools in the composable agent framework
+ */
+import type { Tool, ToolConfig } from './types';
+/**
+ * Creates a new tool with input/output validation and execution logic
+ *
+ * @template TInput - Type for tool input parameters
+ * @template TOutput - Type for tool output
+ * @param config - Tool configuration object
+ * @returns Fully configured tool with validation methods
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = createTool({
+ *   id: 'get-weather',
+ *   description: 'Get current weather for a location',
+ *   inputSchema: z.object({
+ *     location: z.string().describe('City name'),
+ *   }),
+ *   outputSchema: z.object({
+ *     temperature: z.number(),
+ *     conditions: z.string(),
+ *     location: z.string(),
+ *   }),
+ *   execute: async ({ context }) => {
+ *     return await getWeather(context.location);
+ *   },
+ * });
+ * ```
+ */
+export declare function createTool<TInput = any, TOutput = any>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+/**
+ * Converts a tool to OpenAI function format for LLM usage
+ *
+ * @param tool - The tool to convert
+ * @returns OpenAI function specification
+ */
+export declare function toolToOpenAIFunction(tool: Tool): any;
+/**
+ * Converts multiple tools to OpenAI functions format
+ *
+ * @param tools - Record of tools to convert
+ * @returns Array of OpenAI function specifications
+ */
+export declare function toolsToOpenAIFunctions(tools: Record<string, Tool>): any[];
+/**
+ * Executes a tool with proper error handling and validation
+ *
+ * @param tool - The tool to execute
+ * @param input - Input parameters for the tool
+ * @param agent - Optional agent instance for context
+ * @returns Tool execution result
+ */
+export declare function executeTool<TInput, TOutput>(tool: Tool<TInput, TOutput>, input: unknown, agent?: any): Promise<{
+    success: boolean;
+    result?: TOutput;
+    error?: string;
+}>;
+/**
+ * Built-in tool for task completion
+ */
+export declare const attemptCompletionTool: Tool<{
+    result: string;
+}, {
+    completed: boolean;
+    message: string;
+}>;
+/**
+ * Built-in tool for asking follow-up questions
+ */
+export declare const askFollowUpTool: Tool<{
+    question: string;
+}, {
+    question: string;
+    waiting_for_response: boolean;
+}>;
+/**
+ * Creates default tools that are automatically available to all agents
+ *
+ * @returns Record of default tools
+ */
+export declare function createDefaultTools(): Record<string, Tool>;

package/dist/composablepattern/tool.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * @fileoverview Tool creation and management for Composable Agent Pattern
+ * @description Provides utilities for creating and managing tools in the composable agent framework
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askFollowUpTool = exports.attemptCompletionTool = void 0;
+exports.createTool = createTool;
+exports.toolToOpenAIFunction = toolToOpenAIFunction;
+exports.toolsToOpenAIFunctions = toolsToOpenAIFunctions;
+exports.executeTool = executeTool;
+exports.createDefaultTools = createDefaultTools;
+const zod_1 = require("zod");
+/**
+ * Creates a new tool with input/output validation and execution logic
+ *
+ * @template TInput - Type for tool input parameters
+ * @template TOutput - Type for tool output
+ * @param config - Tool configuration object
+ * @returns Fully configured tool with validation methods
+ *
+ * @example
+ * ```typescript
+ * const weatherTool = createTool({
+ *   id: 'get-weather',
+ *   description: 'Get current weather for a location',
+ *   inputSchema: z.object({
+ *     location: z.string().describe('City name'),
+ *   }),
+ *   outputSchema: z.object({
+ *     temperature: z.number(),
+ *     conditions: z.string(),
+ *     location: z.string(),
+ *   }),
+ *   execute: async ({ context }) => {
+ *     return await getWeather(context.location);
+ *   },
+ * });
+ * ```
+ */
+function createTool(config) {
+    return {
+        ...config,
+        /**
+         * Validates input against the tool's input schema
+         * @param input - Raw input to validate
+         * @returns Validated and typed input
+         * @throws {z.ZodError} If validation fails
+         */
+        validateInput(input) {
+            try {
+                return config.inputSchema.parse(input);
+            }
+            catch (error) {
+                if (error instanceof zod_1.z.ZodError) {
+                    throw new Error(`Tool "${config.id}" input validation failed: ${error.issues
+                        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                        .join(', ')}`);
+                }
+                throw error;
+            }
+        },
+        /**
+         * Validates output against the tool's output schema
+         * @param output - Raw output to validate
+         * @returns Validated and typed output
+         * @throws {z.ZodError} If validation fails
+         */
+        validateOutput(output) {
+            try {
+                return config.outputSchema.parse(output);
+            }
+            catch (error) {
+                if (error instanceof zod_1.z.ZodError) {
+                    throw new Error(`Tool "${config.id}" output validation failed: ${error.issues
+                        .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+                        .join(', ')}`);
+                }
+                throw error;
+            }
+        }
+    };
+}
+/**
+ * Converts a tool to OpenAI function format for LLM usage
+ *
+ * @param tool - The tool to convert
+ * @returns OpenAI function specification
+ */
+function toolToOpenAIFunction(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.id,
+            description: tool.description,
+            parameters: zodSchemaToJsonSchema(tool.inputSchema)
+        }
+    };
+}
+/**
+ * Converts multiple tools to OpenAI functions format
+ *
+ * @param tools - Record of tools to convert
+ * @returns Array of OpenAI function specifications
+ */
+function toolsToOpenAIFunctions(tools) {
+    return Object.values(tools).map(toolToOpenAIFunction);
+}
+/**
+ * Executes a tool with proper error handling and validation
+ *
+ * @param tool - The tool to execute
+ * @param input - Input parameters for the tool
+ * @param agent - Optional agent instance for context
+ * @returns Tool execution result
+ */
+async function executeTool(tool, input, agent) {
+    try {
+        // Validate input
+        const validatedInput = tool.validateInput(input);
+        // Execute tool
+        const result = await tool.execute({ context: validatedInput, agent });
+        // Validate output
+        const validatedResult = tool.validateOutput(result);
+        return { success: true, result: validatedResult };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+/**
+ * Converts a Zod schema to JSON Schema format
+ * This is a simplified version - in production you might want to use a library like zod-to-json-schema
+ *
+ * @param schema - Zod schema to convert
+ * @returns JSON Schema object
+ */
+function zodSchemaToJsonSchema(schema) {
+    // This is a basic implementation - you might want to use a proper converter
+    // like zod-to-json-schema for production use
+    if (schema instanceof zod_1.z.ZodObject) {
+        const shape = schema.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodTypeToJsonSchema(value);
+            // Check if field is required (not optional)
+            if (!(value instanceof zod_1.z.ZodOptional)) {
+                required.push(key);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined,
+            additionalProperties: false
+        };
+    }
+    return zodTypeToJsonSchema(schema);
+}
+/**
+ * Converts individual Zod types to JSON Schema
+ *
+ * @param schema - Zod type to convert
+ * @returns JSON Schema type definition
+ */
+function zodTypeToJsonSchema(schema) {
+    if (schema instanceof zod_1.z.ZodString) {
+        const result = { type: 'string' };
+        if (schema.description) {
+            result.description = schema.description;
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodNumber) {
+        const result = { type: 'number' };
+        if (schema.description) {
+            result.description = schema.description;
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodBoolean) {
+        const result = { type: 'boolean' };
+        if (schema.description) {
+            result.description = schema.description;
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return {
+            type: 'array',
+            items: zodTypeToJsonSchema(schema.element)
+        };
+    }
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return zodTypeToJsonSchema(schema.unwrap());
+    }
+    if (schema instanceof zod_1.z.ZodEnum) {
+        return {
+            type: 'string',
+            enum: schema.options
+        };
+    }
+    // Fallback for unsupported types
+    return { type: 'string' };
+}
+/**
+ * Built-in tool for task completion
+ */
+exports.attemptCompletionTool = createTool({
+    id: 'attempt_completion',
+    description: 'Indicates that the task has been completed successfully',
+    inputSchema: zod_1.z.object({
+        result: zod_1.z.string().describe('Summary of what was accomplished')
+    }),
+    outputSchema: zod_1.z.object({
+        completed: zod_1.z.boolean(),
+        message: zod_1.z.string()
+    }),
+    execute: async ({ context }) => {
+        return {
+            completed: true,
+            message: context.result
+        };
+    }
+});
+/**
+ * Built-in tool for asking follow-up questions
+ */
+exports.askFollowUpTool = createTool({
+    id: 'ask_followup_question',
+    description: 'Ask the user a follow-up question when more information is needed',
+    inputSchema: zod_1.z.object({
+        question: zod_1.z.string().describe('The question to ask the user')
+    }),
+    outputSchema: zod_1.z.object({
+        question: zod_1.z.string(),
+        waiting_for_response: zod_1.z.boolean()
+    }),
+    execute: async ({ context }) => {
+        return {
+            question: context.question,
+            waiting_for_response: true
+        };
+    }
+});
+/**
+ * Creates default tools that are automatically available to all agents
+ *
+ * @returns Record of default tools
+ */
+function createDefaultTools() {
+    return {
+        attempt_completion: exports.attemptCompletionTool,
+        ask_followup_question: exports.askFollowUpTool
+    };
+}