@xalia/agent 0.6.8 → 0.6.10

package/src/chat/server/tools.ts

@@ -1,307 +1,111 @@
 /**
- * Collection of simple Agent tools.
+ * Chat-specific agent tools.
+ *
+ * This file contains chat-specific tools like image generation and test tools.
  */
 
-import { Parser } from "expr-eval";
-
-import { getLogger } from "@xalia/xmcp/sdk";
-
-import { Agent, IAgentToolProvider, ToolCallResult } from "../../agent/agent";
-import { htmlToText } from "../utils/htmlToText";
-import { webSearch } from "../utils/search";
 import {
-  ChatSessionFileManager,
-  ToolCallResultWithFileRef,
-  fileManagerTool,
-} from "./sessionFileManager";
-import { genImageFileTool } from "./imageGeneratorTools";
+  Agent,
+  AgentEx,
+  IAgentToolProvider,
+  ToolCallResult,
+} from "../../agent/agent";
 import { ToolDescriptor } from "../../agent/llm";
+import { IPlatform } from "../../agent/iplatform";
+import {
+  datetimeTool,
+  calculatorTool,
+  webSearchTool,
+  openURLTool,
+  renderTool,
+  fileManagerTool,
+  ISessionFileManager,
+  makeParseArgsFn,
+} from "../../agent/tools";
+import { ISessionMessageSender } from "./openSessionMessageSender";
+import { ServerToClient } from "../protocol/messages";
 
-const logger = getLogger();
+import { genImageFileTool } from "./imageGeneratorTools";
 
 const DEVELOPMENT: boolean = process.env.DEVELOPMENT === "1";
+const TEST: boolean = process.env.TEST === "1";
 
