@xalia/agent 0.5.0

package/.prettierrc.json

@@ -0,0 +1,11 @@
+{
+  "overrides": [
+    {
+      "files": "*.ts",
+      "options": {
+        "printWidth": 80,
+        "trailingComma": "es5"
+      }
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,56 @@
+# Sudobase Agent
+
+## Setup
+
+```sh
+# In the root folder
+yarn
+yarn workspaces run build
+```
+
+Run a local backend server (follow instructions in `mcppro`) because authentication against deployed backend is WIP.
+
+## Usage:
+To enter a chat with no initial prompt and default system prompt:
+```sh
+node dist/main.js
+```
+
+Optional arguments are `prompt` (first User message) and `systemprompt`
+```sh
+node dist/main.js --prompt 'Who is the new pope?' --sysprompt 'You are extremely polite.'
+```
+
+## Features:
+### Conversation:
+CLI-mode is a conversation between user and LLM.
+
+### Tool selection:
+We now support MCP tool calls. Currently servers are enabled by editing the `mcpServerUrls.json` file, but this will be improved soon.
+
+### Model selection:
+The CLI uses the default model (`gpt-4o-mini`) but uncomment the `agent.chooseModel` line to switch to `gpt-4.1-2025-04-14`. Right now we can use any OpenAI model that supports tool calling.
+
+Supporting inference providers like Together.ai is TODO.
+
+### Callbacks
+The CLI uses an `onMessage` callback to display the Agent's messages and an `onToolCall` callback to request authorization for tool calls.
+
+## Development Notes
+
+### Architecture
+Frontend talks to
+  - Agent (for conversation, ChatCompletion)
+  - McpServerManager (to enable, disable tools that have been added)
+  - SudoMcpServerManager (to access catalog of SudoMCP servers, add to McpServerManager)
+
+SudoMcpServerManager:
+  - track list of available mcp servers (via sdk/ApiClient)
+  - get the list of tools as required by UI (via sdk/ApiClient)
+  - add tools to McpServerManager
+
+McpServerManager:
+  - manager (mcpServer, tool)
+  - enabling / disabling
+  - list of enabled / available tools per mcp server
+  - exposes tools to Agent

package/dist/agent.js

@@ -0,0 +1,238 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = exports.AgentProfile = void 0;
+exports.createUserMessage = createUserMessage;
+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; } });
+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;
+        this.mcpServerManager = mcpServerManager;
+        this.tools = tools;
+        this.llm = llm;
+        this.toolHandlers = {};
+    }
+    static async initializeWithLLM(onMessage, onToolCall, systemPrompt, llm) {
+        // Initialize messages with system prompt
+        const messages = [
+            {
+                role: "system",
+                content: systemPrompt ?? "You are a helpful assistant",
+            },
+        ];
+        // Create the server manager
+        const mcpServerManager = new mcpServerManager_1.McpServerManager();
+        return new Agent(onMessage, onToolCall, messages, mcpServerManager, [], llm);
+    }
+    async shutdown() {
+        return this.mcpServerManager.shutdown();
+    }
+    getAgentProfile() {
+        return new sdk_1.AgentProfile(this.llm.getModel(), this.getSystemMessage(), 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[0].role != "system", "conversation contains system msg");
+        const newMessages = [this.messages[0]];
+        this.messages = newMessages.concat(structuredClone(messages));
+    }
+    getMcpServerManager() {
+        return this.mcpServerManager;
+    }
+    async userMessage(msg, imageB64) {
+        const userMessage = createUserMessage(msg, imageB64);
+        if (!userMessage) {
+            return undefined;
+        }
+        this.messages.push(userMessage);
+        let completion = await this.chatCompletion();
+        let message = completion.choices[0].message;
+        this.messages.push(message);
+        // While there are tool calls to make, make them and loop
+        while (message.tool_calls && message.tool_calls.length > 0) {
+            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.",
+                    });
+                }
+            }
+            completion = await this.chatCompletion();
+            message = completion.choices[0].message;
+            this.messages.push(message);
+        }
+        return completion.choices[0].message;
+    }
+    chooseModel(model) {
+        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);
+    }
+    getSystemMessage() {
+        (0, assert_1.strict)(this.messages[0].role === "system");
+        return this.messages[0].content;
+    }
+    /**
+     * Set the system prompt
+     */
+    setSystemMessage(systemMsg) {
+        (0, assert_1.strict)(this.messages[0].role === "system");
+        this.messages[0].content = systemMsg;
+    }
+    async chatCompletion() {
+        let tools;
+        const enabledTools = this.tools.concat(this.mcpServerManager.getOpenAITools());
+        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);
+        logger.debug(`Received chat completion ${JSON.stringify(completion)}`);
+        return completion;
+    }
+    toolNames() {
+        return this.mcpServerManager
+            .getOpenAITools()
+            .map((tool) => tool.function.name);
+    }
+    addTool(tool, handler) {
+        const name = tool.function.name;
+        if (this.toolHandlers[name]) {
+            throw `tool ${name} already added`;
+        }
+        logger.debug(`Adding tool ${name}`);
+        this.tools.push(tool);
+        this.toolHandlers[name] = handler;
+    }
+    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);
+        }
+        else {
+            result = await this.mcpServerManager.invoke(name, args);
+        }
+        return {
+            role: "tool",
+            tool_call_id: toolCall.id,
+            content: result.toString(),
+        };
+    }
+}
+exports.Agent = Agent;
+/**
+ * Returns the ChatCompletionMessageParam constructed from (optional) text and
+ * (optional) image.  If neither is given (null message), then undefined is
+ * returned.
+ **/
+function createUserMessage(msg, imageB64) {
+    const content = (() => {
+        if (!imageB64) {
+            if (!msg) {
+                return undefined;
+            }
+            return msg;
+        }
+        const content = [];
+        if (msg) {
+            content.push({
+                type: "text",
+                text: msg,
+            });
+        }
+        if (imageB64) {
+            content.push({
+                type: "image_url",
+                image_url: {
+                    url: imageB64,
+                },
+            });
+        }
+        return content;
+    })();
+    if (!content) {
+        return undefined;
+    }
+    return {
+        role: "user",
+        content,
+    };
+}

