@codebolt/agent 1.2.1 → 2.2.3

package/README.md

@@ -1,101 +1,177 @@
-# CodeBolt Agent Utils
+# CodeBolt Agent Package
 
-A TypeScript library providing utilities for building and managing AI agents with CodeBolt. This package extracts the agent functionality from the main CodeBolt library into a focused, reusable package.
+A comprehensive TypeScript framework for building and managing AI agents with CodeBolt. This package provides multiple architectural patterns and utilities to meet different development needs, from simple composable agents to complex multi-step workflows.
 
-## Features
+## 🚀 Quick Start
 
-- **Agent Class**: Core agent functionality for managing conversations with LLMs
-- **Message Builders**: Utilities for building user messages, system prompts, and task instructions
-- **Prompt Management**: Advanced prompt building and management capabilities
-- **LLM Output Handling**: Processing and managing LLM responses and tool executions
-- **Follow-up Questions**: Generate contextual follow-up questions for conversations
+```typescript
+import { ComposableAgent, createTool } from '@codebolt/agent/composable';
+import { z } from 'zod';
+
+// Create a simple weather tool
+const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({ location: z.string() }),
+  outputSchema: z.object({ temperature: z.number(), conditions: z.string() }),
+  execute: async ({ context }) => {
+    return await getWeatherAPI(context.location);
+  },
+});
+
+// Create and run agent
+const agent = new ComposableAgent({
+  name: 'Weather Agent',
+  instructions: 'You are a helpful weather assistant.',
+  model: 'gpt-4o-mini',
+  tools: { weatherTool },
+  memory: createCodeBoltAgentMemory('weather_agent')
+});
+
+const result = await agent.execute('What is the weather in New York?');
+```
+
+## ✨ Key Features
+
+- **Multiple Patterns**: Choose between Composable, Builder, and Processor patterns
+- **Type Safety**: Full TypeScript support with Zod validation
+- **Memory Management**: Persistent conversation storage with CodeBolt integration
+- **Tool System**: Extensible tool framework with validation
+- **Workflow Orchestration**: Multi-step agent processes with conditional logic
+- **Model Agnostic**: Support for OpenAI, Anthropic, Ollama, and more
+- **Stream Support**: Real-time streaming responses
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @codebolt/agent
 ```
 
-## Usage
+## 📖 Documentation
 
-### Basic Agent Setup
+**📚 [View Complete Documentation](./DOCUMENTATION.md)** - Comprehensive guide with examples, API reference, and best practices
 
-```typescript
-import { Agent, SystemPrompt, TaskInstruction } from '@codebolt/agent';
+### Quick Links
+- [Architectural Patterns](./DOCUMENTATION.md#architectural-patterns) - Choose the right pattern for your use case
+- [API Reference](./API_REFERENCE.md) - Complete API documentation  
+- [Examples](./EXAMPLES.md) - Real-world usage examples and tutorials
+- [Best Practices](./DOCUMENTATION.md#best-practices) - Tips for optimal agent development
+- [Migration Guide](./DOCUMENTATION.md#migration-guide) - Upgrading from previous versions
+
+## 🎯 Architecture Patterns
 
-// Create a system prompt
-const systemPrompt = new SystemPrompt();
-await systemPrompt.loadPrompt('./prompts/system.yaml');
+### Composable Pattern (Recommended)
+**Best for**: Rapid prototyping, simple agents, beginners
 
-// Create a task instruction
-const taskInstruction = new TaskInstruction();
-await taskInstruction.loadInstruction('./tasks/coding-task.yaml');
+```typescript
+import { ComposableAgent, createTool, createCodeBoltAgentMemory } from '@codebolt/agent/composable';
 
-// Initialize agent
-const agent = new Agent([], systemPrompt);
+const agent = new ComposableAgent({
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'gpt-4o-mini',
+  tools: { myTool },
+  memory: createCodeBoltAgentMemory('agent_id')
+});
 
-// Run the agent on a task
-const result = await agent.runAgent(taskInstruction);
+const result = await agent.execute('Help me with this task');
 ```
 
-### Building User Messages
+### Builder Pattern
+**Best for**: Complex workflows, fine-grained control
 
 ```typescript
-import { UserMessage } from '@codebolt/agent-utils';
+import { Agent, InitialPromptBuilder, LLMOutputHandler } from '@codebolt/agent/builder';
 
-const userMessage = new UserMessage();
-await userMessage.addMessage("Please help me with my code");
-await userMessage.addFileContent("./src/main.ts");
+const promptBuilder = new InitialPromptBuilder(userMessage)
+  .addSystemInstructions("You are a coding assistant")
+  .addFile("./src/main.ts")
+  .addTaskDetails("Fix compilation errors");
+
+const prompt = await promptBuilder.build();
+const agent = new Agent(tools, systemPrompt);
+const result = await agent.runAgent(prompt);
 ```
 
-### Advanced Prompt Building
+### Processor Pattern
+**Best for**: Advanced customization, specialized requirements
 
 ```typescript
-import { InitialPromptBuilder } from '@codebolt/agent';
-
-const promptBuilder = new InitialPromptBuilder("Fix the bug in my application");
-promptBuilder
-  .addSystemInstructions("You are a helpful coding assistant")
-  .addFile("./src/problematic-file.ts")
-  .addTaskDetails("Find and fix the TypeScript compilation errors");
+import { BaseProcessor, AgentStep } from '@codebolt/agent/processor';
 
-const prompt = await promptBuilder.build();
+class CustomProcessor extends BaseProcessor {
+  async process(messages: any[]): Promise<any> {
+    return this.executeCustomFlow(messages);
+  }
+}
 ```
 
-### LLM Output Handling
+## 🛠️ Available Exports
+
+### Composable Pattern
+```typescript
+import { 
+  ComposableAgent, createTool, createWorkflow,
+  Memory, createCodeBoltAgentMemory, MDocument 
+} from '@codebolt/agent/composable';
+```
 
+### Builder Pattern  
 ```typescript
-import { LLMOutputHandler } from '@codebolt/agent';
+import { 
+  Agent, InitialPromptBuilder, LLMOutputHandler,
+  SystemPrompt, TaskInstruction, UserMessage 
+} from '@codebolt/agent/builder';
+```
 
-const outputHandler = new LLMOutputHandler();
-const result = await outputHandler.processLLMResponse(llmResponse, tools);
+### Processor Pattern
+```typescript
+import { 
+  BaseProcessor, AgentStep, BaseTool,
+  ChatCompressionProcessor, LoopDetectionProcessor 
+} from '@codebolt/agent/processor';
 ```
 
-## API Reference
+## 🏗️ Workflow System
 
-### Classes
+Create complex multi-agent workflows:
 
-- `Agent` - Core agent for managing LLM conversations and tool executions
-- `UserMessage` - Builder for user messages with file content support
-- `SystemPrompt` - Management of system prompts from YAML files
-- `TaskInstruction` - Handling of task instructions and metadata
-- `InitialPromptBuilder` - Fluent interface for building complex prompts
-- `FollowUpPromptBuilder` - Generate follow-up questions for conversations
-- `LLMOutputHandler` - Process LLM responses and handle tool executions
+```typescript
+const workflow = createWorkflow({
+  name: 'Content Pipeline',
+  steps: [
+    createAgentStep({
+      id: 'research', 
+      agent: researchAgent,
+      messageTemplate: 'Research: {{topic}}'
+    }),
+    createAgentStep({
+      id: 'write',
+      agent: writingAgent, 
+      messageTemplate: 'Write article: {{researchData}}'
+    })
+  ]
+});
+
+const result = await workflow.execute({ topic: 'AI Ethics' });
+```
 
-### Types
+## 🧠 Memory & Storage
 
-The package exports comprehensive TypeScript types for all interfaces, including:
-- `Message`, `ToolResult`, `ToolDetails`
-- `OpenAIMessage`, `OpenAITool`, `ConversationEntry`
-- `UserMessageContent`, `CodeboltAPI`
-- `MCPTool`, `InitialUserMessage`
+Integrated with CodeBolt's storage system:
 
-## Dependencies
+```typescript
+// Agent-scoped persistent storage
+const agentMemory = createCodeBoltAgentMemory('my_agent');
 
-This package depends on `@codebolt/codeboltjs` for core functionality like file system operations, LLM communication, and tool execution.
+// Project-scoped storage
+const projectMemory = createCodeBoltProjectMemory('project_agent');
 
-## Development
+// Fast access memory database  
+const dbMemory = createCodeBoltDbMemory('cache_agent');
+```
+
+## 🔧 Development
 
 ```bash
 # Install dependencies
@@ -104,17 +180,32 @@ npm install
 # Build the project
 npm run build
 
-# Run in development mode
+# Development mode
 npm run dev
 
-# Clean build artifacts
-npm run clean
+# Run tests
+npm run test
+
+# Lint code
+npm run lint
 ```
 
-## License
+## 📋 Pattern Comparison
+
+| Pattern | Complexity | Use Case | Learning Curve |
+|---------|------------|----------|----------------|
+| **Composable** | Low | Rapid prototyping, simple agents | Low |
+| **Builder** | Medium | Complex workflows, custom logic | Medium |
+| **Processor** | High | Advanced customization | High |
+
+## 🤝 Contributing
+
+See our [Contributing Guide](./DOCUMENTATION.md#contributing) for development setup, coding standards, and submission guidelines.
+
+## 📄 License
 
-MIT
+MIT - See the main CodeBolt repository for details.
 
-## Contributing
+---
 
-Please see the main CodeBolt repository for contribution guidelines.
+**📚 [Complete Documentation](./DOCUMENTATION.md)** | **🐛 [Report Issues](https://github.com/codeboltai/codeboltjs/issues)** | **💬 [Join Community](https://discord.gg/codebolt)**

package/dist/{agent.js → builderpattern/agent.js}

@@ -258,9 +258,9 @@ class Agent {
     async executeTool(toolName, toolInput) {
         //codebolttools--readfile
         const [toolboxName, actualToolName] = toolName.split('--');
-        console.log("Toolbox name: ", toolboxName, "Actual tool name: ", actualToolName);
+        // console.log("Toolbox name: ", toolboxName, "Actual tool name: ", actualToolName);
         const { data } = await mcp.executeTool(toolboxName, actualToolName, toolInput);
-        console.log("Tool result: ", data);
+        // console.log("Tool result: ", data);
         return data;
     }
     /**

package/dist/{followupquestionbuilder.d.ts → builderpattern/followupquestionbuilder.d.ts}

@@ -1,4 +1,4 @@
-import type { OpenAIMessage, OpenAITool, ToolResult, CodeboltAPI } from "./types/libFunctionTypes";
+import type { OpenAIMessage, OpenAITool, ToolResult, CodeboltAPI } from "../types/libFunctionTypes";
 /**
  * Builds follow-up prompts for continuing conversations with tool results.
  * Manages conversation history and summarization when conversations get too long.

package/dist/{followupquestionbuilder.js → builderpattern/followupquestionbuilder.js}

@@ -143,7 +143,7 @@ class FollowUpPromptBuilder {
             return this.previousConversation;
         }
         try {
-            console.log("Summarizing conversation due to length:", this.previousConversation.length);
+            // console.log("Summarizing conversation due to length:", this.previousConversation.length);
             // Convert OpenAI messages to the format expected by chatSummary
             const messagesToSummarize = this.previousConversation.map(msg => ({
                 role: msg.role,

package/dist/{index.d.ts → builderpattern/index.d.ts}

@@ -9,6 +9,6 @@ export { TaskInstruction } from './taskInstruction';
 export { InitialPromptBuilder } from './promptbuilder';
 export { FollowUpPromptBuilder } from './followupquestionbuilder';
 export { LLMOutputHandler } from './llmoutputhandler';
-export type { Message, ToolResult, ToolDetails, OpenAIMessage, OpenAITool, ConversationEntry, UserMessageContent, CodeboltAPI, ToolCall } from './types/libFunctionTypes';
-export type { MCPTool, Agent as AgentType, InitialUserMessage } from './types/commonTypes';
-export type { UserMessage as CLIUserMessage } from './types/socketMessageTypes';
+export type { Message, ToolResult, ToolDetails, OpenAIMessage, OpenAITool, ConversationEntry, UserMessageContent, CodeboltAPI, ToolCall } from '../types/libFunctionTypes';
+export type { MCPTool, Agent as AgentType, InitialUserMessage } from '../types/commonTypes';
+export type { UserMessage as CLIUserMessage } from '../types/socketMessageTypes';

package/dist/{llmoutputhandler.d.ts → builderpattern/llmoutputhandler.d.ts}

@@ -1,4 +1,4 @@
-import type { OpenAIMessage, ToolResult, CodeboltAPI } from "./types/libFunctionTypes";
+import type { OpenAIMessage, ToolResult, CodeboltAPI } from "../types/libFunctionTypes";
 /**
  * Handles LLM output processing, tool execution, and completion detection.
  * This class processes LLM responses and manages the conversation flow.

package/dist/{llmoutputhandler.js → builderpattern/llmoutputhandler.js}

@@ -137,7 +137,7 @@ class LLMOutputHandler {
             let toolResults = [];
             let taskCompletedBlock;
             let userRejectedToolUse = false;
-            console.log("Calling run tool: ", JSON.stringify(this.llmResponse.completion));
+            // console.log("Calling run tool: ", JSON.stringify(this.llmResponse.completion));
             const contentBlock = this.llmResponse.completion.choices[0];
             // Validate contentBlock structure
             if (!contentBlock || !contentBlock.message) {
@@ -174,12 +174,12 @@ class LLMOutputHandler {
                                     }
                                 }
                                 else {
-                                    console.log("Executing tool: ", toolName, toolInput);
+                                    // console.log("Executing tool: ", toolName, toolInput);
                                     const [didUserReject, result] = await this.executeTool(toolName, toolInput);
-                                    console.log("Tool result: ", result);
+                                    // console.log("Tool result: ", result);
                                     // toolResults.push(this.getToolResult(toolUseId, result));
                                     let toolResult = this.getToolResult(toolUseId, result);
-                                    console.log("tool result after parsing", toolResult);
+                                    // console.log("tool result after parsing", toolResult);
                                     this.toolResults.push({
                                         role: "tool",
                                         tool_call_id: toolResult.tool_call_id,
@@ -367,9 +367,9 @@ class LLMOutputHandler {
         var _a;
         //codeboltmcp--readfile
         const [toolboxName, actualToolName] = toolName.split('--');
-        console.log("Toolbox name: ", toolboxName, "Actual tool name: ", actualToolName);
+        // console.log("Toolbox name: ", toolboxName, "Actual tool name: ", actualToolName);
         const data = await ((_a = this.codebolt) === null || _a === void 0 ? void 0 : _a.mcp.executeTool(toolboxName, actualToolName, toolInput));
-        console.log("Tool result: ", data);
+        // console.log("Tool result: ", data);
         return data;
     }
     /**
@@ -389,7 +389,7 @@ class LLMOutputHandler {
             // Only attempt to parse if content looks like JSON
             if (content.trim().startsWith('{') || content.trim().startsWith('[')) {
                 const parsed = JSON.parse(content);
-                console.log("Parsed Content: ", parsed);
+                // console.log("Parsed Content: ", parsed);
                 if (parsed && typeof parsed === 'object' && parsed.payload && parsed.payload.content) {
                     content = `The browser action has been executed. The screenshot have been captured for your analysis. The tool response is provided in the next user message`;
                     userMessage = parsed.payload.content;

package/dist/{promptbuilder.d.ts → builderpattern/promptbuilder.d.ts}

@@ -1,6 +1,6 @@
-import { UserMessage as CLIUserMessage } from "./types/socketMessageTypes";
-import type { OpenAIMessage, OpenAITool, ConversationEntry, CodeboltAPI, ToolResult } from "./types/libFunctionTypes";
-import type { MCPTool, Agent, InitialUserMessage } from "./types/commonTypes";
+import { UserMessage as CLIUserMessage } from "../types/socketMessageTypes";
+import type { OpenAIMessage, OpenAITool, ConversationEntry, CodeboltAPI, ToolResult } from "../types/libFunctionTypes";
+import type { MCPTool, Agent, InitialUserMessage } from "../types/commonTypes";
 /**
  * PromptBuilder class for constructing prompts using a fluent interface.
  * Allows chaining methods to build complex prompts from user messages.

package/dist/{taskInstruction.d.ts → builderpattern/taskInstruction.d.ts}

@@ -1,6 +1,6 @@
 import { UserMessage } from "./usermessage";
-import type { UserMessageContent } from "./types/libFunctionTypes";
-import type { Tools, UserMessages } from "./types/InternalTypes";
+import type { UserMessageContent } from "../types/libFunctionTypes";
+import type { Tools, UserMessages } from "../types/InternalTypes";
 /**
  * Class representing a task instruction.
  * Handles loading task data and converting it to prompts.

package/dist/{usermessage.d.ts → builderpattern/usermessage.d.ts}

@@ -1,6 +1,6 @@
-import type { UserMessageContent } from "./types/libFunctionTypes";
-import type { Agent } from "./types/commonTypes";
-import type { Message } from "./types/InternalTypes";
+import type { UserMessageContent } from "../types/libFunctionTypes";
+import type { Agent } from "../types/commonTypes";
+import type { Message } from "../types/InternalTypes";
 /**
  * Class that processes and manages user messages.
  * Handles converting messages to prompts and extracting mentioned entities.
@@ -58,7 +58,12 @@ declare class UserMessage {
      *
      * @returns Promise with an array of MCP tools
      */
-    getMentionedMcpsTools(): Promise<any[] | undefined>;
+    getMentionedMcpsTools(): Promise<{
+        toolbox: string;
+        toolName: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    }[] | undefined>;
     /**
      * Gets environment details for the current working directory.
      *

package/dist/composablepattern/agent.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Main ComposableAgent implementation
+ * @description Core agent class that provides a composable API for creating and running agents
+ */
+import type { ComposableAgentConfig, ComposableAgent as IComposableAgent, Message, ExecutionResult, ExecutionContext, StreamCallback, Tool, CodeBoltMessage } from './types';
+/**
+ * Main ComposableAgent class that provides a simple, composable API for creating agents
+ */
+export declare class ComposableAgent implements IComposableAgent {
+    readonly config: ComposableAgentConfig;
+    private conversation;
+    private memory?;
+    private tools;
+    constructor(config: ComposableAgentConfig);
+    /**
+     * Run the agent using globally saved user context from codeboltjs
+     * This is the main method to use within codebolt.onMessage()
+     *
+     * @param options - Execution options
+     * @returns Promise<ExecutionResult>
+     */
+    run(options?: {
+        stream?: boolean;
+        callback?: StreamCallback;
+    }): Promise<ExecutionResult>;
+    /**
+     * Execute a task with the agent using a simple string message
+     *
+     * @param message - User message to process
+     * @param options - Execution options
+     * @returns Promise<ExecutionResult>
+     */
+    execute(message: string, options?: {
+        stream?: boolean;
+        callback?: StreamCallback;
+    }): Promise<ExecutionResult>;
+    /**
+     * Execute a task with the agent using CodeBolt Message format
+     *
+     * @param message - CodeBolt message with enhanced features
+     * @param options - Execution options
+     * @returns Promise<ExecutionResult>
+     */
+    executeMessage(message: CodeBoltMessage, options?: {
+        stream?: boolean;
+        callback?: StreamCallback;
+    }): Promise<ExecutionResult>;
+    /**
+     * Add a message to the conversation
+     *
+     * @param message - Message to add
+     */
+    addMessage(message: Message): void;
+    /**
+     * Get conversation history
+     *
+     * @returns Array of messages
+     */
+    getConversation(): Message[];
+    /**
+     * Clear conversation history (keeps system message)
+     */
+    clearConversation(): void;
+    /**
+     * Save conversation to memory
+     */
+    saveConversation(): Promise<void>;
+    /**
+     * Load conversation from memory
+     */
+    loadConversation(): Promise<void>;
+    /**
+     * Make a request to the LLM
+     *
+     * @returns LLM response
+     */
+    private makeLLMRequest;
+    /**
+     * Execute a tool call
+     *
+     * @param toolCall - Tool call to execute
+     * @returns Tool result message
+     */
+    private executeToolCall;
+    /**
+     * Get list of tools that were used in the conversation
+     *
+     * @returns Array of tool names
+     */
+    private getUsedTools;
+    /**
+     * Get available tools
+     *
+     * @returns Record of available tools
+     */
+    getTools(): Record<string, Tool>;
+    /**
+     * Add a tool to the agent
+     *
+     * @param name - Tool name
+     * @param tool - Tool instance
+     */
+    addTool(name: string, tool: Tool): void;
+    /**
+     * Remove a tool from the agent
+     *
+     * @param name - Tool name
+     */
+    removeTool(name: string): void;
+    /**
+     * Get execution context for tools
+     *
+     * @returns ExecutionContext
+     */
+    getExecutionContext(): ExecutionContext;
+    /**
+     * Process CodeBolt message and enhance agent capabilities
+     *
+     * @param message - CodeBolt message to process
+     */
+    private processCodeBoltMessage;
+    /**
+     * Process remix prompt and enhance system instructions
+     *
+     * @param remixPrompt - Additional instructions to add to system prompt
+     */
+    private processRemixPrompt;
+    /**
+     * Process mentioned MCP tools and add them to available tools
+     *
+     * @param mentionedMCPs - List of MCP tools to process
+     */
+    private processMCPs;
+    /**
+     * Create a generic MCP tool wrapper
+     *
+     * @param toolbox - MCP toolbox name
+     * @param toolName - MCP tool name
+     * @returns Tool instance
+     */
+    private createMCPTool;
+    /**
+     * Process mentioned agents and add them as sub-agent tools
+     *
+     * @param mentionedAgents - List of agents to process
+     */
+    private processAgents;
+    /**
+     * Create a sub-agent tool wrapper
+     *
+     * @param agent - Agent information
+     * @returns Tool instance
+     */
+    private createSubAgentTool;
+    /**
+     * Process mentioned files and return their contents
+     *
+     * @param mentionedFiles - List of file paths
+     * @returns Array of file contents with headers
+     */
+    private processFiles;
+}
+/**
+ * Create a new ComposableAgent instance
+ *
+ * @param config - Agent configuration
+ * @returns ComposableAgent instance
+ */
+export declare function createAgent(config: ComposableAgentConfig): ComposableAgent;