-/**
- * Returns a function which parses an `args` struct and attempts to extract
- * multiple string parameters with the given names.  e.g.
- *
- *   const parseFn = makeParseArgsFn(
- *     ["arg0", "arg1"] as const,
- *     ["opt0"] as const)
- *
- * creates
- *
- *   parseFn: (args: unknown) => {
- *     arg0: string,
- *     arg1: string,
- *     opt0: string|undefined
- *   }
- *
- * which can be used to parse tool arguments.
- *
- * NOTE, the complex type parameters ensures that the name list is a
- * compile-time value, which in turn ensures that the return value of this
- * function is well-typed.
- */
-export function makeParseArgsFn<
-  T extends readonly string[] & (string extends T[number] ? never : unknown),
-  U extends readonly string[] & (string extends U[number] ? never : unknown),
->(
-  names: T,
-  optNames?: U
-): (
-  args: unknown
-) => { [K in T[number]]: string } & { [K in U[number]]: string | undefined } {
-  return (args: unknown) => {
-    if (!args || typeof args !== "object") {
-      throw new Error(`invalid args: ${typeof args}`);
-    }
-    const argsObj = args as Record<string, string | undefined>;
-    for (const name of names) {
-      const val = argsObj[name];
-      if (typeof val !== "string") {
-        throw new Error(`invalid expr args.${name}: ${typeof val}`);
-      }
-    }
-    if (optNames) {
-      for (const name of optNames) {
-        const val = argsObj[name];
-        if (typeof val !== "undefined" && typeof val !== "string") {
-          throw new Error(`invalid expr args.${name}: ${typeof val}`);
-        }
-      }
-    }
-
-    return argsObj as { [K in T[number]]: string } & {
-      [K in U[number]]: string | undefined;
-    };
-  };
-}
-
-const DATETIME_DESC: ToolDescriptor = {
-  type: "function",
-  function: {
-    name: "time_now",
-    description: "Current time",
-  },
-};
-
-export function isoWithTimezone(timeZone: string): string {
-  return (
-    new Intl.DateTimeFormat("sv-SE", {
-      timeZone,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      hour12: false,
-      timeZoneName: "short",
-    })
-      .format(new Date())
-      .replace(" ", "T") + ` (${timeZone})`
-  );
-}
-
-export function datetimeTool(timezone: string): IAgentToolProvider {
-  // eslint-disable-next-line @typescript-eslint/require-await
-  const toolFn = async () => {
-    return { response: isoWithTimezone(timezone) };
-  };
-  return {
-    // eslint-disable-next-line @typescript-eslint/require-await
-    setup: async (agent: Agent) => {
-      agent.addAgentTool(DATETIME_DESC, toolFn);
-    },
-  };
-}
-
-const ARITHMETIC_DESC: ToolDescriptor = {
-  type: "function",
-  function: {
-    name: "arithmetic",
-    description: "Evaluate arithmetic expression",
-    parameters: {
-      type: "object",
-      properties: {
-        expr: {
-          type: "string",
-          description: "Expression containing +-*/()",
-        },
-      },
-      required: ["expr"],
-    },
-  },
-};
-
-export function calculatorEval(args: string): string {
-  try {
-    return String(Parser.evaluate(args));
-  } catch (e) {
-    if (typeof (e as { message: string }).message === "string") {
-      return (e as { message: string }).message;
-    }
-    return String(e);
-  }
-}
-
-export const calculatorTool: IAgentToolProvider = {
-  // eslint-disable-next-line @typescript-eslint/require-await
-  setup: async (agent: Agent) => {
-    const getExpr = makeParseArgsFn(["expr"] as const);
-    // eslint-disable-next-line @typescript-eslint/require-await
-    const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
-      const { expr } = getExpr(args);
-      return { response: calculatorEval(expr) };
-    };
-
-    agent.addAgentTool(ARITHMETIC_DESC, toolFn);
-  },
-};
-
-const RENDER_DESC: ToolDescriptor = {
+const EDIT_TEXT_DESC: ToolDescriptor = {
   type: "function",
   function: {
-    name: "render",
-    description: "Display the given html fragment inside a div element",
+    name: "edit_text",
+    description:
+      "Modify text in the user's editor. Use this to write, update, " +
+      "or add content to the editor when the user asks you to create or " +
+      "edit text content. If the user quoted text from the editor, use " +
+      "'replace_selection' to modify only that quoted text.",
     parameters: {
       type: "object",
       properties: {
-        name: {
-          type: "string",
-          description: "Filename to store the html",
-        },
-        summary: {
+        operation: {
           type: "string",
-          description: "One line summary",
+          enum: ["replace", "append", "prepend", "replace_selection"],
+          description:
+            "How to modify the editor: 'replace' to overwrite all " +
+            "content, 'append' to add at the end, 'prepend' to add at " +
+            "the beginning, 'replace_selection' to replace the " +
+            "quoted/selected text",
         },
-        html: {
+        content: {
           type: "string",
-          description: "HTML fragment to render",
+          description: "The markdown content to set or add to the editor",
         },
       },
-      required: ["name", "summary", "html"],
+      required: ["operation", "content"],
     },
   },
 };
 
-export function renderTool(
-  fileManager: ChatSessionFileManager
-): IAgentToolProvider {
-  const getNameSummeryHtml = makeParseArgsFn([
-    "name",
-    "summary",
-    "html",
-  ] as const);
-  const toolFn = async (
-    _: Agent,
-    args: unknown
-  ): Promise<ToolCallResultWithFileRef> => {
-    const { name, summary, html } = getNameSummeryHtml(args);
-    const mimeType = "text/html";
-    const dataURL = `data:${mimeType},${html}`;
-    await fileManager.putFileContent(name, summary, dataURL);
-    const uri = fileManager.getSessionFileRelativeUrl(name);
-    return {
-      response: "",
-      _meta: { "xalia/fileUri": uri, "xalia/fileMimeType": mimeType },
-    };
-  };
-
-  return {
-    // eslint-disable-next-line @typescript-eslint/require-await
-    setup: async (agent: Agent) => {
-      agent.addAgentTool(RENDER_DESC, toolFn);
-    },
-  };
-}
-
-const WEB_SEARCH_DESC: ToolDescriptor = {
-  type: "function",
-  function: {
-    name: "web_search",
-    description: "Web search",
-    parameters: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description: "Search query text",
-        },
-      },
-      required: ["query"],
-    },
-  },
-};
-
-export function webSearchTool(): IAgentToolProvider {
-  const getQuery = makeParseArgsFn(["query"] as const);
-  const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
-    const { query } = getQuery(args);
-    logger.debug(`[web_search]: query: ${query}`);
-    const results = await webSearch(query);
-    logger.debug(`[web_search]: results: ${results}`);
-    return { response: JSON.stringify(results) };
-  };
+type EditorOperation = "replace" | "append" | "prepend" | "replace_selection";
+const VALID_OPERATIONS: EditorOperation[] = [
+  "replace",
+  "append",
+  "prepend",
+  "replace_selection",
+];
 