package/dist/agentUtils.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LLM_URL = void 0;
+exports.createAgentAndSudoMcpServerManager = createAgentAndSudoMcpServerManager;
+exports.createNonInteractiveAgent = createNonInteractiveAgent;
+exports.runOneShot = runOneShot;
+const sdk_1 = require("@xalia/xmcp/sdk");
+const agent_1 = require("./agent");
+const sudoMcpServerManager_1 = require("./sudoMcpServerManager");
+const openAILLM_1 = require("./openAILLM");
+const openAILLMStreaming_1 = require("./openAILLMStreaming");
+const dummyLLM_1 = require("./dummyLLM");
+const assert_1 = require("assert");
+const logger = (0, sdk_1.getLogger)();
+exports.DEFAULT_LLM_URL = "http://localhost:5001/v1";
+/**
+ * Util function to create an Agent from some config information.
+ */
+async function createAgent(llmUrl, model, systemPrompt, onMessage, onToolCall, platform, openaiApiKey, stream = false) {
+    let llm;
+    if (model && model.startsWith("dummy:")) {
+        // Dummy Agent
+        const llmUrl = model.slice(6);
+        if (llmUrl.length === 0) {
+            throw "malformed dummy:<script>";
+        }
+        const script = await platform.load(llmUrl);
+        logger.debug(` script: ${script}`);
+        const responses = JSON.parse(script);
+        logger.debug(`Initializing Dummy Agent: ${llmUrl}`);
+        llm = new dummyLLM_1.DummyLLM(responses);
+    }
+    else {
+        // Regular Agent
+        if (!openaiApiKey) {
+            throw "Missing OpenAI API Key";
+        }
+        logger.debug(`Initializing Agent: ${llmUrl} - ${model}`);
+        if (stream) {
+            llm = new openAILLMStreaming_1.OpenAILLMStreaming(openaiApiKey, llmUrl, model);
+        }
+        else {
+            llm = new openAILLM_1.OpenAILLM(openaiApiKey, llmUrl, model);
+        }
+    }
+    (0, assert_1.strict)(llm);
+    return agent_1.Agent.initializeWithLLM(onMessage, onToolCall, systemPrompt, llm);
+}
+/**
+ * Util function to create and initialize an Agent given an AgentProfile.
+ */
+async function createAgentAndSudoMcpServerManager(url, agentProfile, onMessage, onToolCall, platform, openaiApiKey, sudomcpConfig, authorizedUrl, conversation, stream = false) {
+    // Create agent
+    logger.debug("[createAgentAndSudoMcpServerManager] creating agent ...");
+    const agent = await createAgent(url, agentProfile.model, agentProfile.system_prompt, onMessage, onToolCall, platform, openaiApiKey, stream);
+    if (conversation) {
+        agent.setConversation(conversation);
+    }
+    // Init SudoMcpServerManager
+    logger.debug("[createAgentAndSudoMcpServerManager] creating SudoMcpServerManager.");
+    const sudoMcpServerManager = await sudoMcpServerManager_1.SudoMcpServerManager.initialize(agent.getMcpServerManager(), platform.openUrl, sudomcpConfig.backend_url, sudomcpConfig.api_key, authorizedUrl);
+    logger.debug("[createAgentAndSudoMcpServerManager] restore mcp settings:" +
+        JSON.stringify(agentProfile.mcp_settings));
+    await sudoMcpServerManager.restoreMcpSettings(agentProfile.mcp_settings);
+    logger.debug("[createAgentAndSudoMcpServerManager] done");
+    return [agent, sudoMcpServerManager];
+}
+/**
+ * An "non-interactive" agent is one which is not intended to be used
+ * interactively (settings cannot be dyanmically adjusted, intermediate
+ * messages are not used by the caller, the user does not need to approve tool
+ * calls, etc).
+ */
+async function createNonInteractiveAgent(url, agentProfile, conversation, platform, openaiApiKey, sudomcpConfig, approveToolsUpTo) {
+    let remainingToolCalls = approveToolsUpTo;
+    const onMessage = async () => { };
+    const onToolCall = async () => {
+        if (remainingToolCalls !== 0) {
+            --remainingToolCalls;
+            return true;
+        }
+        return false;
+    };
+    const [agent, _] = await createAgentAndSudoMcpServerManager(url, agentProfile, onMessage, onToolCall, platform, openaiApiKey, sudomcpConfig, undefined, conversation);
+    return agent;
+}
+/**
+ * Create an Agent (from the AgentProfile), pass it a single prompt and output
+ * the response.
+ */
+async function runOneShot(url, agentProfile, conversation, platform, prompt, image, llmApiKey, sudomcpConfig, approveToolsUpTo) {
+    logger.debug("[runOneShot]: start");
+    // Create a non-interactive agent and pass any prompt/ image to it.  Return
+    // the first answer.
+    const agent = await createNonInteractiveAgent(url, agentProfile, conversation, platform, llmApiKey, sudomcpConfig, approveToolsUpTo);
+    const response = await agent.userMessage(prompt, image);
+    await agent.shutdown();
+    logger.debug("[runOneShot]: shutdown done");
+    if (!response) {
+        throw "No message returned from agent";
+    }
+    return {
+        response: "" + response.content,
+        conversation: agent.getConversation(),
+    };
+}