@xalia/agent 0.6.8 → 0.6.10

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Agent = exports.DEFAULT_LLM_URL = exports.AgentProfile = void 0;
+exports.Agent = exports.AgentEx = exports.USER_STOP_MESSAGE = exports.DEFAULT_LLM_URL = exports.AgentProfile = void 0;
 exports.createUserMessage = createUserMessage;
 exports.createUserMessageEnsure = createUserMessageEnsure;
 exports.completionToAssistantMessageParam = completionToAssistantMessageParam;
@@ -9,52 +9,49 @@ var sdk_1 = require("@xalia/xmcp/sdk");
 Object.defineProperty(exports, "AgentProfile", { enumerable: true, get: function () { return sdk_1.AgentProfile; } });
 const sdk_2 = require("@xalia/xmcp/sdk");
 const mcpServerManager_1 = require("./mcpServerManager");
+const toolSettings_1 = require("./toolSettings");
 exports.DEFAULT_LLM_URL = "http://localhost:5001/v1";
-const MAX_TOOL_CALL_RESPONSE_LENGTH = 4000;
+/**
+ * The message to append to the agent output if the agent is interrupted by a
+ * signal from the user.
+ */
+exports.USER_STOP_MESSAGE = " AGENT INTERRUPTED";
 const logger = (0, sdk_2.getLogger)();
