@xalia/agent 0.6.9 → 0.6.11

package/README.md

@@ -25,6 +25,17 @@ Example of running agent can be found in [test script](../mcppro/scripts/test_sc
 
 ## Architecture
 
+For a detailed explanation of the context system architecture, including how context is formed, compressed, and managed during agent execution, see:
+
+**📚 [Context System Architecture Documentation](../context_system.md)**
+
+This document covers:
+- Context window structure and composition
+- System prompt fragment injection
+- Automatic context compression
+- Session file handling
+- Transaction-based message flow
+
 ### Core Components
 
 #### Agent (`src/agent/`)

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Agent = exports.AgentEx = 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,9 +9,20 @@ 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)();
+/**
+ * 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
@@ -21,15 +32,25 @@ class AgentEx {
         this.agentTools = new Map();
         this.mcpServerManager = mcpServerManager;
         this.llm = llm;
+        this.stopFlag = false;
+        this.stopFn = undefined;
     }
     async shutdown() {
+        this.stop("shutting down");
         return this.mcpServerManager.shutdown();
     }
+    stop(msg) {
+        this.stopFlag = true;
+        if (this.stopFn) {
+            this.stopFn(msg || exports.USER_STOP_MESSAGE);
+        }
+    }
     getMcpServerManager() {
         return this.mcpServerManager;
     }
     // TODO: rename
     async userMessagesRaw(contextTx, eventHandler) {
+        this.stopFlag = false;
         // New user messages have already been added to the `contextTx`.
         // Image and audio handling
         //
@@ -47,6 +68,11 @@ class AgentEx {
         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 = [];
@@ -66,6 +92,11 @@ class AgentEx {
                 };
                 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) {
@@ -74,9 +105,6 @@ class AgentEx {
                     logger.debug(`agent message after update ${JSON.stringify(message)}`);
                 }
             }
-            // Now that any args have been overwritten, signal the event handler of
-            // the prevoius completion.
-            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
@@ -89,17 +117,15 @@ class AgentEx {
             }
             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.
+                // 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]) => {
-                    const ctxMsg = contextTx.getMessage(handle);
                     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");
-                    eventHandler.onToolCallResult(ctxMsg);
                 });
                 // Note, if an error DID occur, the ContextManager does not see any of
                 // the new context.
@@ -110,6 +136,26 @@ class AgentEx {
         return { message, images: images.length === 0 ? undefined : images };
     }
     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();
@@ -119,7 +165,15 @@ class AgentEx {
             tools = enabledTools;
         }
         logger.debug(`[chatCompletion] tools: ${JSON.stringify(tools)}`);
-        const completion = await this.llm.getConversationResponse(context, tools, eventHandler.onAgentMessage.bind(eventHandler), eventHandler.onReasoning.bind(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;
     }
@@ -161,6 +215,9 @@ class AgentEx {
      * ChatCompletionToolMessageParam to be used in the conversation.
      */
     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.
@@ -210,11 +267,11 @@ class AgentEx {
             };
         }
         // 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;
