@xalia/agent 0.6.8 → 0.6.10

package/src/agent/tools/fileManager/fileManagerTool.ts

@@ -0,0 +1,199 @@
+import {
+  AgentEx,
+  IAgentToolProvider,
+  ToolCallResult,
+  ToolHandler,
+} from "../../agent";
+import { ToolDescriptor } from "../../llm";
+import { makeParseArgsFn } from "../utils";
+import {
+  ISessionFileManager,
+  FileMetaData,
+  getSessionFileMimeTypeFromDataUrl,
+} from "./types";
+
+/**
+ * Tool call result with specific form of metadata
+ */
+export type ToolCallResultWithFileRef = ToolCallResult<FileMetaData>;
+
+const GET_FILE_CONTENT_TOOL: ToolDescriptor = {
+  type: "function",
+  function: {
+    name: "get_file_content",
+    description:
+      "Get raw file content as data-url. Use this for images or when you " +
+      "need the original binary data. For PDFs and documents where you need " +
+      "the text content, use get_file_parsed_content instead.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "File name",
+        },
+      },
+      required: ["name"],
+    },
+  },
+};
+
+const PUT_FILE_CONTENT_TOOL: ToolDescriptor = {
+  type: "function",
+  function: {
+    name: "put_file_content",
+    description: "Create or update file content",
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "File name",
+        },
+        summary: {
+          type: "string",
+          description: "Content summary",
+        },
+        data_url: {
+          type: "string",
+          description:
+            "Content data-url: `data:<mime-type>[;<format>],<encoding>`",
+        },
+      },
+      required: ["name", "summary", "data_url"],
+    },
+  },
+};
+
+const DELETE_FILE_CONTENT_TOOL: ToolDescriptor = {
+  type: "function",
+  function: {
+    name: "delete_file_content",
+    description: "Delete file",
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "File name",
+        },
+      },
+      required: ["name"],
+    },
+  },
+};
+
+const GET_FILE_PARSED_CONTENT_TOOL: ToolDescriptor = {
+  type: "function",
+  function: {
+    name: "get_file_parsed_content",
+    description:
+      "Get extracted text content from a file (e.g., PDF). " +
+      "Returns the parsed text if available, or an error if the file " +
+      "has no parsed content.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "File name",
+        },
+      },
+      required: ["name"],
+    },
+  },
+};
+
+export function fileManagerTool(
+  fileManager: ISessionFileManager
+): IAgentToolProvider {
+  // `get_file_content` tool
+  //
+  // LLM can read data from the file.  To keep the context small, we overwrite
+  // the data with the session file url after the LLM has seen it.
+
+  const parseName = makeParseArgsFn(["name"] as const);
+  const getFileContentFn: ToolHandler = async (
+    _agent: AgentEx,
+    args: unknown
+  ): Promise<ToolCallResult> => {
+    const { name } = parseName(args);
+    const response = await fileManager.getFileContent(name);
+    const overwriteResponse = fileManager.getSessionFileRelativeUrl(name);
+    return { response, overwriteResponse };
+  };
+
+  // `set_file_content` tool
+  //
+  // Allows LLM to write data (as a data-url) to the session file manager. The
+  // data is replaced by a session file url after being saved.
+
+  const putArgs = ["name", "summary", "data_url"] as const;
+  const parseNameSummaryDataUrl = makeParseArgsFn(putArgs);
+  const putFileContentFn: ToolHandler = async (
+    _: AgentEx,
+    args: unknown
+  ): Promise<ToolCallResultWithFileRef> => {
+    const parsed = parseNameSummaryDataUrl(args);
+    const { name, summary, data_url } = parsed;
+    const existingFile = fileManager.listFiles().find((f) => f.name === name);
+    const desc = await fileManager.putFileContent(name, summary, data_url);
+    const mimeType = getSessionFileMimeTypeFromDataUrl(data_url);
+
+    // Calculate content size for response message
+    const contentSize = data_url.split(",")[1]?.length || 0;
+    const sizeKB = (contentSize / 1024).toFixed(1);
+
+    parsed.data_url = fileManager.getSessionFileRelativeUrl(name);
+    const action = existingFile ? "updated" : "created";
+    const responseMsg =
+      `Successfully ${action} file '${desc.name}' with ${sizeKB}KB of content`;
+    return {
+      response: responseMsg,
+      overwriteArgs: JSON.stringify(parsed),
+      _meta: {
+        "xalia/fileUri": parsed.data_url,
+        "xalia/fileMimeType": mimeType,
+      },
+    };
+  };
+
+  // `delete_file_content` tool
+  //
+  // Allows LLM to write data (as a data-url) to the session file manager. The
+  // data is replaced by a session file url after being saved.
+
+  const deleteFileFn: ToolHandler = async (_: AgentEx, args: unknown) => {
+    const { name } = parseName(args);
+    await fileManager.deleteFile(name);
+    return { response: "" };
+  };
+
+  // `get_file_parsed_content` tool
+  //
+  // Returns extracted text content from files like PDFs.
+
+  const getFileParsedContentFn: ToolHandler = async (
+    _: AgentEx,
+    args: unknown
+  ): Promise<ToolCallResult> => {
+    const { name } = parseName(args);
+    const parsedContent = await fileManager.getFileParsedContent(name);
+    if (!parsedContent) {
+      return { response: `File '${name}' has no parsed content available.` };
+    }
+    return { response: parsedContent.text };
+  };
+
+  return {
+    setup: (agent: AgentEx) => {
+      agent.addAgentTool(GET_FILE_CONTENT_TOOL, getFileContentFn);
+      agent.addAgentTool(PUT_FILE_CONTENT_TOOL, putFileContentFn);
+      agent.addAgentTool(DELETE_FILE_CONTENT_TOOL, deleteFileFn);
+      agent.addAgentTool(GET_FILE_PARSED_CONTENT_TOOL, getFileParsedContentFn);
+      return new Promise<void>((r) => {
+        r();
+      });
+    },
+  };
+}