-class Agent {
-    constructor(eventHandler, mcpServerManager, llm, contextManager) {
+/**
+ * An agent attached to an ILLM which updates a context via an
+ * IContextTransaction interface (where IContextTransaction is like a DB tx or
+ * DB writer, for staging changes and reading back state as-if those changes
+ * were applied).
+ */
+class AgentEx {
+    constructor(mcpServerManager, llm) {
         /// 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.llm = llm;
-        this.contextManager = contextManager;
-    }
-    static initializeWithLLM(eventHandler, llm, contextManager, mcpServerManager) {
-        return new Agent(eventHandler, mcpServerManager ?? new mcpServerManager_1.McpServerManager(), llm, contextManager);
+        this.stopFlag = false;
+        this.stopFn = undefined;
     }
     async shutdown() {
+        this.stop("shutting down");
         return this.mcpServerManager.shutdown();
     }
-    getAgentProfile() {
-        return new sdk_2.AgentProfile(this.llm.getModel(), this.getSystemPrompt(), this.mcpServerManager.getMcpServerSettings());
-    }
-    getConversation() {
-        const llmMessages = this.contextManager.getLLMContext();
-        (0, assert_1.strict)(llmMessages[0].role === "system", "first message must have system role");
-        return [...llmMessages.slice(1)];
+    stop(msg) {
+        this.stopFlag = true;
+        if (this.stopFn) {
+            this.stopFn(msg || exports.USER_STOP_MESSAGE);
+        }
     }
     getMcpServerManager() {
         return this.mcpServerManager;
     }
-    /**
-     * Like `userMessage`, but can be awaited, and accepts the user name.
-     */
-    async userMessageEx(msg, imageB64, name) {
-        const userMessage = createUserMessage(msg, imageB64, name);
-        if (!userMessage) {
-            return undefined;
-        }
-        return this.userMessageRaw(userMessage);
-    }
-    async userMessageRaw(userMessage) {
-        return this.userMessagesRaw([userMessage]);
-    }
-    async userMessagesRaw(userMessages) {
+    // TODO: rename
+    async userMessagesRaw(contextTx, eventHandler) {
+        this.stopFlag = false;
+        // New user messages have already been added to the `contextTx`.
         // Image and audio handling
         //
         // `ChatCompletions` (responses from the LLM) can contain `audio` and
@@ -63,19 +60,19 @@ class Agent {
         //
         // As such, our current approach is to extract all assistant-generated
         // media and return it separately.
-        // 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);
         const images = [];
         // We convert the `ChatCompletionsMessage` into a
         // `ChatCompletionAssistantMessageParam` and extract image data.
-        let completion = await this.chatCompletion(context);
-        let message = this.processCompletion(completion, images);
-        context.push(message);
+        let completion = await this.chatCompletion(contextTx.getLLMContext(), eventHandler);
+        let message = this.processCompletion(completion, images, eventHandler);
+        contextTx.addMessage(message);
         // While there are tool calls to make, invoke them and loop
         while (message.tool_calls && message.tool_calls.length > 0) {
+            // Signal the event handler of the assistant message with tool calls
+            // BEFORE processing tool results. This ensures the order of messages
+            // in pendingMessages matches the order in the LLM context:
+            // [user, assistant(tool_calls), tool_result, assistant(final)]
+            eventHandler.onCompletion(message);
             // TODO: Execute all tool calls in parallel
             // [indexInContext, ToolCallResult][]
             const toolCallResults = [];
@@ -83,8 +80,7 @@ class Agent {
                 // 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]);
+                const result = await this.doToolCall(toolCall, eventHandler);
                 const toolResult = {
                     role: "tool",
                     tool_call_id: toolCall.id,
@@ -94,7 +90,13 @@ class Agent {
                         ? { structuredContent: result.structuredContent }
                         : {}),
                 };
-                context.push(toolResult);
+                const toolResultHandle = contextTx.addMessage(toolResult);
+                toolCallResults.push([toolResultHandle, result]);
+                // Immediately broadcast the tool result to the frontend for UI
+                // feedback. This ensures the frontend knows the tool executed
+                // successfully without waiting for the next LLM completion to
+                // finish streaming
+                eventHandler.onToolCallResult(toolResult);
                 // If the tool call requested that its args be redacted, this can be
                 // done now - before the next LLM invocation.
                 if (result.overwriteArgs) {
@@ -103,63 +105,57 @@ class Agent {
                     logger.debug(`agent message after update ${JSON.stringify(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 = this.processCompletion(completion, images);
-                context.push(message);
+                completion = await this.chatCompletion(contextTx.getLLMContext(), eventHandler);
+                message = this.processCompletion(completion, images, eventHandler);
+                contextTx.addMessage(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 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];
+                // any updates on them if overwriteResponse was requested. If so, send
+                // the updated tool result to the frontend to replace the original.
+                toolCallResults.forEach(([handle, tcr]) => {
                     if (tcr.overwriteResponse) {
+                        const ctxMsg = contextTx.getMessage(handle);
                         ctxMsg.content = tcr.overwriteResponse;
+                        (0, assert_1.strict)(ctxMsg.role === "tool");
+                        eventHandler.onToolCallResult(ctxMsg);
                     }
-                    (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));
+        eventHandler.onCompletion(message);
         return { message, images: images.length === 0 ? undefined : images };
     }
-    userMessage(msg, imageB64) {
-        void this.userMessageEx(msg, imageB64);
-    }
-    getModel() {
-        return this.llm.getModel();
-    }
-    setModel(model) {
-        logger.debug(`Set model ${model}`);
-        this.llm.setModel(model);
-    }
-    getSystemPrompt() {
-        return this.contextManager.getAgentPrompt();
-    }
-    /**
-     * Set the system prompt
-     */
-    setSystemPrompt(systemMsg) {
-        this.contextManager.setAgentPrompt(systemMsg);
-    }
-    async chatCompletion(context) {
+    async chatCompletion(context, eventHandler) {
+        if (this.stopFlag) {
+            return {
+                id: "user_stopped",
+                choices: [
+                    {
+                        finish_reason: "stop",
+                        index: 0,
+                        message: {
+                            content: exports.USER_STOP_MESSAGE,
+                            role: "assistant",
+                            refusal: null,
+                        },
+                        logprobs: null,
+                    },
+                ],
+                created: Date.now(),
+                model: this.llm.getModel(),
+                object: "chat.completion",
+            };
+        }
         // Compute the full list of available tools
         let tools;
         const mcpTools = this.mcpServerManager.getOpenAITools();
@@ -169,7 +165,15 @@ class Agent {
             tools = enabledTools;
         }
         logger.debug(`[chatCompletion] tools: ${JSON.stringify(tools)}`);
-        const completion = await this.llm.getConversationResponse(context, tools, this.eventHandler.onAgentMessage.bind(this.eventHandler), this.eventHandler.onReasoning.bind(this.eventHandler));
+        // Log system prompt length
+        if (context.length > 0 && context[0].role === "system") {
+            const systemPrompt = context[0].content;
+            logger.info(`[chatCompletion] System prompt length: ${String(systemPrompt.length)}`);
+        }
+        const { stop, completion: completionP } = await this.llm.getConversationResponse(context, tools, eventHandler.onAgentMessage.bind(eventHandler), eventHandler.onReasoning.bind(eventHandler));
+        this.stopFn = stop;
+        const completion = await completionP;
+        this.stopFn = undefined;
         logger.debug(`Received chat completion ${JSON.stringify(completion)}`);
         return completion;
     }
@@ -210,7 +214,10 @@ class Agent {
      * handler, informing the IAgentEventHandler of the result, and returns the
      * ChatCompletionToolMessageParam to be used in the conversation.
      */
-    async doToolCall(toolCall) {
+    async doToolCall(toolCall, eventHandler) {
+        if (this.stopFlag) {
+            return { response: exports.USER_STOP_MESSAGE };
+        }
         // 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.
@@ -221,7 +228,7 @@ class Agent {
             const isAgentTool = !!agentTool;
             if (isAgentTool) {
                 // Internal (agent) tool
-                if (!(await this.eventHandler.onToolCall(toolCall, true))) {
+                if (!(await eventHandler.onToolCall(toolCall, true))) {
                     result = { response: "User denied tool request." };
                 }
                 else {
@@ -234,7 +241,7 @@ class Agent {
                 // tool call data, get approval, and then invoke.
                 const args = JSON.parse(toolCall.function.arguments || "{}");
                 const tc = this.mcpServerManager.verifyToolCall(toolName, args);
-                if (!(await this.eventHandler.onToolCall(toolCall, false))) {
+                if (!(await eventHandler.onToolCall(toolCall, false))) {
                     result = { response: "User denied tool request." };
                 }
                 else {
@@ -260,27 +267,102 @@ class Agent {
             };
         }
         // Final sanity check on the tool call response length.
-        if (result.response.length > MAX_TOOL_CALL_RESPONSE_LENGTH) {
+        if (result.response.length > toolSettings_1.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) +
+                result.response.slice(0, toolSettings_1.MAX_TOOL_CALL_RESPONSE_LENGTH) +
                     " ..truncated";
         }
         return result;
     }
-    processCompletion(completion, images) {
+    processCompletion(completion, images, eventHandler) {
         // Add any images into the list, and call the event handler
         const compMessage = completion.choices[0].message;
         if (compMessage.images) {
             for (const image of compMessage.images) {
-                this.eventHandler.onImage(image);
+                eventHandler.onImage(image);
                 images.push(image);
             }
         }
         return completionToAssistantMessageParam(compMessage);
     }
 }
+exports.AgentEx = AgentEx;
+/**
+ * Higher-level abstraction over AgentEx, which abstracts out the context
+ * transactions.  A single agent is associated with an IContextManager and
+ * internally creates and commits transactions during each call to
+ * `userMessage*`.
+ */
+class Agent {
+    constructor(eventHandler, mcpServerManager, llm, contextManager) {
+        this.eventHandler = eventHandler;
+        this.contextManager = contextManager;
+        this.agentEx = new AgentEx(mcpServerManager, llm);
+    }
+    static initializeWithLLM(eventHandler, llm, contextManager, mcpServerManager) {
+        return new Agent(eventHandler, mcpServerManager ?? new mcpServerManager_1.McpServerManager(), llm, contextManager);
+    }
+    async shutdown() {
+        return this.agentEx.shutdown();
+    }
+    getAgentProfile() {
+        return new sdk_2.AgentProfile(this.agentEx.llm.getModel(), this.getSystemPrompt(), this.agentEx.mcpServerManager.getMcpServerSettings());
+    }
+    getConversation() {
+        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.agentEx.mcpServerManager;
+    }
+    /**
+     * Like `userMessage`, but can be awaited, and accepts the user name.
+     */
+    async userMessageEx(msg, imageB64, name) {
+        const userMessage = createUserMessage(msg, imageB64, name);
+        if (!userMessage) {
+            return undefined;
+        }
+        return this.userMessageRaw(userMessage);
+    }
+    async userMessageRaw(userMessage) {
+        return this.userMessagesRaw([userMessage]);
+    }
+    async userMessagesRaw(userMessages) {
+        const tx = await this.contextManager.startTx(userMessages);
+        const result = await this.agentEx.userMessagesRaw(tx, this.eventHandler);
+        await this.contextManager.commit(tx);
+        return result;
+    }
+    userMessage(msg, imageB64) {
+        void this.userMessageEx(msg, imageB64);
+    }
+    getModel() {
+        return this.agentEx.llm.getModel();
+    }
+    setModel(model) {
+        logger.debug(`Set model ${model}`);
+        this.agentEx.llm.setModel(model);
+    }
+    getSystemPrompt() {
+        return this.contextManager.getAgentPrompt();
+    }
+    /**
+     * Set the system prompt
+     */
+    setSystemPrompt(systemMsg) {
+        this.contextManager.setAgentPrompt(systemMsg);
+    }
+    addAgentToolProvider(toolProvider) {
+        return this.agentEx.addAgentToolProvider(toolProvider);
+    }
+    addAgentTool(tool, handler) {
+        this.agentEx.addAgentTool(tool, handler);
+    }
+}
 exports.Agent = Agent;
 /**
  * Returns the ChatCompletionMessageParam constructed from (optional) text and
@@ -323,7 +405,7 @@ function createUserMessage(msg, imageB64, name) {
 }
 function createUserMessageEnsure(msg, imageB64, name) {
     const userMsg = createUserMessage(msg, imageB64, name);
-    (0, assert_1.strict)(userMsg);
+    (0, assert_1.strict)(userMsg, "createUserMessageEnsure");
     return userMsg;
 }
 function completionToAssistantMessageParam(compMessage) {

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgentWithoutSkills = createAgentWithoutSkills;
 exports.createAgentWithSkills = createAgentWithSkills;
 exports.createAgentFromSkillManager = createAgentFromSkillManager;
+exports.createSpecializedLLM = createSpecializedLLM;
 exports.createLLM = createLLM;
 exports.createNonInteractiveAgent = createNonInteractiveAgent;
 exports.runOneShot = runOneShot;
@@ -15,7 +16,6 @@ const dummyLLM_1 = require("./dummyLLM");
 const assert_1 = require("assert");
 const repeatLLM_1 = require("./repeatLLM");
 const context_1 = require("./context");
-const imageGenLLM_1 = require("./imageGenLLM");
 const logger = (0, sdk_1.getLogger)();
 async function createAgentWithoutSkills(llmUrl, model, eventHandler, platform, contextManager, llmApiKey, sudomcpConfig, authorizedUrl, stream = false) {
     // Init SudoMcpServerManager
@@ -46,30 +46,36 @@ async function createAgentFromSkillManager(llmUrl, model, eventHandler, platform
     logger.debug("[createAgentFromSkillManager] done");
     return agent;
 }
-async function createLLM(llmUrl, llmApiKey, model, stream = false, platform) {
+/**
+ * Interpret the `model` string to create a specialized agent (dummy, repeat,
+ * etc) or return undefined if a specialized agent has not been requested.
+ */
+async function createSpecializedLLM(model, platform) {
     let llm;
     if (model && model.startsWith("dummy:")) {
         llm = await dummyLLM_1.DummyLLM.initFromModelUrl(model, platform);
     }
-    else if (model === "repeat") {
-        llm = new repeatLLM_1.RepeatLLM();
+    else if (model && model.startsWith("repeat")) {
+        const prefix = model.startsWith("repeat:") ? model.slice(7) : "";
+        llm = new repeatLLM_1.RepeatLLM(prefix);
+    }
+    return llm;
+}
+async function createLLM(llmUrl, llmApiKey, model, stream = false, platform) {
+    let llm = await createSpecializedLLM(model, platform);
+    if (llm) {
+        return llm;
+    }
+    // Regular Agent
+    if (!llmApiKey) {
+        throw new Error("Missing OpenAI API Key");
     }
-    else if (model == imageGenLLM_1.DEFAULT_IMAGE_GEN_MODEL) {
-        logger.info("ImageGenLLM");
-        llm = new imageGenLLM_1.ImageGenLLM(llmApiKey, llmUrl, model);
+    logger.debug(`Initializing Agent: ${llmUrl ?? "unknown"} - ${model}`);
+    if (stream) {
+        llm = new openAILLMStreaming_1.OpenAILLMStreaming(llmApiKey, llmUrl, model);
     }
     else {
-        // Regular Agent
-        if (!llmApiKey) {
-            throw new Error("Missing OpenAI API Key");
-        }
-        logger.debug(`Initializing Agent: ${llmUrl ?? "unknown"} - ${model}`);
-        if (stream) {
-            llm = new openAILLMStreaming_1.OpenAILLMStreaming(llmApiKey, llmUrl, model);
-        }
-        else {
-            llm = new openAILLM_1.OpenAILLM(llmApiKey, llmUrl, model);
-        }
+        llm = new openAILLM_1.OpenAILLM(llmApiKey, llmUrl, model);
     }
     (0, assert_1.strict)(llm);
     return llm;

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

@@ -7,10 +7,9 @@ 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 contextWithWorkspace_1 = require("./contextWithWorkspace");
 const logger = (0, sdk_1.getLogger)();
 /**
  * System prompt used to generate a conversation summary.
@@ -30,12 +29,11 @@ function createCheckpointMessage(summary) {
         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);
+function createCompressionAgent(llm) {
     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);
+async function createSummary(llm, conversation) {
+    const agent = createCompressionAgent(llm);
     const agentResp = await agent.userMessageEx(JSON.stringify(conversation));
     if (!agentResp) {
         throw new Error("compression agent returned null");
@@ -50,12 +48,10 @@ async function createSummary(compressionAgentUrl, compressionAgentModel, compres
  * the Agent) is responsible for committing the conversation and triggering
  * compression.
  */
-class CompressingContextManager extends context_1.ContextManagerWithCommit {
-    constructor(systemPrompt, messages, compressionAgentUrl, compressionAgentModel, compressionAgentApiKey) {
+class CompressingContextManager extends contextWithWorkspace_1.ContextManagerWithWorkspace {
+    constructor(systemPrompt, messages, getLLM) {
         super(systemPrompt, messages);
-        this.compressionAgentUrl = compressionAgentUrl;
-        this.compressionAgentModel = compressionAgentModel;
-        this.compressionAgentApiKey = compressionAgentApiKey;
+        this.getLLM = getLLM;
         this.compressingMessages = undefined;
         // Sanity check the conversation form.
         //
@@ -77,15 +73,15 @@ class CompressingContextManager extends context_1.ContextManagerWithCommit {
         }
     }
     async compress() {
-        // Only select messages for compression if they have been committed.
-        const numToCompress = this.getCommittedLength();
+        const numToCompress = super.numMessages();
         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);
+            const llm = await this.getLLM();
+            const summary = await createSummary(llm, messagesToCompress);
             logger.debug(`[CompressingContextManager] summary: ${summary}`);
             // Replace the context `messages` and update `lastCommittedMessage`
             // index.