@xalia/agent 0.5.8 → 0.6.1

package/README.md

@@ -5,6 +5,7 @@ A TypeScript-based AI agent system with MCP (Model Context Protocol) support, mu
 ## Overview
 
 This agent provides two primary interfaces:
+
 - **Agent Mode**: Single-user conversational AI with tool support
 - **Chat Mode**: Multi-user chat server with shared AI agent sessions
 
@@ -20,28 +21,31 @@ yarn workspaces run build
 
 ### Basic Usage
 
-Example of running agent can be found in [test script](../mcppro/scripts/test_script). 
+Example of running agent can be found in [test script](../mcppro/scripts/test_script).
 
 ## Architecture
 
 ### Core Components
 
 #### Agent (`src/agent/`)
+
 - **`Agent`**: Main orchestrator class managing conversations, tools, and LLM interactions
-- **`McpServerManager`**: Manages MCP tool servers, enables/disables tools dynamically  
+- **`McpServerManager`**: Manages MCP tool servers, enables/disables tools dynamically
 - **`SkillManager`**: Interfaces with SudoMCP backend to discover and connect to hosted MCP servers
-- **LLM Implementations**: 
+- **LLM Implementations**:
   - `OpenAILLM`: Standard OpenAI API integration
   - `OpenAILLMStreaming`: Streaming response support
   - `DummyLLM`: Mock implementation for testing
 
 #### Chat System (`src/chat/`)
+
 - **`ChatClient`/`runServer`**: WebSocket-based real-time communication
 - **`ConversationManager`**: Orchestrates multi-user sessions with shared AI agent
 - **`Database`**: Supabase integration for user management, sessions, and agent profiles
 - **`ApiKeyManager`**: Authentication and authorization
 
 #### CLI Tools (`src/tool/`)
+
 - **`main.ts`**: Primary entry point with subcommands
 - **`agentMain.ts`**: Single-user agent mode implementation
 - **`chatMain.ts`**: Multi-user chat server/client implementation
@@ -51,28 +55,33 @@ Example of running agent can be found in [test script](../mcppro/scripts/test_sc
 ### Agent Mode
 
 **Basic conversation:**
+
 ```bash
 cli/agent-cli
 ```
 
 **One-shot with specific prompt:**
+
 ```bash
 echo "Explain quantum computing" > prompt.txt
 cli/agent-cli -1 --prompt prompt.txt
 ```
 
 **With image analysis:**
+
 ```bash
 echo "Describe this image" > prompt.txt
 cli/agent-cli --image photo.jpg --prompt prompt.txt
 ```
 
 **Using agent profile:**
+
 ```bash
 cli/agent-cli --agent-profile agent/test_data/simplecalc_profile.json
 ```
 
 **Auto-approve tools:**
+
 ```bash
 echo "Calculate 15 * 23" > prompt.txt
 cli/agent-cli --approve-tools --prompt prompt.txt
@@ -81,11 +90,13 @@ cli/agent-cli --approve-tools --prompt prompt.txt
 ### Chat Mode
 
 **Start server:**
+
 ```bash
 node dist/agent/src/tool/main.js chat server --port 5003
 ```
 
 **Connect client:**
+
 ```bash
 node dist/agent/src/tool/main.js chat client \
   --session "project_discussion" \
@@ -93,6 +104,7 @@ node dist/agent/src/tool/main.js chat client \
 ```
 
 **Run scripted conversation:**
+
 ```bash
 node dist/agent/src/tool/main.js chat client \
   --session "test" \
@@ -104,18 +116,21 @@ node dist/agent/src/tool/main.js chat client \
 While in agent mode, use these commands:
 
 **Tool Management:**
+
 - `/ls` - List available MCP servers
-- `/lt` - List current tools (enabled marked with *)
+- `/lt` - List current tools (enabled marked with \*)
 - `/as <server>` - Add and enable all tools from server
 - `/e <server> <tool>` - Enable specific tool
 - `/d <server> <tool>` - Disable specific tool
 
 **Media and Data:**
+
 - `:i image.jpg` - Include image with next message
 - `/wc conversation.json` - Save conversation to file
 - `/wa profile.json` - Save agent profile to file
 
 **General:**
+
 - `/h` - Show help menu
 - `/q` - Quit
 
@@ -129,7 +144,7 @@ LLM_URL=http://localhost:5001/v1          # LLM API endpoint
 LLM_API_KEY=your_openai_key               # API key for LLM
 LLM_MODEL=gpt-4o                          # Model name
 
-# SudoMCP Integration  
+# SudoMCP Integration
 XMCP_URL=http://localhost:5001/           # SudoMCP backend URL
 API_KEY=your_sudomcp_key                  # SudoMCP API key
 
@@ -150,7 +165,7 @@ Agent profiles define the AI's behavior and available tools:
   "model": "gpt-4o",
   "system_prompt": "You are a helpful coding assistant.",
   "mcp_settings": {
-    "github": ["create_issue", "list_repos"],
+    "github": ["create_issue", "list_repos"]
   }
 }
 ```
@@ -197,7 +212,7 @@ yarn test -- --grep "DB"
 # Git commit message generation
 ./scripts/git_message
 
-# PR description generation  
+# PR description generation
 ./scripts/pr_message
 
 # Code review assistance
@@ -227,6 +242,6 @@ Save and restore conversation state:
 # Save conversation
 cli/agent agent --conversation-output saved_conversation.json
 
-# Restore conversation  
+# Restore conversation
 cli/agent --conversation saved_conversation.json
 ```