package/src/agent/tools/fileManager/index.ts

@@ -0,0 +1,50 @@
+// Mime types - values
+export {
+  IMAGE_MIME_TYPES,
+  isImageMimeType,
+  EXTENSION_TO_IMAGE_MIME_TYPE,
+  getMimeTypeFromDataUrl,
+  createDataUrlFromBuffer,
+  createDataUrlFromText,
+} from "./mimeTypes";
+
+// Mime types - types
+export type { ImageMimeType } from "./mimeTypes";
+
+// Session file types - values
+export {
+  SESSION_FILE_MIME_TYPES,
+  isSessionFileMimeType,
+  SESSION_FILE_TEXT_MIME_TYPES,
+  isSessionFileTextMimeType,
+  EXTENSION_TO_SESSION_FILE_MIME_TYPE,
+  isFileMetaData,
+  isParsedContent,
+  getSessionFileMimeTypeFromDataUrl,
+  createSessionFileDataUrl,
+} from "./types";
+
+// Session file types - types
+export type {
+  SessionFileMimeType,
+  SessionFileTextMimeType,
+  SessionFileDescriptor,
+  SessionFileEntry,
+  FileMetaData,
+  ParsedContent,
+  ParsedContentV1,
+  ISessionFileManagerEventHandler,
+  ISessionFileManager,
+} from "./types";
+
+// Implementations
+export { MemoryFileManager } from "./memoryFileManager";
+
+// Tool - values
+export { fileManagerTool } from "./fileManagerTool";
+
+// Tool - types
+export type { ToolCallResultWithFileRef } from "./fileManagerTool";
+
+// Prompt
+export { createSessionFilesManagerPrompt } from "./prompt";

package/src/agent/tools/fileManager/memoryFileManager.ts

