@xalia/agent 0.5.8 → 0.6.1

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

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XALIA_APP_HEADER = exports.DEFAULT_LLM_MODEL = exports.DEFAULT_LLM_URL = void 0;
+exports.createAgentWithoutSkills = createAgentWithoutSkills;
 exports.createAgentWithSkills = createAgentWithSkills;
 exports.createAgentFromSkillManager = createAgentFromSkillManager;
+exports.createLLM = createLLM;
 exports.createNonInteractiveAgent = createNonInteractiveAgent;
 exports.runOneShot = runOneShot;
 const sdk_1 = require("@xalia/xmcp/sdk");
@@ -13,72 +15,70 @@ const openAILLMStreaming_1 = require("./openAILLMStreaming");
 const dummyLLM_1 = require("./dummyLLM");
 const assert_1 = require("assert");
 const repeatLLM_1 = require("./repeatLLM");
+const context_1 = require("./context");
 const logger = (0, sdk_1.getLogger)();
 exports.DEFAULT_LLM_URL = "http://localhost:5001/v1";
-exports.DEFAULT_LLM_MODEL = "gpt-4o";
+// uses openrouter
+exports.DEFAULT_LLM_MODEL = process.env["DEFAULT_LLM_MODEL"] || "openai/gpt-4o";
 exports.XALIA_APP_HEADER = {
     "HTTP-Referer": "xalia.ai",
     "X-Title": "Xalia",
 };
+async function createAgentWithoutSkills(llmUrl, agentProfile, eventHandler, platform, contextManager, llmApiKey, sudomcpConfig, authorizedUrl, stream = false) {
+    // Init SudoMcpServerManager
+    logger.debug("[createAgentWithSkills] creating SudoMcpServerManager.");
+    const sudoMcpServerManager = await sudoMcpServerManager_1.SkillManager.initialize((url, authResultP, displayName) => {
+        platform.openUrl(url, authResultP, displayName);
+    }, sudomcpConfig.backend_url, sudomcpConfig.api_key, authorizedUrl);
+    logger.debug("[createAgentWithoutSkills] restore mcp settings:" +
+        JSON.stringify(agentProfile.mcp_settings));
+    // Create agent using the event handler
+    const agent = await createAgentFromSkillManager(llmUrl, agentProfile, eventHandler, platform, contextManager, llmApiKey, sudoMcpServerManager, stream);
+    return [agent, sudoMcpServerManager];
+}
 /**
- * Util function to create an Agent from some config information.
+ * Create and initialize an Agent given an AgentProfile using the
+ * IAgentEventHandler interface. This is the preferred way to create
+ * agents.
  */