@@ -233,8 +290,10 @@ class AgentEx {
 }
 exports.AgentEx = AgentEx;
 /**
- * Higher-level abstraction over AgentEx, which abstracts out the transactions
- * to the context manager.
+ * 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) {
@@ -346,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

@@ -55,8 +55,9 @@ async function createSpecializedLLM(model, platform) {
     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;
 }

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

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMDocumentSummarizer = void 0;
+exports.createDocumentSummarizer = createDocumentSummarizer;
+exports.summarizeDocument = summarizeDocument;
+const openAIRouterLLM_1 = require("../chat/server/openAIRouterLLM");
+const sdk_1 = require("@xalia/xmcp/sdk");
+const logger = (0, sdk_1.getLogger)();
+const SUMMARY_MODEL = "google/gemini-2.5-flash";
+const SUMMARY_MAX_TOKENS = 500;
+const SUMMARY_TEMPERATURE = 0.3;
+const SUMMARY_TIMEOUT_MS = 30000;
+const MAX_CONTENT_LENGTH = 100000;
+/**
+ * System prompt for document summarization, optimized for recall.
+ */
+const SUMMARY_SYSTEM_PROMPT = `You are a document summarizer optimizing for RECALL. Create a summary ` +
+    `(3-10 sentences) that captures:
+- Main topic and purpose of the document
+- Key entities (names, organizations, places, dates, numbers)
+- Important concepts, terms, and topics mentioned
+- Any conclusions, results, or key findings
+
+Include specific details that would help locate this document later.
+Use keywords and phrases from the original text.
+Do NOT include meta-commentary about the document format.
+Output ONLY the summary text.`;
+class LLMDocumentSummarizer {
+    constructor(model = SUMMARY_MODEL) {
+        this.model = model;
+    }
+    async summarize(content) {
+        if (!content || content.trim().length === 0) {
+            return "Empty document";
+        }
+        try {
+            const summary = await this.summarizeWithTimeout(content);
+            return this.sanitizeSummary(summary);
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger.warn(`[DocumentSummarizer] LLM summarization failed: ${errorMsg}, ` +
+                `using fallback`);
+            return this.fallbackSummary(content);
+        }
+    }
+    async summarizeWithTimeout(content) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error("Summary generation timeout"));
+            }, SUMMARY_TIMEOUT_MS);
+        });
+        const summaryPromise = this.callLLM(content);
+        return Promise.race([summaryPromise, timeoutPromise]);
+    }
+    async callLLM(content) {
+        const client = (0, openAIRouterLLM_1.getOpenAIClient)(this.model);
+        const truncatedContent = content.length > MAX_CONTENT_LENGTH
+            ? content.slice(0, MAX_CONTENT_LENGTH) + "\n\n[Content truncated...]"
+            : content;
+        const response = await client.chat.completions.create({
+            model: this.model,
+            messages: [
+                {
+                    role: "system",
+                    content: SUMMARY_SYSTEM_PROMPT,
+                },
+                {
+                    role: "user",
+                    content: `Please summarize this document:\n\n${truncatedContent}`,
+                },
+            ],
+            max_tokens: SUMMARY_MAX_TOKENS,
+            temperature: SUMMARY_TEMPERATURE,
+        });
+        const summary = response.choices[0]?.message?.content?.trim();
+        if (!summary) {
+            throw new Error("Empty response from LLM");
+        }
+        return summary;
+    }
+    sanitizeSummary(summary) {
+        return summary.replace(/\s+/g, " ").trim();
+    }
+    fallbackSummary(content) {
+        const cleaned = content.trim();
+        if (cleaned.length === 0) {
+            return "Empty document";
+        }
+        const firstParagraph = cleaned.split(/\n\n/)[0];
+        const maxLength = 500;
+        if (firstParagraph.length <= maxLength) {
+            return firstParagraph;
+        }
+        return cleaned.slice(0, maxLength).trim() + "...";
+    }
+}
+exports.LLMDocumentSummarizer = LLMDocumentSummarizer;
+class FallbackDocumentSummarizer {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async summarize(content) {
+        const cleaned = content.trim();
+        if (cleaned.length === 0) {
+            return "Empty document";
+        }
+        const firstParagraph = cleaned.split(/\n\n/)[0];
+        const maxLength = 500;
+        if (firstParagraph.length <= maxLength) {
+            return firstParagraph;
+        }
+        return cleaned.slice(0, maxLength).trim() + "...";
+    }
+}
+function createDocumentSummarizer(model) {
+    if (process.env.DISABLE_LLM_SUMMARIES === "true") {
+        return new FallbackDocumentSummarizer();
+    }
+    return new LLMDocumentSummarizer(model);
+}
+/**
+ * Convenience function for one-off summarization.
+ */
+async function summarizeDocument(content) {
+    const summarizer = createDocumentSummarizer();
+    return summarizer.summarize(content);
+}

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