@@ -0,0 +1,120 @@
+import { v4 as uuidv4 } from "uuid";
+
+import {
+  ISessionFileManager,
+  ISessionFileManagerEventHandler,
+  SessionFileDescriptor,
+  SessionFileEntry,
+  ParsedContent,
+  getSessionFileMimeTypeFromDataUrl,
+} from "./types";
+
+function isSingleLine(str: string): boolean {
+  return !/[\r\n]/.test(str);
+}
+
+/**
+ * In-memory implementation of ISessionFileManager
+ */
+export class MemoryFileManager implements ISessionFileManager {
+  private readonly files: Map<string, SessionFileEntry>;
+  private eventHandlers: ISessionFileManagerEventHandler[];
+
+  constructor() {
+    this.files = new Map();
+    this.eventHandlers = [];
+  }
+
+  // ISessionFileManager.listFiles
+  listFiles(): SessionFileDescriptor[] {
+    return Array.from(this.files.values());
+  }
+
+  // ISessionFileManager.getFileContent
+  getFileContent(name: string): Promise<string> {
+    return new Promise((r, e) => {
+      const entry = this.files.get(name);
+      if (entry) {
+        r(entry.data_url);
+      } else {
+        e(new Error(`no such file ${name}`));
+      }
+    });
+  }
+
+  // ISessionFileManager.getFileParsedContent
+  getFileParsedContent(name: string): Promise<ParsedContent | undefined> {
+    return new Promise((r, e) => {
+      const entry = this.files.get(name);
+      if (entry) {
+        r(entry.parsed_content);
+      } else {
+        e(new Error(`no such file ${name}`));
+      }
+    });
+  }
+
+  // ISessionFileManager.deleteFile
+  deleteFile(name: string): Promise<void> {
+    return new Promise((r, e) => {
+      if (this.files.has(name)) {
+        this.files.delete(name);
+        this.eventHandlers.forEach((eh) => {
+          eh.onFileDeleted(name);
+        });
+        r();
+      } else {
+        e(new Error(`no such file ${name}`));
+      }
+    });
+  }
+
+  // ISessionFileManager.addFile
+  putFileContent(
+    name: string | undefined,
+    summary: string | undefined,
+    data_url: string,
+    parsed_content?: ParsedContent
+  ): Promise<SessionFileDescriptor> {
+    return new Promise((r, e) => {
+      if (!name) {
+        name = uuidv4();
+      }
+      if (!summary) {
+        summary = "";
+      }
+      if (!isSingleLine(summary)) {
+        e(new Error("summary must no contain new-lines"));
+      } else {
+        const mime_type = getSessionFileMimeTypeFromDataUrl(data_url);
+        const is_new = !this.files.has(name);
+        const entry: SessionFileEntry = {
+          name,
+          mime_type,
+          summary,
+          parsed_content,
+          data_url,
+        };
+        this.eventHandlers.forEach((eh) => {
+          eh.onFileChanged(entry, is_new);
+        });
+        this.files.set(name, entry);
+        r({ name, mime_type, summary, parsed_content });
+      }
+    });
+  }
+
+  // ISessionFileManager.setEventHandler
+  addEventHandler(eventHandler: ISessionFileManagerEventHandler) {
+    this.eventHandlers.push(eventHandler);
+  }
+
+  getSessionFileRelativeUrl(name: string): string {
+    return `file+session:/./${name}`;
+  }
+
+  getSessionFileAbsoluteUrl(name: string): string {
+    // MemoryFileManager doesn't have a session ID, use relative URL
+    return this.getSessionFileRelativeUrl(name);
+  }
+}

package/src/{chat/data → agent/tools/fileManager}/mimeTypes.ts

@@ -54,5 +54,7 @@ export function createDataUrlFromBuffer(
 }
 
 export function createDataUrlFromText(data: string, mime_type: string): string {
-  return `data:${mime_type},${data}`;
+  // Properly URL-encode the content to handle special characters
+  const encodedData = encodeURIComponent(data);
+  return `data:${mime_type};charset=utf-8,${encodedData}`;
 }

package/src/agent/tools/fileManager/prompt.ts