-async function createAgent(llmUrl, model, systemPrompt, onMessage, onToolCall, platform, openaiApiKey, stream = false, mcpServerManager) {
+async function createAgentWithSkills(llmUrl, agentProfile, eventHandler, platform, contextManager, llmApiKey, sudomcpConfig, authorizedUrl, stream = false) {
+    const [agent, sudoMcpServerManager] = await createAgentWithoutSkills(llmUrl, agentProfile, eventHandler, platform, contextManager, llmApiKey, sudomcpConfig, authorizedUrl, stream);
+    logger.debug("[createAgentWithSkills] restoring skills");
+    await sudoMcpServerManager.restoreMcpSettings(agentProfile.mcp_settings);
+    return [agent, sudoMcpServerManager];
+}
+async function createAgentFromSkillManager(llmUrl, agentProfile, eventHandler, platform, contextManager, llmApiKey, skillManager, stream = false) {
+    // Create agent
+    logger.debug("[createAgentFromSkillManager] creating agent ...");
+    const llm = await createLLM(llmUrl, llmApiKey, agentProfile.model, stream, platform);
+    contextManager.setAgentPrompt(agentProfile.system_prompt);
+    const agent = agent_1.Agent.initializeWithLLM(eventHandler, llm, contextManager, skillManager);
+    logger.debug("[createAgentFromSkillManager] done");
+    return agent;
+}
+async function createLLM(llmUrl, llmApiKey, model, stream = false, platform) {
     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);
+        llm = await dummyLLM_1.DummyLLM.initFromModelUrl(model, platform);
     }
     else if (model === "repeat") {
         llm = new repeatLLM_1.RepeatLLM();
     }
     else {
         // Regular Agent
-        if (!openaiApiKey) {
-            throw "Missing OpenAI API Key";
+        if (!llmApiKey) {
+            throw new Error("Missing OpenAI API Key");
         }
-        logger.debug(`Initializing Agent: ${llmUrl} - ${model}`);
+        logger.debug(`Initializing Agent: ${llmUrl ?? "unknown"} - ${model ?? "unknown"}`);
         if (stream) {
-            llm = new openAILLMStreaming_1.OpenAILLMStreaming(openaiApiKey, llmUrl, model);
+            llm = new openAILLMStreaming_1.OpenAILLMStreaming(llmApiKey, llmUrl, model);
         }
         else {
-            llm = new openAILLM_1.OpenAILLM(openaiApiKey, llmUrl, model);
+            llm = new openAILLM_1.OpenAILLM(llmApiKey, llmUrl, model);
         }
     }
     (0, assert_1.strict)(llm);
-    return agent_1.Agent.initializeWithLLM(onMessage, onToolCall, systemPrompt, llm, mcpServerManager);
-}
-/**
- * Util function to create and initialize an Agent given an AgentProfile.
- */
-async function createAgentWithSkills(llmUrl, agentProfile, onMessage, onToolCall, platform, llmApiKey, sudomcpConfig, authorizedUrl, conversation, stream = false) {
-    // Init SudoMcpServerManager
-    logger.debug("[createAgentWithSkills] creating SudoMcpServerManager.");
-    const sudoMcpServerManager = await sudoMcpServerManager_1.SkillManager.initialize(platform.openUrl, sudomcpConfig.backend_url, sudomcpConfig.api_key, authorizedUrl);
-    logger.debug("[createAgentWithSkills] restore mcp settings:" +
-        JSON.stringify(agentProfile.mcp_settings));
-    await sudoMcpServerManager.restoreMcpSettings(agentProfile.mcp_settings);
-    // Create agent using the McpServerManager just created
-    const agent = await createAgentFromSkillManager(llmUrl, agentProfile, onMessage, onToolCall, platform, llmApiKey, sudoMcpServerManager, conversation, stream);
-    return [agent, sudoMcpServerManager];
-}
-async function createAgentFromSkillManager(llmUrl, agentProfile, onMessage, onToolCall, platform, llmApiKey, skillManager, conversation, stream = false) {
-    // Create agent
-    logger.debug("[createAgentFromSkillManager] creating agent ...");
-    const agent = await createAgent(llmUrl, agentProfile.model, agentProfile.system_prompt, onMessage, onToolCall, platform, llmApiKey, stream, skillManager);
-    if (conversation) {
-        agent.setConversation(conversation);
-    }
-    logger.debug("[createAgentFromSkillManager] done");
-    return agent;
+    return llm;
 }
 /**
  * An "non-interactive" agent is one which is not intended to be used
@@ -88,15 +88,21 @@ async function createAgentFromSkillManager(llmUrl, agentProfile, onMessage, onTo
  */
 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 eventHandler = {
+        onCompletion: () => { },
+        onAgentMessage: async () => { },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        onToolCall: async () => {
+            if (remainingToolCalls !== 0) {
+                --remainingToolCalls;
+                return true;
+            }
+            return false;
+        },
+        onToolCallResult: () => { },
     };