package/dist/agent/src/agent/agent.js

@@ -35,33 +35,30 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = exports.AgentProfile = void 0;
 exports.createUserMessage = createUserMessage;
+exports.createUserMessageEnsure = createUserMessageEnsure;
 const dotenv = __importStar(require("dotenv"));
 const mcpServerManager_1 = require("./mcpServerManager");
 const assert_1 = require("assert");
 const sdk_1 = require("@xalia/xmcp/sdk");
 var sdk_2 = require("@xalia/xmcp/sdk");
 Object.defineProperty(exports, "AgentProfile", { enumerable: true, get: function () { return sdk_2.AgentProfile; } });
+const MAX_TOOL_CALL_RESPONSE_LENGTH = 4000;
 dotenv.config();
 const logger = (0, sdk_1.getLogger)();
 class Agent {
-    constructor(onMessage, onToolCall, messages, mcpServerManager, tools, llm) {
-        this.onMessage = onMessage;
-        this.onToolCall = onToolCall;
-        this.messages = messages;
+    constructor(eventHandler, mcpServerManager, llm, contextManager) {
+        /// The full list of tools, ready to pass to the LLM
+        this.tools = [];
+        /// Handlers for "agent" (or "built-in") tools.  These do not require
+        /// approval from the user.
+        this.agentTools = new Map();
+        this.eventHandler = eventHandler;
         this.mcpServerManager = mcpServerManager;
-        this.tools = tools;
         this.llm = llm;
-        this.toolHandlers = {};
-    }
-    static async initializeWithLLM(onMessage, onToolCall, systemPrompt, llm, mcpServerManager) {
-        // Initialize messages with system prompt
-        const messages = [
-            {
-                role: "system",
-                content: systemPrompt ?? "You are a helpful assistant",
-            },
-        ];
-        return new Agent(onMessage, onToolCall, messages, mcpServerManager ?? new mcpServerManager_1.McpServerManager(), [], llm);
+        this.contextManager = contextManager;
+    }
+    static initializeWithLLM(eventHandler, llm, contextManager, mcpServerManager) {
+        return new Agent(eventHandler, mcpServerManager ?? new mcpServerManager_1.McpServerManager(), llm, contextManager);
     }
     async shutdown() {
         return this.mcpServerManager.shutdown();
@@ -70,16 +67,9 @@ class Agent {
         return new sdk_1.AgentProfile(this.llm.getModel(), this.getSystemPrompt(), this.mcpServerManager.getMcpServerSettings());
     }
     getConversation() {
-        (0, assert_1.strict)(this.messages[0].role == "system", "first message must have system role");
-        // Return a copy so future modifications to `this.messages` don't impact
-        // the callers copy.
-        return structuredClone(this.messages.slice(1));
-    }
-    setConversation(messages) {
-        (0, assert_1.strict)(this.messages[0].role == "system");
-        (0, assert_1.strict)(messages.length === 0 || messages[0].role != "system", "conversation contains system msg");
-        const newMessages = [this.messages[0]];
-        this.messages = newMessages.concat(structuredClone(messages));
+        const llmMessages = this.contextManager.getLLMContext();
+        (0, assert_1.strict)(llmMessages[0].role === "system", "first message must have system role");
+        return [...llmMessages.slice(1)];
     }
     getMcpServerManager() {
         return this.mcpServerManager;
@@ -95,45 +85,80 @@ class Agent {
         return this.userMessageRaw(userMessage);
     }
     async userMessageRaw(userMessage) {
-        this.messages.push(userMessage);
-        let completion = await this.chatCompletion();
+        return this.userMessagesRaw([userMessage]);
+    }
+    async userMessagesRaw(userMessages) {
+        // Note: `getLLMContext` returns a copy to we can mutate this array
+        const context = this.contextManager.getLLMContext();
+        const newMessagesIdx = context.length;
+        // Add the new user messages
+        context.push(...userMessages);
+        let completion = await this.chatCompletion(context);
         let message = completion.choices[0].message;
-        this.messages.push(message);
-        // While there are tool calls to make, make them and loop
+        context.push(message);
+        // While there are tool calls to make, invoke them and loop
         while (message.tool_calls && message.tool_calls.length > 0) {
+            // TODO: Execute all tool calls in parallel
+            // [indexInContext, ToolCallResult][]
+            const toolCallResults = [];
             for (const toolCall of message.tool_calls ?? []) {
-                const approval = await this.onToolCall(toolCall);
-                if (approval) {
-                    try {
-                        const result = await this.doToolCall(toolCall);
-                        logger.debug(`tool call result ${JSON.stringify(result)}`);
-                        this.messages.push(result);
-                    }
-                    catch (e) {
-                        logger.error(`tool call error: ${e}`);
-                        this.messages.push({
-                            role: "tool",
-                            tool_call_id: toolCall.id,
-                            content: "Tool call failed.",
-                        });
-                    }
-                }
-                else {
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: toolCall.id,
-                        content: "User denied tool use request.",
-                    });
+                // Execute the tool call, add the result to the context as an LLM
+                // mesage, and record the index of the message alongside the result in
+                // `toolCallResults`.
+                const result = await this.doToolCall(toolCall);
+                toolCallResults.push([context.length, result]);
+                context.push({
+                    role: "tool",
+                    tool_call_id: toolCall.id,
+                    content: result.response,
+                });
+                // If the tool call requested that its args be redacted, this can be
+                // done now - before the next LLM invocation.
+                if (result.overwriteArgs) {
+                    logger.debug(`updating args for toolcall ${toolCall.id}: ${result.overwriteArgs}`);
+                    toolCall.function.arguments = result.overwriteArgs;
+                    logger.debug(`agent message after update ${JSON.stringify(message)}`);
                 }
             }
-            completion = await this.chatCompletion();
-            message = completion.choices[0].message;
-            this.messages.push(message);
+            // Now that any args have been overwritten, signal the event handler of
+            // the prevoius completion.
+            this.eventHandler.onCompletion(message);
+            // Get a new completion using the untouched tool call results.  Note
+            // that, since we are deferring the `onToolCallResult` calls (so they
+            // can be redacted), we must take care that the errors in
+            // `chatCompletion` do not disrupt this, so the caller has a consistent
+            // view of the conversation state.
+            try {
+                completion = await this.chatCompletion(context); // CAN THROW
+                message = completion.choices[0].message;
+                context.push(message);
+            }
+            finally {
+                // Now that the tool call results have been passed to the LLM, perform
+                // any updates on them.  Pass the (updated) tool-call-result LLM
+                // messages to the event handler - note, we want to do this even if
+                // the an error occured, so that the caller has an up-to-date picture
+                // of the context state when the error occured.
+                toolCallResults.forEach(([indexInContext, tcr]) => {
+                    const ctxMsg = context[indexInContext];
+                    if (tcr.overwriteResponse) {
+                        ctxMsg.content = tcr.overwriteResponse;
+                    }
+                    (0, assert_1.strict)(ctxMsg.role === "tool");
+                    this.eventHandler.onToolCallResult(ctxMsg);
+                });
+                // Note, if an error DID occur, the ContextManager does not see any of
+                // the new context.
+            }
         }
+        // Signal the event handler of the final completion.
+        this.eventHandler.onCompletion(message);
+        // Add all new new messages to the context
+        this.contextManager.addMessages(context.slice(newMessagesIdx));
         return completion.choices[0].message;
     }
     userMessage(msg, imageB64) {
-        this.userMessageEx(msg, imageB64);
+        void this.userMessageEx(msg, imageB64);
     }
     getModel() {
         return this.llm.getModel();
@@ -142,69 +167,116 @@ class Agent {
         logger.debug(`Set model ${model}`);
         this.llm.setModel(model);
     }
-    /**
-     * Clear the conversation.
-     */
-    resetConversation() {
-        (0, assert_1.strict)(this.messages.length > 0);
-        // Keep only the system message
-        this.messages.splice(1);
-    }
     getSystemPrompt() {
-        (0, assert_1.strict)(this.messages[0].role === "system");
-        return this.messages[0].content;
+        return this.contextManager.getAgentPrompt();
     }
     /**
      * Set the system prompt
      */
     setSystemPrompt(systemMsg) {
-        (0, assert_1.strict)(this.messages[0].role === "system");
-        this.messages[0].content = systemMsg;
+        this.contextManager.setAgentPrompt(systemMsg);
     }
-    async chatCompletion() {
+    async chatCompletion(context) {
+        // Compute the full list of available tools
         let tools;
-        const enabledTools = this.tools.concat(this.mcpServerManager.getOpenAITools());
+        const mcpTools = this.mcpServerManager.getOpenAITools();
+        const enabledTools = this.tools.concat(mcpTools);
         if (enabledTools.length > 0) {
             tools = enabledTools;
         }
-        // logger.debug(
-        //   `chatCompletion: tools: ${JSON.stringify(tools, undefined, 2)}`
-        // );
-        const completion = await this.llm.getConversationResponse(this.messages, tools, this.onMessage);
+        const completion = await this.llm.getConversationResponse(context, tools, this.eventHandler.onAgentMessage.bind(this.eventHandler));
         logger.debug(`Received chat completion ${JSON.stringify(completion)}`);
         return completion;
     }
-    toolNames() {
-        return this.mcpServerManager
-            .getOpenAITools()
-            .map((tool) => tool.function.name);
+    addAgentToolProvider(toolProvider) {
+        return toolProvider.setup(this);
     }
-    addTool(tool, handler) {
+    addAgentTool(tool, handler) {
         const name = tool.function.name;
-        if (this.toolHandlers[name]) {
-            throw `tool ${name} already added`;
+        if (this.agentTools.has(name)) {
+            throw new Error(`tool ${name} already added`);
         }
         logger.debug(`Adding tool ${name}`);
         this.tools.push(tool);
-        this.toolHandlers[name] = handler;
+        this.agentTools.set(name, { handler });
+    }
+    removeAgentTool(name) {
+        if (!this.agentTools.has(name)) {
+            logger.warn(`[removeTool] tool ${name} not present`);
+        }
+        // Find idx of the tool in the list
+        const idx = (() => {
+            let idx = 0;
+            while (idx < this.tools.length) {
+                if (this.tools[idx].function.name === name) {
+                    return idx;
+                }
+                idx++;
+            }
+            return -1;
+        })();
+        (0, assert_1.strict)(idx > -1);
+        // Remove entries
+        this.tools.splice(idx, 1);
+        this.agentTools.delete(name);
     }
+    /**
+     * Handle the details of getting approval (if required), invoking the tool
+     * handler, informing the IAgentEventHandler of the result, and returns the
+     * OpenAI.ChatCompletionToolMessageParam to be used in the conversation.
+     */
     async doToolCall(toolCall) {
-        const name = toolCall.function.name;
-        const args = JSON.parse(toolCall.function.arguments);
-        let result = undefined;
-        const handler = this.toolHandlers[name];
-        if (handler) {
-            logger.debug(`  found agent tool ${name} ...`);
-            result = handler(args);
+        // If the tool is and "agent" (internal) tool, we can just execute it.
+        // Otherwise, call the event handler to get permission and invoke the
+        // external tool handler.
+        let result;
+        try {
+            const toolName = toolCall.function.name;
+            const agentTool = this.agentTools.get(toolName);
+            const isAgentTool = !!agentTool;
+            const approve = await this.eventHandler.onToolCall(toolCall, isAgentTool);
+            if (!approve) {
+                result = { response: "User denied tool request." };
+            }
+            else if (isAgentTool) {
+                // Internal (agent) tool
+                const args = JSON.parse(toolCall.function.arguments);
+                result = await agentTool.handler(this, args);
+            }
+            else {
+                // McpServer tool call (agentTool === undefined)
+                const args = JSON.parse(toolCall.function.arguments);
+                result = {
+                    response: await this.mcpServerManager.invoke(toolName, args),
+                };
+                logger.debug(`tool call result ${JSON.stringify(result)}`);
+            }
         }
-        else {
-            result = await this.mcpServerManager.invoke(name, args);
+        catch (e) {
+            let msg;
+            if (e instanceof Error) {
+                msg = e.message;
+            }
+            else if (typeof e === "string") {
+                msg = e;
+            }
+            else {
+                msg = String(e);
+            }
+            logger.error(`tool call error: ${msg}`);
+            result = {
+                response: `tool call error: ${msg}`,
+            };
         }
-        return {
-            role: "tool",
-            tool_call_id: toolCall.id,
-            content: result.toString(),
-        };
+        // Final sanity check on the tool call response length.
+        if (result.response.length > MAX_TOOL_CALL_RESPONSE_LENGTH) {
+            logger.warn("[Agent.doToolCall]: truncating tool call result.response for call:\n" +
+                JSON.stringify(toolCall));
+            result.response =
+                result.response.slice(0, MAX_TOOL_CALL_RESPONSE_LENGTH) +
+                    " ..truncated";
+        }
+        return result;
     }
 }
 exports.Agent = Agent;
@@ -247,3 +319,8 @@ function createUserMessage(msg, imageB64, name) {
         name,
     };
 }
+function createUserMessageEnsure(msg, imageB64, name) {
+    const userMsg = createUserMessage(msg, imageB64, name);
+    (0, assert_1.strict)(userMsg);
+    return userMsg;
+}