@@ -0,0 +1,38 @@
+import { ISessionFileManager } from "./types";
+
+/**
+ * Return the file list in a form easily parsable by the LLM.
+ */
+export function createSessionFilesManagerPrompt(
+  fm: ISessionFileManager
+): string {
+  const files = fm.listFiles();
+
+  let prompt =
+    "Files can be read/written as required. Create new files " +
+    "conservatively, usually when complex content is requested. " +
+    "\n\nDATA URL FORMAT: For text files (plain, markdown, html), use " +
+    "URL-encoded format: 'data:<mime-type>;charset=utf-8," +
+    "<URL-encoded-content>'. For binary files (images, PDF), use " +
+    "base64: 'data:<mime-type>;base64,<base64-data>'. URL encoding " +
+    "means using encodeURIComponent() or percent-encoding where " +
+    "special characters become %XX codes." +
+    "\n\n⚠️ CRITICAL: After you call put_file_content, the system " +
+    "AUTOMATICALLY replaces your data_url argument with " +
+    "'file+session://...' in the conversation history. This is NORMAL " +
+    "behavior to save context space. The replacement happens AFTER the " +
+    "file is successfully written. When you see 'file+session://...' in " +
+    "your previous tool call, this means SUCCESS - the file was created " +
+    "with your full content. NEVER retry or attempt to 'fix' this. The " +
+    "file+session:// reference is NOT an error - it confirms the " +
+    "operation succeeded.";
+
+  if (files.length > 0) {
+    prompt += "\n\nAvailable files:\nname,type,summary\n";
+    for (const f of files) {
+      prompt += `${f.name},${f.mime_type},${f.summary || ""}\n`;
+    }
+  }
+
+  return prompt;
+}

package/src/{chat/data/dbSessionFileModels.ts → agent/tools/fileManager/types.ts}

@@ -54,10 +54,28 @@ export const EXTENSION_TO_SESSION_FILE_MIME_TYPE: Record<
   md: "text/markdown",
 };
 
+/**
+ * Parsed content from files like PDFs.
+ * Stored as JSON to allow future expansion (pages, tables, metadata).
+ */
+export type ParsedContentV1 = {
+  version: 1;
+  text: string;
+};
+
+export type ParsedContent = ParsedContentV1;
+
+export function isParsedContent(obj: unknown): obj is ParsedContent {
+  if (typeof obj !== "object" || obj === null) return false;
+  const pc = obj as Record<string, unknown>;
+  return pc.version === 1 && typeof pc.text === "string";
+}
+
 export type SessionFileDescriptor = {
   name: string;
   mime_type: SessionFileMimeType;
   summary?: string;
+  parsed_content?: ParsedContent;
 };
 
 export type SessionFileEntry = SessionFileDescriptor & { data_url: string };
@@ -111,3 +129,61 @@ export function createSessionFileDataUrl(
     return createDataUrlFromBuffer(data, mime_type);
   }
 }
+
+/**
+ * Calling code implements this to be informed of file changes.
+ */
+export interface ISessionFileManagerEventHandler {
+  onFileChanged(entry: SessionFileEntry, new_file: boolean): void;
+  onFileDeleted(name: string): void;
+}
+
+/**
+ * Interface to a set of files in a session.
+ */
+export interface ISessionFileManager {
+  /**
+   * List file names, types and summaries,
+   */
+  listFiles(): SessionFileDescriptor[];
+
+  /**
+   * Retrieve file contents as data URL.
+   */
+  getFileContent(name: string): Promise<string>;
+
+  /**
+   * Retrieve parsed content for a file (e.g., extracted text from PDF).
+   * Returns undefined if the file has no parsed content.
+   */
+  getFileParsedContent(name: string): Promise<ParsedContent | undefined>;
+
+  /**
+   * Delete a file
+   */
+  deleteFile(name: string): Promise<void>;
+
+  /**
+   * Create or update a file with the given name.  Returns the name (which is
+   * created if one is not passed in).
+   */
+  putFileContent(
+    name: string | undefined,
+    summary: string | undefined,
+    data_url: string,
+    parsed_content?: ParsedContent
+  ): Promise<SessionFileDescriptor>;
+
+  addEventHandler(eventHandler: ISessionFileManagerEventHandler): void;
+
+  /**
+   * Get a relative URL for a session file (e.g., "file+session:/./{name}")
+   */
+  getSessionFileRelativeUrl(name: string): string;
+
+  /**
+   * Get an absolute URL for a session file
+   * (e.g., "file+session://{sessionId}/{name}")
+   */
+  getSessionFileAbsoluteUrl(name: string): string;
+}