-    const [agent, _] = await createAgentWithSkills(url, agentProfile, onMessage, onToolCall, platform, openaiApiKey, sudomcpConfig, undefined, conversation);
+    const contextManager = new context_1.ContextManager(agentProfile.system_prompt, conversation || []);
+    const [agent, _] = await createAgentWithSkills(url, agentProfile, eventHandler, platform, contextManager, openaiApiKey, sudomcpConfig, undefined);
     return agent;
 }
 /**
@@ -112,10 +118,33 @@ async function runOneShot(url, agentProfile, conversation, platform, prompt, ima
     await agent.shutdown();
     logger.debug("[runOneShot]: shutdown done");
     if (!response) {
-        throw "No message returned from agent";
+        throw new Error("No message returned from agent");
+    }
+    // Handle different content types
+    let responseText = "";
+    if (typeof response.content === "string") {
+        responseText = response.content;
+    }
+    else if (response.content === null || response.content === undefined) {
+        responseText = "";
+    }
+    else if (Array.isArray(response.content)) {
+        // Handle array of content parts
+        responseText = response.content
+            .map((part) => {
+            if ("text" in part) {
+                return part.text;
+            }
+            return "";
+        })
+            .join("");
+    }
+    else {
+        // Fallback for other types
+        responseText = String(response.content);
     }
     return {
-        response: "" + response.content,
+        response: responseText,
         conversation: agent.getConversation(),
     };
 }

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

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompressingContextManager = void 0;
+exports.createCheckpointMessage = createCheckpointMessage;
+exports.createCompressionAgent = createCompressionAgent;
+exports.createSummary = createSummary;
+const assert_1 = require("assert");
+const sdk_1 = require("@xalia/xmcp/sdk");
+const agent_1 = require("./agent");
+const nullPlatform_1 = require("./nullPlatform");
+const agentUtils_1 = require("./agentUtils");
+const context_1 = require("./context");
+const nullAgentEventHandler_1 = require("./nullAgentEventHandler");
+const logger = (0, sdk_1.getLogger)();
+/**
+ * System prompt used to generate a conversation summary.
+ */
+const COMPRESSION_SYSTEM_PROMPT = 
+// eslint-disable-next-line max-len
+"You are a context summarizer, creating MINIMAL conversation digests which can be used to CONTINUE the conversation at a later date. TOKEN EFFICIENCY is a HIGH PRIORITY. Summaries will only be seen by LLMs and should USE ANY AND ALL ABBREVIATIONS to keep them as CONCISE as possible, while PRESERVING IMPORTANT DETAILS of the CONVERSATION.";
+/**
+ * Text prepended to a summary to create the checkpoint message
+ */
+const CHECKPOINT_MESSAGE_PREFIX = 
+// eslint-disable-next-line max-len
+"We are continuing an earlier conversation. The remainder of this message is a summary of the conversation so far: ";
+function createCheckpointMessage(summary) {
+    return {
+        role: "user",
+        content: CHECKPOINT_MESSAGE_PREFIX + summary,
+    };
+}
+async function createCompressionAgent(compressionAgentUrl, compressionAgentModel, compressionAgentApiKey) {
+    const llm = await (0, agentUtils_1.createLLM)(compressionAgentUrl, compressionAgentApiKey, compressionAgentModel, false /* stream */, nullPlatform_1.NULL_PLATFORM);
+    return agent_1.Agent.initializeWithLLM(nullAgentEventHandler_1.NULL_AGENT_EVENT_HANDLER, llm, new context_1.ContextManager(COMPRESSION_SYSTEM_PROMPT, []));
+}
+async function createSummary(compressionAgentUrl, compressionAgentModel, compressionAgentApiKey, conversation) {
+    const agent = await createCompressionAgent(compressionAgentUrl, compressionAgentModel, compressionAgentApiKey);
+    const resp = await agent.userMessageEx(JSON.stringify(conversation));
+    if (!resp) {
+        throw new Error("compression agent returned null");
+    }
+    (0, assert_1.strict)(resp.role === "assistant");
+    (0, assert_1.strict)(typeof resp.content === "string", "expected string content from compression agent");
+    return resp.content;
+}
+/**
+ * Can perform compression on the committed part of the context. Caller (not
+ * the Agent) is responsible for committing the conversation and triggering
+ * compression.
+ */
+class CompressingContextManager extends context_1.ContextManagerWithCommit {
+    constructor(systemPrompt, messages, compressionAgentUrl, compressionAgentModel, compressionAgentApiKey) {
+        super(systemPrompt, messages);
+        this.compressionAgentUrl = compressionAgentUrl;
+        this.compressionAgentModel = compressionAgentModel;
+        this.compressionAgentApiKey = compressionAgentApiKey;
+        this.compressingMessages = undefined;
+        // Sanity check the conversation form.
+        //
+        // Ordinarily, the committed context should end with an "assistant"
+        // message (i.e. user messages, an agent loop terminating in a final agent
+        // response).  However, if a conversation has been compressed, we may have
+        // only the summary, which is a "user" message.  In this case, this should
+        // be the only message.
+        const numMessages = this.numMessages();
+        const lastMessage = this.lastMessage();
+        if (lastMessage) {
+            const finalRole = lastMessage.role;
+            if (finalRole === "user") {
+                (0, assert_1.strict)(numMessages === 1);
+            }
+            else {
+                (0, assert_1.strict)(finalRole === "assistant", `unexpected final role ${finalRole}`);
+            }
+        }
+    }
+    async compress() {
+        // Only select messages for compression if they have been committed.
+        const numToCompress = this.getCommittedLength();
+        const messagesToCompress = this.leadingMessages(numToCompress);
+        (0, assert_1.strict)(messagesToCompress.length === numToCompress);
+        this.compressingMessages = numToCompress;
+        (0, assert_1.strict)(this.compressingMessages > 1, "<2 messages commited in the context");
+        logger.debug(`[CompressingContextManager] start (${String(this.compressingMessages)})`);
+        try {
+            const summary = await createSummary(this.compressionAgentUrl, this.compressionAgentModel, this.compressionAgentApiKey, messagesToCompress);
+            logger.debug(`[CompressingContextManager] summary: ${summary}`);
+            // Replace the context `messages` and update `lastCommittedMessage`
+            // index.
+            const checkpointMessage = createCheckpointMessage(summary);
+            (0, assert_1.strict)(typeof checkpointMessage.content === "string");
+            this.replaceLeadingMessages(numToCompress, checkpointMessage);
+            return summary;
+        }
+        finally {
+            this.compressingMessages = undefined;
+            logger.debug(`[CompressingContextManager] compression done`);
+        }
+    }
+}
+exports.CompressingContextManager = CompressingContextManager;

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

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextManagerWithCommit = exports.ContextManagerWithWorkspace = exports.ContextManager = void 0;
+const assert_1 = require("assert");
+const promptProvider_1 = require("./promptProvider");
+/**
+ * Trivial implementation of IContextManage which just manages the context as
+ * an array of `ChatCompletionMessageParam[]`
+ */
+class ContextManager {
+    constructor(systemPrompt, messages) {
+        (0, assert_1.strict)(messages.length === 0 || messages[0].role !== "system");
+        // Insert system message at the beginning if not present
+        if (messages.length === 0 || messages[0].role !== "system") {
+            this.messages = [
+                {
+                    role: "system",
+                    content: "",
+                },
+                ...messages,
+            ];
+        }
+        else {
+            (0, assert_1.strict)(false);
+            // this.messages = [...conversationMessages];
+            // this.messages[0] = {systemPrompt;
+        }
+        this.systemPromptProvider = new promptProvider_1.SystemPromptProvider(systemPrompt);
+    }
+    numMessages() {
+        return this.messages.length - 1;
+    }
+    lastMessage() {
+        if (this.messages.length > 1) {
+            return this.messages[this.messages.length - 1];
+        }
+        return undefined;
+    }
+    leadingMessages(numMessages) {
+        return this.messages.slice(1, numMessages + 1);
+    }
+    trailingMessagesFrom(idx) {
+        return this.messages.slice(1 + idx);
+    }
+    addMessages(messages) {
+        for (const message of messages) {
+            this.messages.push(message);
+        }
+    }
+    addMessage(message) {
+        this.messages.push(message);
+    }
+    getLLMContext() {
+        return this.getLLMContextRaw().slice();
+    }
+    replaceLeadingMessages(numMessagesToReplace, replacement) {
+        (0, assert_1.strict)(this.messages.length >= 1 + numMessagesToReplace);
+        const remainingMsgs = this.messages.slice(1 + numMessagesToReplace);
+        this.messages = [this.messages[0], replacement, ...remainingMsgs];
+    }
+    popMessage() {
+        if (this.messages.length > 1) {
+            return this.messages.pop();
+        }
+        return undefined;
+    }
+    getAgentPrompt() {
+        return this.systemPromptProvider.getAgentPrompt();
+    }
+    setAgentPrompt(prompt) {
+        this.systemPromptProvider.setAgentPrompt(prompt);
+    }
+    setPromptFragment(fragmentID, prompt) {
+        this.systemPromptProvider.setFragment(fragmentID, prompt);
+    }
+    removePromptFragment(fragmentID) {
+        this.systemPromptProvider.removeFragment(fragmentID);
+    }
+    /// Returns the actual array (so that child classes can avoid an unnecessary
+    /// copy)
+    getLLMContextRaw() {
+        (0, assert_1.strict)(this.messages[0].role === "system");
+        this.messages[0].content = this.systemPromptProvider.getSystemPrompt();
+        return this.messages;
+    }
+}
+exports.ContextManager = ContextManager;
+/**
+ * Maintain a trailing "workspace" message at the end of the context.
+ */
+class ContextManagerWithWorkspace extends ContextManager {
+    constructor(systemPrompt, conversationMessages) {
+        super(systemPrompt, conversationMessages);
+        super.addMessage({ role: "user", content: "" });
+    }
+    numMessages() {
+        return super.numMessages() - 1;
+    }
+    lastMessage() {
+        const totalNum = super.numMessages();
+        if (totalNum < 2) {
+            return undefined;
+        }
+        const trailing = super.trailingMessagesFrom(totalNum - 2);
+        return trailing[0];
+    }
+    trailingMessagesFrom(idx) {
+        const trailing = super.trailingMessagesFrom(idx);
+        return trailing.slice(0, trailing.length - 1);
+    }
+    addMessages(messages) {
+        const workspaceMsg = super.popMessage();
+        (0, assert_1.strict)(workspaceMsg);
+        super.addMessages(messages);
+        super.addMessage(workspaceMsg);
+    }
+    addMessage(message) {
+        const workspaceMsg = super.popMessage();
+        (0, assert_1.strict)(workspaceMsg);
+        super.addMessages([message, workspaceMsg]);
+    }
+    getLLMContext() {
+        const context = super.getLLMContextRaw();
+        const workspace = super.lastMessage();
+        (0, assert_1.strict)(workspace);
+        if (workspace.content === "") {
+            return context.slice(0, context.length - 1);
+        }
+        return context.slice();
+    }
+    popMessage() {
+        const workspaceMsg = super.popMessage();
+        (0, assert_1.strict)(workspaceMsg);
+        const msg = super.popMessage();
+        super.addMessage(workspaceMsg);
+        return msg;
+    }
+    getWorkspace() {
+        const workspace = super.lastMessage();
+        (0, assert_1.strict)(workspace);
+        (0, assert_1.strict)(workspace.role === "user");
+        if (workspace.content === "") {
+            return undefined;
+        }
+        return workspace;
+    }
+    /**
+     * Replace (or remove) the workspace message
+     */
+    setWorkspace(userMessage) {
+        if (!userMessage) {
+            userMessage = { role: "user", content: "" };
+        }
+        // Replace the workspace message.
+        super.popMessage();
+        super.addMessage(userMessage);
+    }
+}
+exports.ContextManagerWithWorkspace = ContextManagerWithWorkspace;
+/**
+ * ContextManagerWithCommit
+ *
+ * Allows the user to distinguish between messages that are still part of an
+ * on-going agent loop.
+ */
+class ContextManagerWithCommit extends ContextManagerWithWorkspace {
+    constructor(systemPrompt, messages) {
+        super(systemPrompt, messages);
+        // Use `this.messages` to initialize the index since this is well-formed
+        // (starts with "system")
+        this.numCommitted = this.numMessages();
+    }
+    getPending() {
+        (0, assert_1.strict)(this.numCommitted <= this.numMessages());
+        return this.trailingMessagesFrom(this.numCommitted);
+    }
+    getCommittedLength() {
+        // this.lastCommittedMessage + 1 - 1 (system message)
+        return this.numCommitted;
+    }
+    commit() {
+        this.numCommitted = this.numMessages();
+    }
+    replaceLeadingMessages(numMessages, replacement) {
+        super.replaceLeadingMessages(numMessages, replacement);
+        this.numCommitted -= numMessages - 1;
+    }
+}
+exports.ContextManagerWithCommit = ContextManagerWithCommit;

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