@@ -50,31 +50,34 @@ class DummyLLM {
     }
     async getConversationResponse(messages, _tools, onMessage, onReasoning) {
         await new Promise((r) => setTimeout(r, 0));
-        (0, assert_1.strict)(this.idx < this.responses.length);
         this.lastRequest = messages;
-        for (;;) {
-            const response = this.responses[this.idx++];
-            if (response.finish_reason === "error") {
-                throw new Error(response.message);
-            }
-            if (response.finish_reason === "reasoning") {
-                if (onReasoning) {
-                    await onReasoning(response.message);
+        const completion = (async () => {
+            for (;;) {
+                const idx = this.idx++;
+                const response = this.responses[idx % this.responses.length];
+                if (response.finish_reason === "error") {
+                    throw new Error(response.message);
                 }
-                continue;
-            }
-            if (onMessage) {
-                const message = response.message;
-                void onMessage(message.content || "", true);
+                if (response.finish_reason === "reasoning") {
+                    if (onReasoning) {
+                        await onReasoning(response.message);
+                    }
+                    continue;
+                }
+                if (onMessage) {
+                    const message = response.message;
+                    void onMessage(message.content || "", true);
+                }
+                return {
+                    id: String(idx),
+                    choices: [response],
+                    created: Date.now(),
+                    model: "dummyLlmModel",
+                    object: "chat.completion",
+                };
             }
-            return {
-                id: String(this.idx),
-                choices: [response],
-                created: Date.now(),
-                model: "dummyLlmModel",
-                object: "chat.completion",
-            };
-        }
+        })();
+        return { stop: () => { }, completion };
     }
     setModel(_model) {
         (0, assert_1.strict)(false, "unexpected call to setModel");

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

@@ -27,7 +27,7 @@ class ImageGenLLM {
     getUrl() {
         return this.openai.baseURL;
     }
-    async getConversationResponse(messages, tools, onMessage) {
+    getConversationResponse(messages, tools, onMessage) {
         (0, assert_1.strict)(!tools || tools.length === 0, "tools not supported in ImageGenLLM");
         // Designed for image generation using openrouter, which tweaks the Create
         const params = {
@@ -37,25 +37,28 @@ class ImageGenLLM {
             modalities: ["image", "text"],
         };
         logger.info(`[ImageGenLLM] params; ${JSON.stringify(params)}`);
-        const completion = (await this.openai.chat.completions.create(params));
-        // logger.debug(
-        //   `[ImageGenLLM.getConversationResponse] completion:
-        //   ${JSON.stringify(completion)}`
-        // );
-        if (onMessage) {
-            const message = completion.choices[0].message;
-            if (message.content) {
-                await onMessage(message.content, true);
+        const completion = (async () => {
+            const completion = (await this.openai.chat.completions.create(params));
+            // logger.debug(
+            //   `[ImageGenLLM.getConversationResponse] completion:
+            //   ${JSON.stringify(completion)}`
+            // );
+            if (onMessage) {
+                const message = completion.choices[0].message;
+                if (message.content) {
+                    await onMessage(message.content, true);
+                }
+                if (message.images) {
+                    message.images.forEach((image, index) => {
+                        const imageUrl = image.image_url.url; // Base64 data URL
+                        const truncated = imageUrl.substring(0, 50);
+                        logger.info(`[ImageGenLLM] ${String(index + 1)}: ${truncated}...`);
+                    });
+                }
             }
-            if (message.images) {
-                message.images.forEach((image, index) => {
-                    const imageUrl = image.image_url.url; // Base64 data URL
-                    const truncated = imageUrl.substring(0, 50);
-                    logger.info(`[ImageGenLLM] ${String(index + 1)}: ${truncated}...`);
-                });
-            }
-        }
-        return completion;
+            return completion;
+        })();
+        return Promise.resolve({ stop: () => { }, completion });
     }
 }
 exports.ImageGenLLM = ImageGenLLM;

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

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XALIA_APP_HEADER = void 0;
 exports.XALIA_APP_HEADER = {
-    "HTTP-Referer": "xalia.ai",
+    "HTTP-Referer": "https://xalia.ai",
     "X-Title": "Xalia",
 };

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

@@ -46,19 +46,22 @@ class OpenAILLM {
     getUrl() {
         return this.openai.baseURL;
     }
-    async getConversationResponse(messages, tools, onMessage) {
-        const completion = await this.openai.chat.completions.create({
-            model: this.model,
-            messages,
-            tools,
-        });
-        if (onMessage) {
-            const message = completion.choices[0].message;
-            if (message.content) {
-                await onMessage(message.content, true);
+    getConversationResponse(messages, tools, onMessage) {
+        const completion = (async () => {
+            const completion = await this.openai.chat.completions.create({
+                model: this.model,
+                messages,
+                tools,
+            });
+            if (onMessage) {
+                const message = completion.choices[0].message;
+                if (message.content) {
+                    await onMessage(message.content, true);
+                }
             }
-        }
-        return completionFromOpenAI(completion);
+            return completionFromOpenAI(completion);
+        })();
+        return Promise.resolve({ stop: () => { }, completion });
     }
 }
 exports.OpenAILLM = OpenAILLM;

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

@@ -439,47 +439,78 @@ class OpenAILLMStreaming {
         if (!chunks.iterator) {
             throw new Error("not a stream");
         }
-        let aggregatedMessage;
-        for await (const chunk of chunks) {
-            logger.debug(`[stream] chunk: ${JSON.stringify(chunk)}`);
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            if (chunk.object !== "chat.completion.chunk") {
-                // logger.warn("[stream]: unexpected message");
-                continue;
-            }
-            if (!aggregatedMessage) {
-                logger.debug(`[stream] first}`);
-                const { initMessage } = initializeCompletion(chunk);
-                aggregatedMessage = initMessage;
-            }
-            else {
-                updateCompletion(aggregatedMessage, chunk);
-            }
-            if (onMessage) {
-                // Inform the call of a message fragment if it contains any text.
-                // Note: chunks may have zero choices (e.g., usage-only chunks), so
-                // we safely access the first choice.
-                const delta = chunk.choices[0]?.delta;
+        let stopMsg = undefined;
+        const stop = (msg) => {
+            stopMsg = msg;
+        };
+        const completion = (async () => {
+            // Completion built up over successive calls to processChunk.
+            let aggregatedMessage;
+            const processChunk = async (chunk) => {
                 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-                if (delta?.content) {
-                    await onMessage(delta.content, false);
+                if (chunk.object !== "chat.completion.chunk") {
+                    // logger.warn("[stream]: unexpected message");
+                    return;
                 }
-            }
-            if (onReasoning) {
-                const delta = chunk.choices[0]
-                    ?.delta;
-                const reasoning = (0, openAI_1.choiceDeltaExtractReasoning)(delta);
-                if (reasoning) {
-                    await onReasoning(reasoning);
+                if (!aggregatedMessage) {
+                    logger.debug(`[stream] first}`);
+                    const { initMessage } = initializeCompletion(chunk);
+                    aggregatedMessage = initMessage;
+                }
+                else {
+                    updateCompletion(aggregatedMessage, chunk);
                 }
+                if (onMessage) {
+                    // Inform the call of a message fragment if it contains any text.
+                    // Note: chunks may have zero choices (e.g., usage-only chunks), so
+                    // we safely access the first choice.
+                    const delta = chunk.choices[0]?.delta;
+                    // eslint-disable-next-line
+                    if (delta?.content) {
+                        await onMessage(delta.content, false);
+                    }
+                }
+                if (onReasoning) {
+                    const delta = chunk.choices[0]
+                        ?.delta;
+                    const reasoning = (0, openAI_1.choiceDeltaExtractReasoning)(delta);
+                    if (reasoning) {
+                        await onReasoning(reasoning);
+                    }
+                }
+            };
+            // Process each chunk, checking for a stop signal.
+            for await (const chunk of chunks) {
+                logger.debug(`[stream] chunk: ${JSON.stringify(chunk)}`);
+                await processChunk(chunk);
+                /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+                if (stopMsg) {
+                    const choice = {
+                        delta: { content: stopMsg },
+                        finish_reason: aggregatedMessage && aggregatedMessage.choices[0].finish_reason
+                            ? null
+                            : "stop",
+                        index: 0,
+                    };
+                    await processChunk({
+                        id: aggregatedMessage?.id || "user_stop_chunk",
+                        created: aggregatedMessage?.created || Date.now(),
+                        model: aggregatedMessage?.model || model,
+                        object: "chat.completion.chunk",
+                        choices: [choice],
+                    });
+                    break;
+                }
+                /* eslint-enable @typescript-eslint/no-unnecessary-condition */
             }
-        }
-        if (onMessage) {
-            await onMessage("", true);
-        }
-        logger.debug(`[stream] final message: ${JSON.stringify(aggregatedMessage)}`);
-        (0, assert_1.strict)(aggregatedMessage);
-        return aggregatedMessage;
+            if (onMessage) {
+                await onMessage("", true);
+            }
+            logger.debug(`[stream] final message: ${JSON.stringify(aggregatedMessage)}`);
+            (0, assert_1.strict)(aggregatedMessage);
+            return aggregatedMessage;
+        })();
+        return { stop, completion };
     }
 }
 exports.OpenAILLMStreaming = OpenAILLMStreaming;