@xalia/agent 0.6.8 → 0.6.10

package/dist/agent/src/chat/server/chatContextManager.js

@@ -1,18 +1,123 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChatContextManager = void 0;
+exports.ChatContextManager = exports.ChatContextTransaction = void 0;
 exports.resolveConversationWithCheckpoint = resolveConversationWithCheckpoint;
 const assert_1 = require("assert");
 const sdk_1 = require("@xalia/xmcp/sdk");
-const agent_1 = require("../../agent/agent");
 const compressingContextManager_1 = require("../../agent/compressingContextManager");
 const conversation_1 = require("./conversation");
-const sessionFileManager_1 = require("./sessionFileManager");
+const fileManager_1 = require("../../agent/tools/fileManager");
+const errorUtils_1 = require("./errorUtils");
+const agent_1 = require("../../agent/agent");
+const tokenCounter_1 = require("../../agent/tokenCounter");
 const logger = (0, sdk_1.getLogger)();
 /**
  * TODO: Until token-tracking is in place.
  */
 const COMPRESSION_TRIGGER_NUM_MESSAGES = parseInt(process.env["COMPRESSION_TRIGGER_NUM_MESSAGES"] || "80", 10);
+class ChatContextTransaction {
+    constructor(baseTx, sessionUUID, baseMsgIdx, pendingUserMessages, curAgentMsgIdx) {
+        (0, assert_1.strict)(typeof curAgentMsgIdx !== "undefined");
+        this.sessionUUID = sessionUUID;
+        this.baseTx = baseTx;
+        this.baseMsgIdx = baseMsgIdx;
+        this.startingLLMContextLength = baseTx.getLLMContextLength();
+        this.pendingMessages = pendingUserMessages;
+        this.curAgentMsgIdx = curAgentMsgIdx;
+    }
+    // IContextTransaction.addMessages
+    addMessages(messages) {
+        return this.baseTx.addMessages(messages);
+    }
+    // IContextTransaction.addMessage
+    addMessage(message) {
+        return this.baseTx.addMessage(message);
+    }
+    // IContextTransaction.getMessage
+    getMessage(handle) {
+        return this.baseTx.getMessage(handle);
+    }
+    // IContextTransaction.getLLMContext
+    getLLMContext() {
+        return this.baseTx.getLLMContext();
+    }
+    // IContextTransaction.getLLMContextLength
+    getLLMContextLength() {
+        return this.baseTx.getLLMContextLength();
+    }
+    getPending() {
+        return this.pendingMessages;
+    }
+    baseMessageIdx() {
+        return this.baseMsgIdx;
+    }
+    getBaseTx() {
+        return this.baseTx;
+    }
+    /**
+     * Process a FULL Agent message (not chunks from stream).  No message is
+     * required for broadcast as the calling code is expected to broadcast this
+     * as chunks.
+     */
+    processAgentResponse(result) {
+        // Insert this (full) agent response into the list of agent messages
+        const msg = {
+            type: "agent_msg",
+            session_id: this.sessionUUID,
+            message_idx: this.getNextMessageSubIdx(),
+            message: result,
+        };
+        this.pendingMessages.push(msg);
+    }
+    processAgentMessageChunk(msg, end) {
+        const message = {
+            type: "agent_msg_chunk",
+            session_id: this.sessionUUID,
+            message_idx: this.getCurrentAgentMessageIdx(),
+            message: msg,
+            end,
+        };
+        return message;
+    }
+    processToolCallResult(result) {
+        // Allocate the sub-index for this tool call result.  It should not
+        // have been used already.
+        const message_idx = this.getNextMessageSubIdx();
+        const numPending = this.pendingMessages.length;
+        (0, assert_1.strict)(numPending > 0);
+        (0, assert_1.strict)(this.pendingMessages[numPending - 1].message_idx < message_idx);
+        const msg = {
+            type: "tool_call_result",
+            session_id: this.sessionUUID,
+            message_idx,
+            result,
+        };
+        this.pendingMessages.push(msg);
+        return msg;
+    }
+    revertAgentResponse(errMsg) {
+        logger.warn(`[ChatContextManager.revertAgentResponse] error: ${errMsg}`);
+        // Remove all messages since the user messages were placed on.
+        while (this.baseTx.getLLMContextLength() > this.startingLLMContextLength) {
+            const last = this.baseTx.popMessage();
+            (0, assert_1.strict)(last);
+        }
+    }
+    newMessages() {
+        return this.baseTx.newMessages();
+    }
+    getNextMessageSubIdx() {
+        const idx = this.curAgentMsgIdx;
+        this.curAgentMsgIdx += conversation_1.MESSAGE_INDEX_SUB_INCREMENT;
+        return idx;
+    }
+    /// Get the current index to use for streaming Agent chunks
+    getCurrentAgentMessageIdx() {
+        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
+        return this.curAgentMsgIdx;
+    }
+}
+exports.ChatContextTransaction = ChatContextTransaction;
 /**
  * A context manager for Agents interacting with the (potentially multi-user)
  * chat conversations.
@@ -25,38 +130,27 @@ const COMPRESSION_TRIGGER_NUM_MESSAGES = parseInt(process.env["COMPRESSION_TRIGG
  *   committed to the DB
  */
 class ChatContextManager {
-    constructor(systemPrompt, sessionMessages, sessionUUID, defaultUserName, checkpoint = undefined, compressionAgentUrl, compressionAgentModel, compressionAgentApiKey, checkpointWriter, fileManager) {
+    constructor(systemPrompt, sessionMessages, sessionUUID, defaultUserName, checkpoint = undefined, checkpointWriter, fileManager, llm) {
         const nextMessageIdx = (0, conversation_1.sessionMessagesToNextIndex)(sessionMessages);
         const { messages: llmMessages } = resolveConversationWithCheckpoint(sessionMessages, checkpoint);
         logger.debug(`[ChatContextManager]: llm messages: ${JSON.stringify(llmMessages)}`);
-        // Insert a system message placeholder into the context
+        const getLLM = () => Promise.resolve(llm);
         this.sessionUUID = sessionUUID;
         this.conversationMessages = (0, conversation_1.sessionMessagesToConversationMessages)(sessionMessages, defaultUserName, sessionUUID);
-        this.pendingUserMessages = [];
-        this.llmContext = new compressingContextManager_1.CompressingContextManager(systemPrompt, llmMessages, compressionAgentUrl, compressionAgentModel, compressionAgentApiKey);
+        this.llmContext = new compressingContextManager_1.CompressingContextManager(systemPrompt, llmMessages, getLLM);
         this.nextMessageIdx = nextMessageIdx;
-        this.startingLLMContextLength = undefined;
-        this.curAgentMsgIdx = undefined;
-        this.pendingMessages = undefined;
         this.pendingCompression = false;
         this.checkpointWriter = checkpointWriter;
         this.fileManager = fileManager;
         fileManager.addEventHandler(this);
         this.fileManagerDescriptionsDirty = true;
-    }
-    // IContextManager.addMessages
-    addMessages(messages) {
-        this.llmContext.addMessages(messages);
-    }
-    // IContextManager.addMessage
-    addMessage(message) {
-        this.llmContext.addMessage(message);
+        this.llm = llm;
+        this.tokenCounter = new tokenCounter_1.TokenCounter(llm.getModel());
     }
     // IContextManager.getLLMContext
     getLLMContext() {
         if (this.fileManagerDescriptionsDirty) {
-            const prompt = (0, sessionFileManager_1.createSessionFilesManagerPrompt)(this.fileManager);
-            logger.debug(`[ChatContextManager] filemanager prompt:\n${prompt}`);
+            const prompt = (0, fileManager_1.createSessionFilesManagerPrompt)(this.fileManager);
             this.llmContext.setPromptFragment("file_manager", prompt);
             this.fileManagerDescriptionsDirty = false;
         }
@@ -97,13 +191,28 @@ class ChatContextManager {
     }
     // Get the conversation (to send to clients)
     getConversationMessages() {
-        return this.conversationMessages.concat(this.pendingUserMessages);
+        return this.conversationMessages;
+    }
+    // Get current context usage (tokens)
+    getContextUsage() {
+        // Update tokenCounter if model changed
+        const currentModel = this.llm.getModel();
+        if (this.tokenCounter.getModel() !== currentModel) {
+            this.tokenCounter.free();
+            this.tokenCounter = new tokenCounter_1.TokenCounter(currentModel);
+        }
+        const messages = this.getLLMContext();
+        const used = this.tokenCounter.countMessagesTokens(messages);
+        const max = this.tokenCounter.getContextWindow();
+        return { used, max };
     }
     processUserMessage(msg, from_uuid, from_nickname) {
         // TODO: maintain a queue internally instead of relying on the caller to
         // pass in our generated messages back into `startAgentResponse`.
         // Filter out null messages immediately.
-        if (!msg.imageB64 && !msg.message) {
+        if (!msg.imageB64 &&
+            !msg.message &&
+            (!msg.attachedFiles || msg.attachedFiles.length === 0)) {
             return undefined;
         }
         const message_idx = this.getNextMessageIdx();
@@ -118,7 +227,12 @@ class ChatContextManager {
         if (msg.imageB64) {
             userMessage.imageB64 = msg.imageB64;
         }
-        this.pendingUserMessages.push(userMessage);
+        if (msg.attachedFiles) {
+            userMessage.attachedFiles = msg.attachedFiles;
+        }
+        if (msg.race_mode) {
+            userMessage.race_mode = msg.race_mode;
+        }
         return userMessage;
     }
     unprocessUserMessage(userMsg) {
@@ -128,58 +242,60 @@ class ChatContextManager {
     // TODO: Don't take the set of messages.  Instead, have OpenSession or this
     // class manage the interaction with the agent and ensure this process only
     // happens one-at-a-time.
-    startAgentResponse(msgs) {
-        // Sanity check the state
-        (0, assert_1.strict)(typeof this.startingLLMContextLength === "undefined", "already processing");
-        (0, assert_1.strict)(typeof this.pendingMessages === "undefined", "already processing");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx === "undefined", "already processing");
-        // Sanity check the messages
-        const numMessages = this.pendingUserMessages.length;
-        (0, assert_1.strict)(numMessages > 0);
-        (0, assert_1.strict)(msgs.length === this.pendingUserMessages.length);
-        (0, assert_1.strict)(msgs[0].message_idx === this.pendingUserMessages[0].message_idx);
-        (0, assert_1.strict)(msgs[numMessages - 1].message_idx ===
-            this.pendingUserMessages[numMessages - 1].message_idx);
+    async startAgentResponse(msgs) {
+        // Sanity check the state - the incoming user messages should match the
+        // pending user messages.
+        const numMessages = msgs.length;
+        (0, assert_1.strict)(numMessages > 0, "no messages");
         // Collect the pending user messages and allocate a starting index for
         // agent messages and tool calls.
-        const pendingUserMessages = this.pendingUserMessages;
-        this.pendingUserMessages = [];
-        this.startingLLMContextLength = this.llmContext.getCommittedLength();
-        this.curAgentMsgIdx = this.getNextMessageIdx();
-        this.pendingMessages = pendingUserMessages;
+        const baseMsgIdx = this.lastCommittedMessageIdx();
+        const curAgentMsgIdx = this.getNextMessageIdx();
         // Compute the new llm messages
         const llmUserMessages = [];
-        for (const msg of pendingUserMessages) {
+        for (const msg of msgs) {
             const userMsg = (0, agent_1.createUserMessage)(msg.message, msg.imageB64, msg.user_uuid);
             if (userMsg) {
                 llmUserMessages.push(userMsg);
             }
         }
-        return {
-            llmUserMessages,
-            agentFirstChunk: {
-                type: "agent_msg_chunk",
-                session_id: this.sessionUUID,
-                message_idx: this.curAgentMsgIdx,
-                message: "",
-                end: false,
-            },
+        // Return the context tx and first ServerAgentMessageChunk
+        const agentFirstChunk = {
+            type: "agent_msg_chunk",
+            session_id: this.sessionUUID,
+            message_idx: curAgentMsgIdx,
+            message: "",
+            end: false,
         };
+        // Update file manager fragment BEFORE starting the transaction
+        if (this.fileManagerDescriptionsDirty) {
+            const prompt = (0, fileManager_1.createSessionFilesManagerPrompt)(this.fileManager);
+            this.llmContext.setPromptFragment("file_manager", prompt);
+            this.fileManagerDescriptionsDirty = false;
+        }
+        const baseTx = await this.llmContext.startTx(llmUserMessages);
+        const contextTx = new ChatContextTransaction(baseTx, this.sessionUUID, baseMsgIdx, msgs, curAgentMsgIdx);
+        return { agentFirstChunk, contextTx };
     }
-    endAgentResponse() {
-        (0, assert_1.strict)(typeof this.startingLLMContextLength !== "undefined", "agent response not started (startingLLMContextLength)");
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined", "agent response not started (pendingMessages)");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined", "agent response not started (curAgentMsgIdx)");
-        const numPending = this.pendingMessages.length;
+    async endAgentResponse(tx) {
+        (0, assert_1.strict)(tx instanceof ChatContextTransaction);
+        if (tx.baseMessageIdx() !== this.lastCommittedMessageIdx()) {
+            throw new Error(`Tx stale? tx.baseMessageIdx=${String(tx.baseMessageIdx())}, ` +
+                `this.conv: ${JSON.stringify(this.conversationMessages)}`);
+        }
+        const pending = tx.getPending();
+        const numPending = pending.length;
         (0, assert_1.strict)(numPending > 0, "no pending"); // at least 1 user message
         // Compute DB messages
-        const newSessionMessages = (0, conversation_1.chatMessagesToSessionMessages)(this.pendingMessages);
-        const newLLMMessages = this.llmContext.getPending();
+        const newSessionMessages = (0, conversation_1.chatMessagesToSessionMessages)(pending);
+        const newLLMMessages = tx.newMessages();
         const messageListError = (error) => {
-            throw new Error(`${error}:` +
+            const fullError = `[endAgentResponse] Message list validation failed - ${error}:` +
                 `\n  newSessionMessages: ${JSON.stringify(newSessionMessages)}` +
-                `\n  this.pendingMessages: ${JSON.stringify(this.pendingMessages)}` +
-                `\n  newLLMMessages: ${JSON.stringify(newLLMMessages)}`);
+                `\n  pending: ${JSON.stringify(pending)}` +
+                `\n  newLLMMessages: ${JSON.stringify(newLLMMessages)}`;
+            logger.error(fullError);
+            throw new Error(fullError);
         };
         if (newSessionMessages.length !== numPending) {
             messageListError("newSessionMessages.length !== numPending");
@@ -193,7 +309,7 @@ class ChatContextManager {
         // this ensures all representations are aligned.
         for (let i = 0; i < numPending; ++i) {
             const sMsg = newSessionMessages[i];
-            const pMsg = this.pendingMessages[i];
+            const pMsg = pending[i];
             const lMsg = newLLMMessages[i];
             if (sMsg.content.role !== lMsg.role) {
                 messageListError(`newSessionMessages[${String(i)}].role !== ` +
@@ -210,91 +326,18 @@ class ChatContextManager {
         }
         // Update our internal state and return the SessionMessages to write to
         // the DB
-        this.llmContext.commit();
-        this.conversationMessages.push(...this.pendingMessages);
-        this.startingLLMContextLength = undefined;
-        this.pendingMessages = undefined;
-        this.curAgentMsgIdx = undefined;
+        await this.llmContext.commit(tx.getBaseTx());
+        this.conversationMessages.push(...pending);
         // Kick off a compression?
         this.checkCompression();
         return newSessionMessages;
     }
-    /**
-     * End the Agent message session with an error.  Caller should not call
-     * `endAgentResponse` after calling this function.
-     *
-     * This function checks that nothing has been entered into the LLM context,
-     * and drops any new user messages or responses before the error.
-     */
-    revertAgentResponse(errMsg) {
-        logger.warn(`[ChatContextManager.revertAgentResponse] error: ${errMsg}`);
-        (0, assert_1.strict)(typeof this.startingLLMContextLength !== "undefined");
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        // Sanity check that no new messages were put into the context (The Agent
-        // is expected to only call `addMessage(s)` at the end of the Agent loop.
-        // (Note, we don't check for equality here, just in case the context was
-        // compressed while the Agent was executing).
-        const contextLength = this.llmContext.getCommittedLength();
-        if (contextLength > this.startingLLMContextLength) {
-            logger.error("[ChatContextManager.revertAgentResponse] llmContext has grown " +
-                `despite Agent error (${String(contextLength)}, ` +
-                `${String(this.startingLLMContextLength)})`);
+    lastCommittedMessageIdx() {
+        const numMsgs = this.conversationMessages.length;
+        if (numMsgs > 0) {
+            return this.conversationMessages[numMsgs - 1].message_idx;
         }
-        // We simply reset the state, dropping any pending messages.
-        this.startingLLMContextLength = undefined;
-        this.pendingMessages = undefined;
-        this.curAgentMsgIdx = undefined;
-    }
-    processAgentMessage(msg, end) {
-        (0, assert_1.strict)(typeof this.startingLLMContextLength !== "undefined");
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        const message = {
-            type: "agent_msg_chunk",
-            session_id: this.sessionUUID,
-            message_idx: this.getCurrentAgentMessageIdx(),
-            message: msg,
-            end,
-        };
-        return message;
-    }
-    /**
-     * Process a FULL Agent message (not chunks from stream).  No message is
-     * required for broadcast as the calling code is expected to broadcast this
-     * as chunks.
-     */
-    processAgentResponse(result) {
-        (0, assert_1.strict)(typeof this.startingLLMContextLength !== "undefined");
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        // Insert this (full) agent response into the list of agent messages
-        const msg = {
-            type: "agent_msg",
-            session_id: this.sessionUUID,
-            message_idx: this.getNextMessageSubIdx(),
-            message: result,
-        };
-        this.pendingMessages.push(msg);
-    }
-    processToolCallResult(result) {
-        (0, assert_1.strict)(typeof this.startingLLMContextLength !== "undefined");
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        // Allocate the sub-index for this tool call result.  It should not
-        // have been used already.
-        const message_idx = this.getNextMessageSubIdx();
-        const numPending = this.pendingMessages.length;
-        (0, assert_1.strict)(numPending > 0);
-        (0, assert_1.strict)(this.pendingMessages[numPending - 1].message_idx < message_idx);
-        const msg = {
-            type: "tool_call_result",
-            session_id: this.sessionUUID,
-            message_idx,
-            result,
-        };
-        this.pendingMessages.push(msg);
-        return msg;
+        return undefined;
     }
     getNextMessageIdx() {
         const idx = this.nextMessageIdx;
@@ -309,25 +352,12 @@ class ChatContextManager {
         (0, assert_1.strict)(messageIdx === this.nextMessageIdx - conversation_1.MESSAGE_INDEX_FULL_INCREMENT, "message idx cannot be free-ed");
         this.nextMessageIdx = messageIdx;
     }
-    /// Get the current index to use for streaming Agent chunks
-    getCurrentAgentMessageIdx() {
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        return this.curAgentMsgIdx;
-    }
-    getNextMessageSubIdx() {
-        (0, assert_1.strict)(typeof this.pendingMessages !== "undefined");
-        (0, assert_1.strict)(typeof this.curAgentMsgIdx !== "undefined");
-        const idx = this.curAgentMsgIdx;
-        this.curAgentMsgIdx += conversation_1.MESSAGE_INDEX_SUB_INCREMENT;
-        return idx;
-    }
     checkCompression() {
         if (this.pendingCompression) {
             return;
         }
         // TODO: track tokens and use that to trigger compression
-        const numCommitted = this.llmContext.getCommittedLength();
+        const numCommitted = this.llmContext.numMessages();
         if (numCommitted < COMPRESSION_TRIGGER_NUM_MESSAGES) {
             return;
         }
@@ -347,7 +377,7 @@ class ChatContextManager {
             await this.checkpointWriter.writeCheckpoint(checkpoint);
         }
         catch (err) {
-            logger.warn(`[runCompression] error during compression: ${JSON.stringify(err)}`);
+            logger.warn(`[runCompression] error during compression: ${(0, errorUtils_1.getErrorString)(err)}`);
         }
         finally {
             this.pendingCompression = false;

package/dist/agent/src/chat/server/conversation.js

@@ -92,6 +92,9 @@ function userMessageToConversationMessage(userMessage, user_uuid, message_idx, s
     if (userMsgData.imageB64) {
         msg.imageB64 = userMsgData.imageB64;
     }
+    if (userMsgData.attachedFiles) {
+        msg.attachedFiles = userMsgData.attachedFiles;
+    }
     return msg;
 }
 /**

package/dist/agent/src/chat/server/imageGeneratorTools.js

@@ -4,19 +4,30 @@ exports.genImageTool = genImageTool;
 exports.genImageFileTool = genImageFileTool;
 const sdk_1 = require("@xalia/xmcp/sdk");
 const imageGenerator_1 = require("../../agent/imageGenerator");
-const tools_1 = require("./tools");
-const dbSessionFileModels_1 = require("../data/dbSessionFileModels");
+const tools_1 = require("../../agent/tools");
+const openAIRouterLLM_1 = require("./openAIRouterLLM");
+const imageGenLLM_1 = require("../../agent/imageGenLLM");
+const agentUtils_1 = require("../../agent/agentUtils");
+const constants_1 = require("../constants");
 const logger = (0, sdk_1.getLogger)();
-function createImageGenerator(llmUrl, llmApiKey) {
-    const imageGenModel = process.env["GEN_IMAGE_MODEL"];
-    logger.debug(`[genImageFileTool] model: ${imageGenModel || "(default)"}`);
-    return imageGenerator_1.ImageGenerator.init(llmUrl, llmApiKey, imageGenModel);
+async function createImageGenerator(platform) {
+    const imageGenModel = process.env["GEN_IMAGE_MODEL"] || imageGenLLM_1.DEFAULT_IMAGE_GEN_MODEL;
+    // Allow the image generator to use a "specialized" or "debug" LLM if
+    // requested.  Otherwise query the router maps for the url and api key and
+    // instantiate an ImageGenLLM.
+    let llm = await (0, agentUtils_1.createSpecializedLLM)(imageGenModel, platform);
+    if (!llm) {
+        const { apiKey, baseURL } = (0, openAIRouterLLM_1.getOpenAIClientParams)(imageGenModel);
+        logger.debug(`[genImageFileTool] model: ${imageGenModel}, url: ${baseURL}"}`);
+        llm = new imageGenLLM_1.ImageGenLLM(apiKey, baseURL, imageGenModel);
+    }
+    return imageGenerator_1.ImageGenerator.init(llm);
 }
 // gen_image
 //
 // Simple tool to generate image output as tool output.  The user can then
 // decide how/whether to use the image.
-async function genImageTool(llmUrl, llmApiKey) {
+async function genImageTool(platform) {
     const GEN_IMAGE_DESC = {
         type: "function",
         function: {
@@ -38,7 +49,7 @@ async function genImageTool(llmUrl, llmApiKey) {
             },
         },
     };
-    const imageGenerator = await createImageGenerator(llmUrl, llmApiKey);
+    const imageGenerator = await createImageGenerator(platform);
     const getPromptInputImg = (0, tools_1.makeParseArgsFn)(["prompt"], ["input_img"]);
     const toolFn = async (_, args) => {
         const { prompt, input_img } = getPromptInputImg(args);
@@ -59,12 +70,15 @@ async function genImageTool(llmUrl, llmApiKey) {
     };
 }
 // gen_image_file
-async function genImageFileTool(llmUrl, llmApiKey, fileManager) {
+async function genImageFileTool(platform, fileManager) {
     const GEN_IMAGE_FILE_DESC = {
         type: "function",
         function: {
             name: "gen_image_file",
-            description: "Generate image (into session file manager)",
+            description: "Generate or edit an image. Saves result to file manager. " +
+                `Canvas workspace is '${constants_1.CANVAS_WORKSPACE_FILENAME}'. ` +
+                "When editing canvas images, set add_to_canvas=true to " +
+                "place the result back onto the canvas.",
             parameters: {
                 type: "object",
                 properties: {
@@ -82,27 +96,36 @@ async function genImageFileTool(llmUrl, llmApiKey, fileManager) {
                     },
                     input_name: {
                         type: "string",
-                        description: "(Optional) input image filename",
+                        description: "(Optional) input image filename. " +
+                            `Use '${constants_1.CANVAS_WORKSPACE_FILENAME}' for canvas edits.`,
+                    },
+                    add_to_canvas: {
+                        type: "boolean",
+                        description: "Set true to place result on canvas (use when editing canvas)",
                     },
                 },
                 required: ["prompt", "name", "summary"],
             },
         },
     };
-    const imageGenerator = await createImageGenerator(llmUrl, llmApiKey);
-    const getPromptNameSummary = (0, tools_1.makeParseArgsFn)(["prompt", "name", "summary"], ["input_name"]);
+    const imageGenerator = await createImageGenerator(platform);
+    const getArgs = (0, tools_1.makeParseArgsFn)(["prompt", "name", "summary"], ["input_name"], ["add_to_canvas"]);
     const toolFn = async (_, args) => {
-        const { prompt, name, summary, input_name } = getPromptNameSummary(args);
+        const { prompt, name, summary, input_name, add_to_canvas } = getArgs(args);
+        const addToCanvas = add_to_canvas ?? false;
         const input_image = input_name
             ? await fileManager.getFileContent(input_name)
             : undefined;
         const image = await imageGenerator.generate(prompt, input_image);
-        const mimeType = (0, dbSessionFileModels_1.getSessionFileMimeTypeFromDataUrl)(image);
         await fileManager.putFileContent(name, summary, image);
         const uri = fileManager.getSessionFileRelativeUrl(name);
         return {
             response: uri,
-            _meta: { "xalia/fileUri": uri, "xalia/fileMimeType": mimeType },
+            _meta: {
+                "xalia/fileUri": uri,
+                "xalia/fileMimeType": (0, tools_1.getSessionFileMimeTypeFromDataUrl)(image),
+                ...(addToCanvas && { "xalia/addToCanvas": "true" }),
+            },
         };
     };
     return {