@@ -2,29 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DummyLLM = void 0;
 const assert_1 = require("assert");
+const sdk_1 = require("@xalia/xmcp/sdk");
+const logger = (0, sdk_1.getLogger)();
+/// Supports model-urls:
+///
+///   dummy:[{"index":0,"message":{"role":"assistant","content":"message 1"},
+///         "finish_reason":"stop"}]
+///                    (OpenAI.Chat.Completions.ChatCompletion.Choice[] as JSON)
+///   dummy:<filename>
+///
 class DummyLLM {
     constructor(responses) {
         this.responses = responses;
         this.idx = 0;
     }
+    static async initFromModelUrl(modelUrl, platform) {
+        // Dummy LLM
+        (0, assert_1.strict)(modelUrl.startsWith("dummy:"));
+        const scriptUrl = modelUrl.slice(6);
+        let script;
+        try {
+            script = JSON.parse(scriptUrl);
+        }
+        catch (e) {
+            logger.debug(`[DummyLLM.init] failed to parse model url as json: ${String(e)}`);
+        }
+        if (!script) {
+            try {
+                const scriptTxt = await platform.load(scriptUrl);
+                script = JSON.parse(scriptTxt);
+            }
+            catch (e) {
+                throw new Error("model URL error: invalid JSON and load (as filename) failed: " +
+                    String(e));
+            }
+        }
+        logger.debug(`Initialized Dummy Agent: ${modelUrl}`);
+        return new DummyLLM(script);
+    }
     getModel() {
-        return "dummy";
+        // Returns as a data-url
+        return "dummy:" + JSON.stringify(this.responses);
     }
     getUrl() {
-        throw "cannot get url for DummyLLM";
+        return "";
     }
-    async getConversationResponse(_messages, _tools, onMessage) {
+    async getConversationResponse(messages, _tools, onMessage) {
         await new Promise((r) => setTimeout(r, 0));
         (0, assert_1.strict)(this.idx < this.responses.length);
+        this.lastRequest = messages;
         const response = this.responses[this.idx++];
+        if (response.finish_reason === "error") {
+            throw new Error(response.message);
+        }
         if (onMessage) {
             const message = response.message;
             if (message.content) {
-                onMessage(message.content, true);
+                void onMessage(message.content, true);
             }
         }
         return {
-            id: "" + this.idx,
+            id: String(this.idx),
             choices: [response],
             created: Date.now(),
             model: "dummyLlmModel",
@@ -34,5 +72,8 @@ class DummyLLM {
     setModel(_model) {
         (0, assert_1.strict)(false, "unexpected call to setModel");
     }
+    getLastRequest() {
+        return this.lastRequest;
+    }
 }
 exports.DummyLLM = DummyLLM;

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });