@codebolt/agent 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# CodeBolt Agent Utils
+
+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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @codebolt/agent-utils
+```
+
+## Usage
+
+### Basic Agent Setup
+
+```typescript
+import { Agent, SystemPrompt, TaskInstruction } from '@codebolt/agent-utils';
+
+// Create a system prompt
+const systemPrompt = new SystemPrompt();
+await systemPrompt.loadPrompt('./prompts/system.yaml');
+
+// Create a task instruction
+const taskInstruction = new TaskInstruction();
+await taskInstruction.loadInstruction('./tasks/coding-task.yaml');
+
+// Initialize agent
+const agent = new Agent([], systemPrompt);
+
+// Run the agent on a task
+const result = await agent.runAgent(taskInstruction);
+```
+
+### Building User Messages
+
+```typescript
+import { UserMessage } from '@codebolt/agent-utils';
+
+const userMessage = new UserMessage();
+await userMessage.addMessage("Please help me with my code");
+await userMessage.addFileContent("./src/main.ts");
+```
+
+### Advanced Prompt Building
+
+```typescript
+import { InitialPromptBuilder } from '@codebolt/agent-utils';
+
+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");
+
+const prompt = await promptBuilder.build();
+```
+
+### LLM Output Handling
+
+```typescript
+import { LLMOutputHandler } from '@codebolt/agent-utils';
+
+const outputHandler = new LLMOutputHandler();
+const result = await outputHandler.processLLMResponse(llmResponse, tools);
+```
+
+## API Reference
+
+### Classes
+
+- `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
+
+### Types
+
+The package exports comprehensive TypeScript types for all interfaces, including:
+- `Message`, `ToolResult`, `ToolDetails`
+- `OpenAIMessage`, `OpenAITool`, `ConversationEntry`
+- `UserMessageContent`, `CodeboltAPI`
+- `MCPTool`, `InitialUserMessage`
+
+## Dependencies
+
+This package depends on `@codebolt/codeboltjs` for core functionality like file system operations, LLM communication, and tool execution.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Clean build artifacts
+npm run clean
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Please see the main CodeBolt repository for contribution guidelines.

package/dist/agent.d.ts

@@ -0,0 +1,86 @@
+import { SystemPrompt } from "./systemprompt";
+import { TaskInstruction } from "./taskInstruction";
+/**
+ * Agent class that manages conversations with LLMs and tool executions.
+ * Handles the conversation flow, tool calls, and task completions.
+ */
+declare class Agent {
+    /** Available tools for the agent to use */
+    private tools;
+    /** Full conversation history for API calls */
+    private apiConversationHistory;
+    /** Maximum number of conversation turns (0 means unlimited) */
+    private maxRun;
+    /** System prompt that provides instructions to the model */
+    private systemPrompt;
+    /** Messages from the user */
+    private userMessage;
+    /** The next user message to be added to the conversation */
+    private nextUserMessage;
+    /**
+     * Creates a new Agent instance.
+     *
+     * @param tools - The tools available to the agent
+     * @param systemPrompt - The system prompt providing instructions to the LLM
+     * @param maxRun - Maximum number of conversation turns (0 means unlimited)
+     */
+    constructor(tools: any | undefined, systemPrompt: SystemPrompt, maxRun?: number);
+    /**
+     * Runs the agent on a specific task until completion or max runs reached.
+     *
+     * @param task - The task instruction to be executed
+     * @param successCondition - Optional function to determine if the task is successful
+     * @returns Promise with success status, error (if any), and the last assistant message
+     */
+    run(task: TaskInstruction, successCondition?: () => boolean): Promise<{
+        success: boolean;
+        error: string | null;
+        message: string | null;
+    }>;
+    /**
+     * Attempts to make a request to the LLM with conversation history and tools.
+     *
+     * @param apiConversationHistory - The current conversation history
+     * @param tools - The tools available to the LLM
+     * @returns Promise with the LLM response
+     */
+    private attemptLlmRequest;
+    /**
+     * Executes a tool with given name and input.
+     *
+     * @param toolName - The name of the tool to execute
+     * @param toolInput - The input parameters for the tool
+     * @returns Promise with tuple [userRejected, result]
+     */
+    private executeTool;
+    /**
+     * Starts a sub-agent to handle a specific task.
+     *
+     * @param agentName - The name of the sub-agent to start
+     * @param params - Parameters for the sub-agent
+     * @returns Promise with tuple [userRejected, result]
+     */
+    private startSubAgent;
+    /**
+     * Extracts tool details from a tool call object.
+     *
+     * @param tool - The tool call object from the LLM response
+     * @returns ToolDetails object with name, input, and ID
+     */
+    private getToolDetail;
+    /**
+     * Creates a tool result object from the tool execution response.
+     *
+     * @param tool_call_id - The ID of the tool call
+     * @param content - The content returned by the tool
+     * @returns ToolResult object
+     */
+    private getToolResult;
+    /**
+     * Fallback method for API requests in case of failures.
+     *
+     * @throws Error API request fallback not implemented
+     */
+    private attemptApiRequest;
+}
+export { Agent };

package/dist/agent.js

@@ -0,0 +1,324 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const codeboltjs_1 = __importDefault(require("@codebolt/codeboltjs"));
+const { chat, mcp, llm, agent: codeboltAgent } = codeboltjs_1.default;
+// All interfaces moved to libFunctionTypes.ts
+/**
+ * Agent class that manages conversations with LLMs and tool executions.
+ * Handles the conversation flow, tool calls, and task completions.
+ */
+class Agent {
+    /**
+     * Creates a new Agent instance.
+     *
+     * @param tools - The tools available to the agent
+     * @param systemPrompt - The system prompt providing instructions to the LLM
+     * @param maxRun - Maximum number of conversation turns (0 means unlimited)
+     */
+    constructor(tools = [], systemPrompt, maxRun = 0) {
+        this.tools = tools;
+        this.userMessage = [];
+        this.apiConversationHistory = [];
+        this.maxRun = maxRun;
+        this.systemPrompt = systemPrompt;
+    }
+    /**
+     * Runs the agent on a specific task until completion or max runs reached.
+     *
+     * @param task - The task instruction to be executed
+     * @param successCondition - Optional function to determine if the task is successful
+     * @returns Promise with success status, error (if any), and the last assistant message
+     */
+    async run(task, successCondition = () => true) {
+        var _a, _b;
+        let mentaionedMCPSTool = await task.userMessage.getMentionedMcpsTools();
+        this.tools = [
+            ...this.tools,
+            ...mentaionedMCPSTool || [],
+        ];
+        let mentionedAgents = await task.userMessage.getMentionedAgents();
+        // Transform agents into tool format
+        const agentTools = mentionedAgents.map(agent => {
+            return {
+                type: "function",
+                function: {
+                    name: `subagent--${agent.unique_id}`,
+                    description: agent.longDescription || agent.description,
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            task: {
+                                type: "string",
+                                description: "The task to be executed by the tool."
+                            }
+                        },
+                        required: ["task"]
+                    }
+                }
+            };
+        });
+        this.tools = this.tools.concat(agentTools);
+        let completed = false;
+        let userMessages = await task.toPrompt();
+        this.apiConversationHistory.push({ role: "user", content: userMessages });
+        let runcomplete = 0;
+        while (!completed && (runcomplete <= this.maxRun || this.maxRun === 0)) {
+            try {
+                runcomplete++;
+                const response = await this.attemptLlmRequest(this.apiConversationHistory, this.tools);
+                let isMessagePresentinReply = false;
+                for (const contentBlock of response.choices) {
+                    if (contentBlock.message) {
+                        isMessagePresentinReply = true;
+                        this.apiConversationHistory.push(contentBlock.message);
+                        if (contentBlock.message.content != null) {
+                            await chat.sendMessage(contentBlock.message.content, {});
+                        }
+                    }
+                }
+                if (!isMessagePresentinReply) {
+                    this.apiConversationHistory.push({
+                        role: "assistant",
+                        content: [{ type: "text", text: "Failure: I did not provide a response." }],
+                    });
+                }
+                try {
+                    let toolResults = [];
+                    let taskCompletedBlock;
+                    let userRejectedToolUse = false;
+                    const contentBlock = response.choices[0];
+                    if ((_a = contentBlock.message) === null || _a === void 0 ? void 0 : _a.tool_calls) {
+                        for (const tool of contentBlock.message.tool_calls) {
+                            try {
+                                const { toolInput, toolName, toolUseId } = this.getToolDetail(tool);
+                                if (!userRejectedToolUse) {
+                                    if (toolName.includes("attempt_completion")) {
+                                        taskCompletedBlock = tool;
+                                    }
+                                    else {
+                                        let [serverName] = toolName.replace('--', ':').split(':');
+                                        if (serverName == 'subagent') {
+                                            const agentResponse = await codeboltAgent.startAgent(toolName.replace("subagent--", ''), toolInput.task);
+                                            const [didUserReject, result] = [false, "tool result is successful"];
+                                            let toolResult = this.getToolResult(toolUseId, result);
+                                            toolResults.push({
+                                                role: "tool",
+                                                tool_call_id: toolResult.tool_call_id,
+                                                content: toolResult.content,
+                                            });
+                                            if (toolResult.userMessage) {
+                                                this.nextUserMessage = {
+                                                    role: "user",
+                                                    content: toolResult.userMessage
+                                                };
+                                            }
+                                            if (didUserReject) {
+                                                userRejectedToolUse = true;
+                                            }
+                                        }
+                                        else {
+                                            const [didUserReject, result] = await this.executeTool(toolName, toolInput);
+                                            // toolResults.push(this.getToolResult(toolUseId, result));
+                                            let toolResult = this.getToolResult(toolUseId, result);
+                                            toolResults.push({
+                                                role: "tool",
+                                                tool_call_id: toolResult.tool_call_id,
+                                                content: toolResult.content,
+                                            });
+                                            if (toolResult.userMessage) {
+                                                this.nextUserMessage = {
+                                                    role: "user",
+                                                    content: toolResult.userMessage
+                                                };
+                                            }
+                                            if (didUserReject) {
+                                                userRejectedToolUse = true;
+                                            }
+                                        }
+                                    }
+                                }
+                                else {
+                                    let toolResult = this.getToolResult(toolUseId, "Skipping tool execution due to previous tool user rejection.");
+                                    toolResults.push({
+                                        role: "tool",
+                                        tool_call_id: toolResult.tool_call_id,
+                                        content: toolResult.content,
+                                    });
+                                    if (toolResult.userMessage) {
+                                        this.nextUserMessage = {
+                                            role: "user",
+                                            content: toolResult.userMessage
+                                        };
+                                    }
+                                }
+                            }
+                            catch (error) {
+                                toolResults.push({
+                                    role: "tool",
+                                    tool_call_id: tool.id,
+                                    content: `please provide valid json string for tool.function.arguments String(error)`,
+                                });
+                            }
+                        }
+                    }
+                    if (taskCompletedBlock) {
+                        let [_, result] = await this.executeTool(taskCompletedBlock.function.name, JSON.parse(taskCompletedBlock.function.arguments || "{}"));
+                        if (result === "") {
+                            completed = true;
+                            result = "The user is satisfied with the result.";
+                        }
+                        let toolResult = this.getToolResult(taskCompletedBlock.id, result);
+                        toolResults.push({
+                            role: "tool",
+                            tool_call_id: toolResult.tool_call_id,
+                            content: toolResult.content,
+                        });
+                        if (toolResult.userMessage) {
+                            this.nextUserMessage = {
+                                role: "user",
+                                content: toolResult.userMessage
+                            };
+                        }
+                    }
+                    this.apiConversationHistory.push(...toolResults);
+                    if (this.nextUserMessage) {
+                        this.apiConversationHistory.push(this.nextUserMessage);
+                    }
+                    let nextUserMessage = toolResults;
+                    if (toolResults.length === 0) {
+                        nextUserMessage = [{
+                                role: "user",
+                                content: [{
+                                        type: "text",
+                                        text: "If you have completed the user's task, use the attempt_completion tool. If you require additional information from the user, use the ask_followup_question tool. Otherwise, if you have not completed the task and do not need additional information, then proceed with the next step of the task. (This is an automated message, so do not respond to it conversationally.)"
+                                    }]
+                            }];
+                        if (nextUserMessage) {
+                            this.apiConversationHistory.push(nextUserMessage[0]);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error("Error in agent tool call:", error);
+                    return { success: false, error: error instanceof Error ? error.message : String(error), message: null };
+                }
+            }
+            catch (error) {
+                console.error("Error in agent tool call:", error);
+                return { success: false, error: error instanceof Error ? error.message : String(error), message: null };
+            }
+        }
+        return {
+            success: completed,
+            error: null,
+            message: ((_b = this.apiConversationHistory
+                .filter(msg => msg.role === 'assistant')
+                .pop()) === null || _b === void 0 ? void 0 : _b.content) || ''
+        };
+    }
+    /**
+     * Attempts to make a request to the LLM with conversation history and tools.
+     *
+     * @param apiConversationHistory - The current conversation history
+     * @param tools - The tools available to the LLM
+     * @returns Promise with the LLM response
+     */
+    async attemptLlmRequest(apiConversationHistory, tools) {
+        try {
+            let systemPrompt = await this.systemPrompt.toPromptText();
+            const aiMessages = [
+                { role: "system", content: systemPrompt },
+                ...apiConversationHistory,
+            ];
+            const createParams = {
+                full: true,
+                messages: aiMessages,
+                tools: tools,
+                tool_choice: "auto",
+            };
+            //@ts-ignore
+            const { completion } = await llm.inference(createParams);
+            return completion;
+        }
+        catch (error) {
+            return this.attemptApiRequest();
+        }
+    }
+    /**
+     * Executes a tool with given name and input.
+     *
+     * @param toolName - The name of the tool to execute
+     * @param toolInput - The input parameters for the tool
+     * @returns Promise with tuple [userRejected, result]
+     */
+    async executeTool(toolName, toolInput) {
+        //codebolttools--readfile
+        const [toolboxName, actualToolName] = toolName.split('--');
+        console.log("Toolbox name: ", toolboxName, "Actual tool name: ", actualToolName);
+        const { data } = await mcp.executeTool(toolboxName, actualToolName, toolInput);
+        console.log("Tool result: ", data);
+        return data;
+    }
+    /**
+     * Starts a sub-agent to handle a specific task.
+     *
+     * @param agentName - The name of the sub-agent to start
+     * @param params - Parameters for the sub-agent
+     * @returns Promise with tuple [userRejected, result]
+     */
+    async startSubAgent(agentName, params) {
+        return [false, await codeboltAgent.startAgent(agentName, params.task)];
+    }
+    /**
+     * Extracts tool details from a tool call object.
+     *
+     * @param tool - The tool call object from the LLM response
+     * @returns ToolDetails object with name, input, and ID
+     */
+    getToolDetail(tool) {
+        return {
+            toolName: tool.function.name,
+            toolInput: JSON.parse(tool.function.arguments || "{}"),
+            toolUseId: tool.id
+        };
+    }
+    /**
+     * Creates a tool result object from the tool execution response.
+     *
+     * @param tool_call_id - The ID of the tool call
+     * @param content - The content returned by the tool
+     * @returns ToolResult object
+     */
+    getToolResult(tool_call_id, content) {
+        let userMessage = undefined;
+        try {
+            let parsed = JSON.parse(content);
+            if (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`;
+                // this.apiConversationHistory.push()
+                userMessage = parsed.payload.content;
+            }
+        }
+        catch (error) {
+        }
+        return {
+            role: "tool",
+            tool_call_id,
+            content,
+            userMessage
+        };
+    }
+    /**
+     * Fallback method for API requests in case of failures.
+     *
+     * @throws Error API request fallback not implemented
+     */
+    attemptApiRequest() {
+        throw new Error("API request fallback not implemented");
+    }
+}
+exports.Agent = Agent;

package/dist/followupquestionbuilder.d.ts

@@ -0,0 +1,75 @@
+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.
+ */
+declare class FollowUpPromptBuilder {
+    /** Previous conversation messages */
+    private previousConversation;
+    /** Tool results to add to the conversation */
+    private toolResults;
+    /** Available tools for the conversation */
+    private tools;
+    /** The last LLM response, if available */
+    private llmResponse?;
+    /** Maximum conversation length before summarization */
+    private maxConversationLength;
+    /** Whether to force summarization */
+    private forceSummarization;
+    /** Codebolt API instance */
+    private codebolt?;
+    /**
+     * Creates a new FollowUpQuestionBuilder instance.
+     *
+     * @param codebolt - Optional codebolt API instance
+     */
+    constructor(codebolt?: CodeboltAPI);
+    /**
+     * Adds the previous conversation to the builder.
+     *
+     * @param previousPrompt - The previous prompt object containing messages and tools
+     * @returns The FollowUpQuestionBuilder instance for chaining
+     */
+    addPreviousConversation(previousPrompt: {
+        messages: OpenAIMessage[];
+        tools: OpenAITool[];
+        tool_choice?: string;
+    }, llmResponse: {
+        completion: any;
+    }): this;
+    addLLMResponseToConverstaion(llmResponse: {
+        completion: any;
+    }): this;
+    /**
+     * Adds tool execution results to the conversation.
+     *
+     * @param toolResults - Array of tool execution results
+     * @returns The FollowUpQuestionBuilder instance for chaining
+     */
+    addToolResult(toolResults: ToolResult[]): this;
+    /**
+     * Checks if the conversation is too long and sets up summarization with custom max length.
+     *
+     * @param maxLength - Maximum number of messages before summarization
+     * @returns The FollowUpQuestionBuilder instance for chaining
+     */
+    checkAndSummarizeConversationIfLong(maxLength: number): this;
+    /**
+     * Performs conversation summarization if needed.
+     *
+     * @returns Promise that resolves to the summarized messages
+     */
+    private performSummarization;
+    /**
+     * Builds the follow-up conversation prompt with tool results.
+     *
+     * @returns Promise that resolves to the conversation prompt object
+     */
+    build(): Promise<{
+        messages: OpenAIMessage[];
+        tools: OpenAITool[];
+        tool_choice: "auto";
+        full: boolean;
+    }>;
+}
+export { FollowUpPromptBuilder };