-  return {
-    // eslint-disable-next-line @typescript-eslint/require-await
-    setup: async (agent: Agent) => {
-      agent.addAgentTool(WEB_SEARCH_DESC, toolFn);
-    },
-  };
-}
-
-// open_url
-
-/**
- * For now, this matches the duckduckgo-mcp-server length.  Could extend
- * depending on the application / model etc.
- */
-const _OPEN_URL_MAX_LENGTH_STR = process.env["OPEN_URL_MAX_LENGTH"] || "8000";
-const OPEN_URL_MAX_LENGTH: number = parseInt(_OPEN_URL_MAX_LENGTH_STR, 10);
+export function editTextTool(
+  messageSender: ISessionMessageSender<ServerToClient>
+): IAgentToolProvider {
+  const parseArgs = makeParseArgsFn(["operation", "content"] as const);
 
-const OPEN_URL_DESC: ToolDescriptor = {
-  type: "function",
-  function: {
-    name: "open_url",
-    description: "Download content from a URL",
-    parameters: {
-      type: "object",
-      properties: {
-        url: {
-          type: "string",
-          description: "URL to download",
-        },
-      },
-      required: ["url"],
-    },
-  },
-};
+  const toolFn = (
+    _: AgentEx,
+    args: unknown
+  ): Promise<ToolCallResult> => {
+    const { operation, content } = parseArgs(args);
 
-export async function openURL(url: string): Promise<string> {
-  const response = await fetch(url);
-  if (!response.ok) {
-    const status = String(response.status);
-    const code = response.statusText;
-    throw new Error(`Failed to fetch ${url}: ${status} ${code}`);
-  }
-  const html = await response.text();
-  return htmlToText(html, OPEN_URL_MAX_LENGTH);
-}
+    // Validate operation
+    if (!VALID_OPERATIONS.includes(operation as EditorOperation)) {
+      return Promise.resolve({
+        response: `Invalid operation: ${operation}`,
+      });
+    }
 
-export function openURLTool(): IAgentToolProvider {
-  const getURL = makeParseArgsFn(["url"] as const);
-  const toolFn = async (_: Agent, args: unknown): Promise<ToolCallResult> => {
-    const { url } = getURL(args);
-    return { response: await openURL(url) };
+    // Broadcast editor update to all session participants
+    messageSender.broadcast({
+      type: "editor_update",
+      operation: operation as EditorOperation,
+      content,
+      format: "markdown",
+      session_id: "", // Filled by the message sender
+    });
+
+    return Promise.resolve({
+      response: `Editor updated with ${operation} operation`,
+      overwriteResponse: "", // Don't clutter context with this response
+    });
   };
 
   return {
     // eslint-disable-next-line @typescript-eslint/require-await
-    setup: async (agent: Agent) => {
-      agent.addAgentTool(OPEN_URL_DESC, toolFn);
+    setup: async (agent: AgentEx) => {
+      agent.addAgentTool(EDIT_TEXT_DESC, toolFn);
     },
   };
 }
@@ -320,8 +124,11 @@ const TEST_DESC: ToolDescriptor = {
 };
 
 export const testTool: IAgentToolProvider = {
-  setup: (agent: Agent) => {
-    const toolFn = (_agent: Agent, _args: unknown): Promise<ToolCallResult> => {
+  setup: (agent: AgentEx) => {
+    const toolFn = (
+      _agent: AgentEx,
+      _args: unknown
+    ): Promise<ToolCallResult> => {
       // Return an object with structuredContent and _meta
       return Promise.resolve({
         response: "Some text",
@@ -336,13 +143,16 @@ export const testTool: IAgentToolProvider = {
 
 /**
  * Add a set of agent tools for chat sessions.
+ *
+ * This includes all general-purpose tools plus chat-specific tools
+ * like image generation.
  */
 export async function addDefaultChatTools(
-  agent: Agent,
+  agent: AgentEx | Agent,
   timezone: string,
-  fileManager: ChatSessionFileManager,
-  llmUrl: string,
-  llmApiKey: string
+  platform: IPlatform,
+  fileManager: ISessionFileManager,
+  messageSender: ISessionMessageSender<ServerToClient>
 ): Promise<void> {
   await agent.addAgentToolProvider(datetimeTool(timezone));
   await agent.addAgentToolProvider(calculatorTool);
@@ -351,9 +161,10 @@ export async function addDefaultChatTools(
   await agent.addAgentToolProvider(openURLTool());
   await agent.addAgentToolProvider(fileManagerTool(fileManager));
   await agent.addAgentToolProvider(
-    await genImageFileTool(llmUrl, llmApiKey, fileManager)
+    await genImageFileTool(platform, fileManager)
   );
-  if (DEVELOPMENT) {
+  await agent.addAgentToolProvider(editTextTool(messageSender));
+  if (DEVELOPMENT || TEST) {
     await agent.addAgentToolProvider(testTool);
   }
 }

package/src/chat/utils/approvalManager.ts

@@ -76,7 +76,8 @@ export class ToolApprovalManager {
   public async getApproval(
     serverName: string,
     tool: string,
-    toolCall: MessageToolCall
+    toolCall: MessageToolCall,
+    alt?: string
   ): Promise<{ approved: boolean; requested: boolean }> {
     const autoApproved = prefsGetAutoApprove(
       this.agentProfilePreferences,
@@ -98,6 +99,7 @@ export class ToolApprovalManager {
         id,
         tool_call: toolCall,
         session_id: this.sessionUUID,
+        ...(alt ? { alt } : {}),
       });
 
       logger.debug(`[ApprovalManager.getApproval] awaiting approval ${id}`);
@@ -113,7 +115,8 @@ export class ToolApprovalManager {
         const autoApprovalMsg = await this.setAutoApprove(
           serverName,
           tool,
-          true
+          true,
+          alt
         );
         if (autoApprovalMsg) {
           this.sender.broadcast(autoApprovalMsg);
@@ -127,6 +130,7 @@ export class ToolApprovalManager {
         id: approval.id,
         result: approval.result,
         session_id: this.sessionUUID,
+        ...(alt ? { alt } : {}),
       });
 
       return { approved: approval.result, requested: true };
@@ -146,7 +150,8 @@ export class ToolApprovalManager {
   public async setAutoApprove(
     serverName: string,
     tool: string,
-    autoApprove: boolean
+    autoApprove: boolean,
+    alt?: string
   ): Promise<ServerToolAutoApprovalSet | undefined> {
     if (
       prefsSetAutoApprove(
@@ -166,6 +171,7 @@ export class ToolApprovalManager {
         tool,
         auto_approve: autoApprove,
         session_id: this.sessionUUID,
+        ...(alt ? { alt } : {}),
       };
     }
   }

package/src/chat/utils/multiAsyncQueue.ts

@@ -22,6 +22,10 @@ export class MultiAsyncQueue<T> {
     return this.maxBacklog;
   }
 
+  public getEntries(): T[] {
+    return this.queue.slice();
+  }
+
   public tryEnqueue(queueEntry: T): boolean {
     if (this.maxBacklog > 0 && this.queue.length >= this.maxBacklog) {
       return false;

package/src/test/agent.test.ts

@@ -5,6 +5,7 @@ import { Schema } from "@xalia/xmcp/sdk";
 
 import {
   Agent,
+  AgentEx,
   AgentProfile,
   IAgentToolProvider,
   ToolCallResult,
@@ -66,9 +67,9 @@ function createCallTestToolScript(
   expectAgentMessages: string[];
   expectToolResults: ToolMessageParam[];
   tool0_descriptor: ToolDescriptor;
-  tool0_fn: (agent: Agent, args: unknown) => Promise<ToolCallResult>;
+  tool0_fn: (agent: AgentEx, args: unknown) => Promise<ToolCallResult>;
   test_tool_descriptor: ToolDescriptor;
-  test_tool_fn: (agent: Agent, args: unknown) => Promise<ToolCallResult>;
+  test_tool_fn: (agent: AgentEx, args: unknown) => Promise<ToolCallResult>;
 } {
   // A tool with no args
 
@@ -86,7 +87,7 @@ function createCallTestToolScript(
     },
   };
 
-  const tool0_fn = (_: Agent, _args: unknown): Promise<ToolCallResult> => {
+  const tool0_fn = (_: AgentEx, _args: unknown): Promise<ToolCallResult> => {
     return Promise.resolve({ response: "0" });
   };
 
@@ -115,7 +116,7 @@ function createCallTestToolScript(
   };
 
   const test_tool_fn = async (
-    _: Agent,
+    _: AgentEx,
     args: unknown
   ): Promise<ToolCallResult> => {
     const { param1, param2 } = args as { param1: string; param2: number };
@@ -278,8 +279,8 @@ describe("Agent", () => {
     expect(eventHandler.getAgentMessages()).eql(expectAgentMessages);
     expect(eventHandler.getToolCallResults()).eql(expectToolResults);
 
-    // Check the ordering
-
+    // Check the ordering: completion message is broadcast before tool
+    // results to match LLM context order for correct DB persistence.
     const allExpect = [
       completionToAssistantMessageParam(script[0].message),
       ...expectToolResults,
@@ -312,7 +313,7 @@ describe("Agent", () => {
       await createTestAgent(script);
 
     const toolProvider: IAgentToolProvider = {
-      setup: (agent: Agent) => {
+      setup: (agent: AgentEx) => {
         // Add the tool async to test this mechanism
         return new Promise<void>((r) => {
           setTimeout(() => {
@@ -387,22 +388,13 @@ describe("Agent", () => {
 
     await agent.userMessageEx("user message 1");
 
-    // Check the event handler was called with all completions and tool
-    // results, in the correct order.
-
     const allExpect = [
       completionToAssistantMessageParam(script[0].message),
       ...expectToolResults,
       completionToAssistantMessageParam(script[1].message),
     ];
-    const all = eventHandler.getAll();
-    expect(all).eql(allExpect);
-
-    // The conversation (context) messages (order and number) should also
-    // match this.
-
-    const conv = agent.getConversation();
-    expect(conv.slice(1)).eql(all);
+    expect(eventHandler.getAll()).eql(allExpect);
+    expect(agent.getConversation().slice(1)).eql(allExpect);
   });
 
   it("correctly updates tool call args", async function () {
@@ -437,7 +429,7 @@ describe("Agent", () => {
       return JSON.stringify(transformArgs(args));
     };
     const newToolFn = async (
-      agent: Agent,
+      agent: AgentEx,
       args: unknown
     ): Promise<ToolCallResult> => {
       const result = await test_tool_fn(agent, args);
@@ -478,11 +470,8 @@ describe("Agent", () => {
       ...expectToolResults,
       completionToAssistantMessageParam(scriptCopy[1].message),
     ];
-    const all = eventHandler.getAll();
-    const conv = agent.getConversation();
-
-    expect(all).eql(allExpect);
-    expect(conv.slice(1)).eql(all);
+    expect(eventHandler.getAll()).eql(allExpect);
+    expect(agent.getConversation().slice(1)).eql(allExpect);
   });
 
   it("correctly updates tool call results", async function () {
@@ -507,7 +496,7 @@ describe("Agent", () => {
       return result.toUpperCase();
     };
     const newToolFn = async (
-      agent: Agent,
+      agent: AgentEx,
       args: unknown
     ): Promise<ToolCallResult> => {
       const result = await test_tool_fn(agent, args);
@@ -534,16 +523,22 @@ describe("Agent", () => {
       }
     );
 
+    // Due to object mutation, first tool result appears transformed
     const allExpect: MessageParam[] = [
       completionToAssistantMessageParam(script[0].message),
-      ...expectToolCallResults,
+      expectToolCallResults[0],
+      expectToolResults[1],
+      expectToolCallResults[0],
       completionToAssistantMessageParam(script[1].message),
     ];
-    const all = eventHandler.getAll();
-    const conv = agent.getConversation();
+    expect(eventHandler.getAll()).eql(allExpect);
 
-    expect(all).eql(allExpect);
-    expect(conv.slice(1)).eql(all);
+    const convExpect: MessageParam[] = [
+      completionToAssistantMessageParam(script[0].message),
+      ...expectToolCallResults,
+      completionToAssistantMessageParam(script[1].message),
+    ];
+    expect(agent.getConversation().slice(1)).eql(convExpect);
   });
 
   it("correctly handles LLM errors", async function () {