package/src/agent/tools/index.ts

@@ -0,0 +1,49 @@
+/**
+ * General-purpose agent tools.
+ *
+ * These tools are available to all agents, not just chat-based ones.
+ */
+
+import { AgentEx, Agent } from "../agent";
+import { IPlatform } from "../iplatform";
+import { ISessionFileManager } from "./fileManager";
+
+// Tool implementations
+export { datetimeTool, isoWithTimezone } from "./datetimeTool";
+export { calculatorTool, calculatorEval } from "./calculatorTool";
+export { webSearchTool } from "./webSearchTool";
+export { openURLTool, openURL } from "./openUrlTool";
+export { renderTool } from "./renderTool";
+
+// Utilities
+export { makeParseArgsFn } from "./utils";
+export { webSearch } from "./webSearch";
+export { htmlToText } from "./contentExtractors/htmlToText";
+
+// File manager (re-export everything)
+export * from "./fileManager";
+
+// Import tools for addDefaultTools
+import { datetimeTool } from "./datetimeTool";
+import { calculatorTool } from "./calculatorTool";
+import { webSearchTool } from "./webSearchTool";
+import { openURLTool } from "./openUrlTool";
+import { renderTool } from "./renderTool";
+import { fileManagerTool } from "./fileManager";
+
+/**
+ * Add the default set of general-purpose agent tools.
+ */
+export async function addDefaultTools(
+  agent: AgentEx | Agent,
+  timezone: string,
+  _platform: IPlatform,
+  fileManager: ISessionFileManager
+): Promise<void> {
+  await agent.addAgentToolProvider(datetimeTool(timezone));
+  await agent.addAgentToolProvider(calculatorTool);
+  await agent.addAgentToolProvider(renderTool(fileManager));
+  await agent.addAgentToolProvider(webSearchTool());
+  await agent.addAgentToolProvider(openURLTool());
+  await agent.addAgentToolProvider(fileManagerTool(fileManager));
+}

package/src/agent/tools/openUrlTool.ts

@@ -0,0 +1,62 @@
+import { AgentEx, IAgentToolProvider, ToolCallResult } from "../agent";
+import { ToolDescriptor } from "../llm";
+import { OPEN_URL_MAX_LENGTH } from "../toolSettings";
+import { makeParseArgsFn } from "./utils";
+import { htmlToText } from "./contentExtractors/htmlToText";
+import { pdfToText } from "./contentExtractors/pdfToText";
+
+const OPEN_URL_DESC: ToolDescriptor = {
+  type: "function",
+  function: {
+    name: "open_url",
+    description:
+      "Download and extract text content from a URL (supports HTML and PDF)",
+    parameters: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "URL to download (HTML pages or PDF files)",
+        },
+      },
+      required: ["url"],
+    },
+  },
+};
+
+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 contentType = response.headers.get("content-type") || "";
+  const isPdf =
+    contentType.includes("application/pdf") ||
+    url.toLowerCase().endsWith(".pdf");
+
+  if (isPdf) {
+    const buffer = await response.arrayBuffer();
+    return pdfToText(buffer, OPEN_URL_MAX_LENGTH);
+  } else {
+    const html = await response.text();
+    return htmlToText(html, OPEN_URL_MAX_LENGTH);
+  }
+}
+
+export function openURLTool(): IAgentToolProvider {
+  const getURL = makeParseArgsFn(["url"] as const);
+  const toolFn = async (_: AgentEx, args: unknown): Promise<ToolCallResult> => {
+    const { url } = getURL(args);
+    return { response: await openURL(url) };
+  };
+
+  return {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    setup: async (agent: AgentEx) => {
+      agent.addAgentTool(OPEN_URL_DESC, toolFn);
+    },
+  };
+}