fourmis-agents-sdk 0.2.6 → 0.3.0

package/dist/index.js

@@ -501,7 +501,8 @@ async function* agentLoop(prompt, options) {
     hooks,
     mcpClient,
     previousMessages,
-    sessionLogger
+    sessionLogger,
+    nativeMemoryTool
   } = options;
   const startTime = Date.now();
   let apiTimeMs = 0;
@@ -555,13 +556,15 @@ async function* agentLoop(prompt, options) {
     let assistantTextParts = [];
     let toolCalls = [];
     let turnUsage = emptyTokenUsage();
+    const nativeTools = nativeMemoryTool ? [nativeMemoryTool.definition] : undefined;
     try {
       const chunks = provider.chat({
         model,
         messages,
         tools: toolDefs.length > 0 ? toolDefs : undefined,
         systemPrompt,
-        signal
+        signal,
+        nativeTools
       });
       for await (const chunk of chunks) {
         switch (chunk.type) {
@@ -719,13 +722,24 @@ async function* agentLoop(prompt, options) {
         input: toolInput,
         uuid: uuid()
       };
-      const toolCtx = {
-        cwd,
-        signal,
-        sessionId,
-        env
-      };
-      const result = await tools.execute(call.name, toolInput, toolCtx);
+      let result;
+      if (call.name === "memory" && nativeMemoryTool) {
+        try {
+          const content = await nativeMemoryTool.execute(toolInput);
+          result = { content, isError: content.startsWith("Error:") };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          result = { content: `Error: ${message}`, isError: true };
+        }
+      } else {
+        const toolCtx = {
+          cwd,
+          signal,
+          sessionId,
+          env
+        };
+        result = await tools.execute(call.name, toolInput, toolCtx);
+      }
       if (debug) {
         console.error(`[debug] Tool ${call.name}: ${result.isError ? "ERROR" : "OK"} (${result.content.length} chars)`);
       }
@@ -1040,15 +1054,29 @@ class AnthropicAdapter {
     } else if (request.systemPrompt) {
       params.system = request.systemPrompt;
     }
+    const allTools = [];
     if (tools && tools.length > 0) {
-      params.tools = tools;
+      allTools.push(...tools);
+    }
+    if (request.nativeTools && request.nativeTools.length > 0) {
+      allTools.push(...request.nativeTools);
+    }
+    if (allTools.length > 0) {
+      params.tools = allTools;
     }
     if (request.temperature !== undefined) {
       params.temperature = request.temperature;
     }
-    const stream = this.client.messages.stream(params, {
+    const hasMemoryTool = request.nativeTools?.some((t) => t.type === "memory_20250818");
+    const requestOptions = {
       signal: request.signal
-    });
+    };
+    if (hasMemoryTool) {
+      requestOptions.headers = {
+        "anthropic-beta": "context-management-2025-06-27"
+      };
+    }
+    const stream = this.client.messages.stream(params, requestOptions);
     const toolInputBuffers = new Map;
     for await (const event of stream) {
       switch (event.type) {
@@ -3586,6 +3614,307 @@ function loadSessionMessages(cwd, sessionId) {
   return messages;
 }
 
+// src/memory/memory-handler.ts
+import { readdir, stat, readFile, writeFile, rm, rename, mkdir as mkdir2 } from "fs/promises";
+import { join as join6, resolve, relative } from "path";
+import { existsSync as existsSync4 } from "fs";
+function createMemoryHandler(memoryDir) {
+  const absMemoryDir = resolve(memoryDir);
+  function resolvePath2(logicalPath) {
+    let cleaned = logicalPath;
+    if (cleaned.startsWith("/memories")) {
+      cleaned = cleaned.slice("/memories".length);
+    }
+    if (cleaned.startsWith("/")) {
+      cleaned = cleaned.slice(1);
+    }
+    if (cleaned.includes("..") || cleaned.includes("%2e") || cleaned.includes("%2E")) {
+      throw new Error(`Path traversal detected: ${logicalPath}`);
+    }
+    const absPath = cleaned === "" ? absMemoryDir : resolve(absMemoryDir, cleaned);
+    const rel = relative(absMemoryDir, absPath);
+    if (rel.startsWith("..") || resolve(absPath) !== absPath && !absPath.startsWith(absMemoryDir)) {
+      throw new Error(`Path traversal detected: ${logicalPath}`);
+    }
+    return absPath;
+  }
+  function toLogicalPath(absPath) {
+    const rel = relative(absMemoryDir, absPath);
+    return rel === "" ? "/memories" : `/memories/${rel}`;
+  }
+  function formatSize(bytes) {
+    if (bytes < 1024)
+      return `${bytes}`;
+    if (bytes < 1024 * 1024)
+      return `${(bytes / 1024).toFixed(1)}K`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+  }
+  async function listDir(dirPath, depth = 0) {
+    const lines = [];
+    const dirStat = await stat(dirPath);
+    if (depth === 0) {
+      lines.push(`${formatSize(dirStat.size)}	${toLogicalPath(dirPath)}`);
+    }
+    if (depth >= 2)
+      return lines;
+    try {
+      const entries = await readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+          continue;
+        const entryPath = join6(dirPath, entry.name);
+        const entryStat = await stat(entryPath);
+        lines.push(`${formatSize(entryStat.size)}	${toLogicalPath(entryPath)}`);
+        if (entry.isDirectory()) {
+          const subLines = await listDir(entryPath, depth + 1);
+          lines.push(...subLines.slice(depth === 0 ? 0 : 0));
+        }
+      }
+    } catch {}
+    return lines;
+  }
+  function formatFileContent(content, viewRange) {
+    const lines = content.split(`
+`);
+    if (lines.length > 999999) {
+      throw new Error(`File exceeds maximum line limit of 999,999 lines.`);
+    }
+    let start = 0;
+    let end = lines.length;
+    if (viewRange && viewRange.length >= 2) {
+      start = Math.max(0, viewRange[0] - 1);
+      end = Math.min(lines.length, viewRange[1]);
+    }
+    const formatted = [];
+    for (let i = start;i < end; i++) {
+      const lineNum = String(i + 1).padStart(6, " ");
+      formatted.push(`${lineNum}	${lines[i]}`);
+    }
+    return formatted.join(`
+`);
+  }
+  async function handleView(cmd) {
+    const absPath = resolvePath2(cmd.path);
+    if (!existsSync4(absPath)) {
+      return `The path ${cmd.path} does not exist. Please provide a valid path.`;
+    }
+    const s = await stat(absPath);
+    if (s.isDirectory()) {
+      const lines = await listDir(absPath);
+      return `Here're the files and directories up to 2 levels deep in ${cmd.path}, excluding hidden items and node_modules:
+${lines.join(`
+`)}`;
+    }
+    const content = await readFile(absPath, "utf-8");
+    const formatted = formatFileContent(content, cmd.view_range);
+    return `Here's the content of ${cmd.path} with line numbers:
+${formatted}`;
+  }
+  async function handleCreate(cmd) {
+    const absPath = resolvePath2(cmd.path);
+    if (existsSync4(absPath)) {
+      return `Error: File ${cmd.path} already exists`;
+    }
+    const parentDir = resolve(absPath, "..");
+    await mkdir2(parentDir, { recursive: true });
+    await writeFile(absPath, cmd.file_text, "utf-8");
+    return `File created successfully at: ${cmd.path}`;
+  }
+  async function handleStrReplace(cmd) {
+    const absPath = resolvePath2(cmd.path);
+    if (!existsSync4(absPath)) {
+      return `Error: The path ${cmd.path} does not exist. Please provide a valid path.`;
+    }
+    const s = await stat(absPath);
+    if (s.isDirectory()) {
+      return `Error: The path ${cmd.path} does not exist. Please provide a valid path.`;
+    }
+    const content = await readFile(absPath, "utf-8");
+    const lines = content.split(`
+`);
+    const matchingLines = [];
+    let searchPos = 0;
+    let occurrences = 0;
+    while (true) {
+      const idx = content.indexOf(cmd.old_str, searchPos);
+      if (idx === -1)
+        break;
+      occurrences++;
+      const lineNum = content.substring(0, idx).split(`
+`).length;
+      matchingLines.push(lineNum);
+      searchPos = idx + cmd.old_str.length;
+    }
+    if (occurrences === 0) {
+      return `No replacement was performed, old_str \`${cmd.old_str}\` did not appear verbatim in ${cmd.path}.`;
+    }
+    if (occurrences > 1) {
+      return `No replacement was performed. Multiple occurrences of old_str \`${cmd.old_str}\` in lines: ${matchingLines.join(", ")}. Please ensure it is unique`;
+    }
+    const newContent = content.replace(cmd.old_str, cmd.new_str);
+    await writeFile(absPath, newContent, "utf-8");
+    const newLines = newContent.split(`
+`);
+    const replaceLine = matchingLines[0];
+    const snippetStart = Math.max(0, replaceLine - 3);
+    const snippetEnd = Math.min(newLines.length, replaceLine + 3);
+    const snippet = newLines.slice(snippetStart, snippetEnd).map((line, i) => `${String(snippetStart + i + 1).padStart(6, " ")}	${line}`).join(`
+`);
+    return `The memory file has been edited.
+${snippet}`;
+  }
+  async function handleInsert(cmd) {
+    const absPath = resolvePath2(cmd.path);
+    if (!existsSync4(absPath)) {
+      return `Error: The path ${cmd.path} does not exist`;
+    }
+    const s = await stat(absPath);
+    if (s.isDirectory()) {
+      return `Error: The path ${cmd.path} does not exist`;
+    }
+    const content = await readFile(absPath, "utf-8");
+    const lines = content.split(`
+`);
+    if (cmd.insert_line < 0 || cmd.insert_line > lines.length) {
+      return `Error: Invalid \`insert_line\` parameter: ${cmd.insert_line}. It should be within the range of lines of the file: [0, ${lines.length}]`;
+    }
+    const insertLines = cmd.insert_text.split(`
+`);
+    lines.splice(cmd.insert_line, 0, ...insertLines);
+    await writeFile(absPath, lines.join(`
+`), "utf-8");
+    return `The file ${cmd.path} has been edited.`;
+  }
+  async function handleDelete(cmd) {
+    const absPath = resolvePath2(cmd.path);
+    if (!existsSync4(absPath)) {
+      return `Error: The path ${cmd.path} does not exist`;
+    }
+    await rm(absPath, { recursive: true, force: true });
+    return `Successfully deleted ${cmd.path}`;
+  }
+  async function handleRename(cmd) {
+    const oldAbs = resolvePath2(cmd.old_path);
+    const newAbs = resolvePath2(cmd.new_path);
+    if (!existsSync4(oldAbs)) {
+      return `Error: The path ${cmd.old_path} does not exist`;
+    }
+    if (existsSync4(newAbs)) {
+      return `Error: The destination ${cmd.new_path} already exists`;
+    }
+    const parentDir = resolve(newAbs, "..");
+    await mkdir2(parentDir, { recursive: true });
+    await rename(oldAbs, newAbs);
+    return `Successfully renamed ${cmd.old_path} to ${cmd.new_path}`;
+  }
+  async function execute(cmd) {
+    if (!existsSync4(absMemoryDir)) {
+      await mkdir2(absMemoryDir, { recursive: true });
+    }
+    switch (cmd.command) {
+      case "view":
+        return handleView(cmd);
+      case "create":
+        return handleCreate(cmd);
+      case "str_replace":
+        return handleStrReplace(cmd);
+      case "insert":
+        return handleInsert(cmd);
+      case "delete":
+        return handleDelete(cmd);
+      case "rename":
+        return handleRename(cmd);
+      default:
+        return `Error: Unknown command: ${cmd.command}`;
+    }
+  }
+  return { execute, resolvePath: resolvePath2, toLogicalPath };
+}
+// src/memory/index.ts
+function createNativeMemoryTool(config) {
+  const handler = createMemoryHandler(config.path);
+  return {
+    definition: { type: "memory_20250818", name: "memory" },
+    execute: (cmd) => handler.execute(cmd)
+  };
+}
+function createMemoryTool(config) {
+  const handler = createMemoryHandler(config.path);
+  return {
+    name: "memory",
+    description: `Manage persistent memory files. Supports 6 commands:
+` + `- view: Show directory listing or file contents (path, optional view_range)
+` + `- create: Create a new file (path, file_text)
+` + `- str_replace: Replace text in a file (path, old_str, new_str)
+` + `- insert: Insert text at a line number (path, insert_line, insert_text)
+` + `- delete: Delete a file or directory (path)
+` + `- rename: Rename/move a file or directory (old_path, new_path)
+
+` + `All paths should start with /memories/. Example: /memories/notes.txt
+
+` + "IMPORTANT: Always view your memory directory before starting any task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          enum: ["view", "create", "str_replace", "insert", "delete", "rename"],
+          description: "The memory operation to perform"
+        },
+        path: {
+          type: "string",
+          description: "Path to the file or directory (starts with /memories/)"
+        },
+        file_text: {
+          type: "string",
+          description: "Content for the 'create' command"
+        },
+        old_str: {
+          type: "string",
+          description: "Text to find for 'str_replace' command"
+        },
+        new_str: {
+          type: "string",
+          description: "Replacement text for 'str_replace' command"
+        },
+        insert_line: {
+          type: "number",
+          description: "Line number for 'insert' command"
+        },
+        insert_text: {
+          type: "string",
+          description: "Text to insert for 'insert' command"
+        },
+        old_path: {
+          type: "string",
+          description: "Source path for 'rename' command"
+        },
+        new_path: {
+          type: "string",
+          description: "Destination path for 'rename' command"
+        },
+        view_range: {
+          type: "array",
+          items: { type: "number" },
+          description: "Optional [start, end] line range for 'view' command"
+        }
+      },
+      required: ["command"]
+    },
+    async execute(input) {
+      try {
+        const cmd = input;
+        const result = await handler.execute(cmd);
+        const isError = result.startsWith("Error:");
+        return { content: result, isError };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: `Error: ${message}`, isError: true };
+      }
+    }
+  };
+}
+
 // src/api.ts
 var DEFAULT_MODEL = "claude-sonnet-4-5-20250929";
 var DEFAULT_MAX_TURNS = 10;
@@ -3682,6 +4011,15 @@ function query(params) {
     registry.register(createTaskOutputTool(taskManager));
     registry.register(createTaskStopTool(taskManager));
   }
+  let nativeMemoryTool;
+  if (options.memoryPath) {
+    const memoryConfig = { path: options.memoryPath };
+    if (providerName === "anthropic") {
+      nativeMemoryTool = createNativeMemoryTool(memoryConfig);
+    } else {
+      registry.register(createMemoryTool(memoryConfig));
+    }
+  }
   const generator = agentLoop(prompt, {
     provider,
     model,
@@ -3699,7 +4037,8 @@ function query(params) {
     hooks: hookManager,
     mcpClient,
     previousMessages,
-    sessionLogger
+    sessionLogger,
+    nativeMemoryTool
   });
   return createQuery(generator, abortController);
 }
@@ -3733,6 +4072,9 @@ export {
   query,
   tool as mcpTool,
   getProvider,
+  createNativeMemoryTool,
+  createMemoryTool,
+  createMemoryHandler,
   createMcpServer,
   WriteTool,
   ToolRegistry,

package/dist/memory/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Memory module — provider-agnostic memory tool.
+ *
+ * For Anthropic: Returns a native memory tool config that the provider
+ * handles specially (type: "memory_20250818" + beta header).
+ *
+ * For OpenAI/Gemini: Returns a regular ToolImplementation that the
+ * agent can call just like any other tool.
+ */
+export { createMemoryHandler } from "./memory-handler.js";
+export type { MemoryCommand } from "./memory-handler.js";
+import type { MemoryCommand } from "./memory-handler.js";
+import type { ToolImplementation } from "../tools/registry.js";
+export type MemoryConfig = {
+    /** Absolute path to the memory directory (e.g. /workspace/memories/) */
+    path: string;
+};
+/**
+ * For Anthropic provider: returns the native memory tool definition
+ * to include in the API request, plus handler functions for each command.
+ *
+ * The Anthropic provider needs to:
+ * 1. Add `{type: "memory_20250818", name: "memory"}` to the tools array
+ * 2. Add `context-management-2025-06-27` beta header
+ * 3. Route "memory" tool calls to the handler
+ */
+export type NativeMemoryTool = {
+    /** The tool definition for the Anthropic API (type: "memory_20250818") */
+    definition: {
+        type: "memory_20250818";
+        name: "memory";
+    };
+    /** Execute a memory command */
+    execute: (cmd: MemoryCommand) => Promise<string>;
+};
+export declare function createNativeMemoryTool(config: MemoryConfig): NativeMemoryTool;
+/**
+ * For non-Anthropic providers: wraps memory as a standard ToolImplementation
+ * so any LLM can call it as a regular function tool.
+ */
+export declare function createMemoryTool(config: MemoryConfig): ToolImplementation;
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI/D,MAAM,MAAM,YAAY,GAAG;IACzB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAIF;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0EAA0E;IAC1E,UAAU,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC;IACxD,+BAA+B;IAC/B,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAClD,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAM7E;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CA4EzE"}