@vellumai/assistant 0.8.5 → 0.8.7

package/src/tools/filesystem/write.ts

@@ -9,7 +9,11 @@ import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
 const logger = getLogger("file-write");
 
@@ -29,34 +33,34 @@ function isInsidePkbRoot(absPath: string, pkbRoot: string): boolean {
   return normalized.startsWith(rootWithSep);
 }
 
-class FileWriteTool implements Tool {
-  name = "file_write";
-  description =
-    "Write content to a file on your own machine, creating it if it does not exist. Use host_file_write for files on your guardian's device instead.";
-  category = "filesystem";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
+export const fileWriteTool = {
+  name: "file_write",
+  description:
+    "Write content to a file on your own machine, creating it if it does not exist. Use host_file_write for files on your guardian's device instead.",
+  category: "filesystem",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
 
-  input_schema = {
-        type: "object",
-        properties: {
-          path: {
-            type: "string",
-            description:
-              "The path to the file to write (absolute or relative to working directory)",
-          },
-          content: {
-            type: "string",
-            description: "The content to write to the file",
-          },
-          activity: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-          },
-        },
-        required: ["path", "content", "activity"],
-      };
+  input_schema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description:
+          "The path to the file to write (absolute or relative to working directory)",
+      },
+      content: {
+        type: "string",
+        description: "The content to write to the file",
+      },
+      activity: {
+        type: "string",
+        description:
+          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+      },
+    },
+    required: ["path", "content", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -144,8 +148,7 @@ class FileWriteTool implements Tool {
       isError: false,
       diff: { filePath, oldContent, newContent, isNewFile },
     };
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const fileWriteTool = new FileWriteTool();
 registerTool(fileWriteTool);

package/src/tools/host-filesystem/edit.test.ts

@@ -26,6 +26,7 @@ mock.module("../../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
     listClientsByCapability: () => [],
   },
+  broadcastMessage: async () => {},
 }));
 
 const { hostFileEditTool } = await import("./edit.js");

package/src/tools/host-filesystem/edit.ts

@@ -5,44 +5,48 @@ import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatEditDiff } from "../shared/filesystem/format-diff.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
-
-class HostFileEditTool implements Tool {
-  name = "host_file_edit";
-  description =
-    "Replace exact text in a file on your guardian's device with new text. For files on your own machine, use file_edit instead.";
-  category = "host-filesystem";
-  executionTarget = "host" as const;
-  defaultRiskLevel = RiskLevel.Medium;
-
-  input_schema = {
-        type: "object",
-        properties: {
-          path: {
-            type: "string",
-            description: "Absolute host path to the file to edit",
-          },
-          old_string: {
-            type: "string",
-            description: "The exact text to find in the file",
-          },
-          new_string: {
-            type: "string",
-            description: "The replacement text",
-          },
-          replace_all: {
-            type: "boolean",
-            description:
-              "Replace all occurrences instead of requiring a unique match (default: false)",
-          },
-          target_client_id: {
-            type: "string",
-            description:
-              "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
-          },
-        },
-        required: ["path", "old_string", "new_string"],
-      };
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
+
+export const hostFileEditTool = {
+  name: "host_file_edit",
+  description:
+    "Replace exact text in a file on your guardian's device with new text. For files on your own machine, use file_edit instead.",
+  category: "host-filesystem",
+  executionTarget: "host",
+  defaultRiskLevel: RiskLevel.Medium,
+
+  input_schema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Absolute host path to the file to edit",
+      },
+      old_string: {
+        type: "string",
+        description: "The exact text to find in the file",
+      },
+      new_string: {
+        type: "string",
+        description: "The replacement text",
+      },
+      replace_all: {
+        type: "boolean",
+        description:
+          "Replace all occurrences instead of requiring a unique match (default: false)",
+      },
+      target_client_id: {
+        type: "string",
+        description:
+          "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
+      },
+    },
+    required: ["path", "old_string", "new_string"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -229,7 +233,5 @@ class HostFileEditTool implements Tool {
       isError: false,
       diff: { filePath, oldContent, newContent, isNewFile: false },
     };
-  }
-}
-
-export const hostFileEditTool: Tool = new HostFileEditTool();
+  },
+} satisfies ToolDefinition;

package/src/tools/host-filesystem/read.test.ts

@@ -26,6 +26,7 @@ mock.module("../../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
     listClientsByCapability: () => [],
   },
+  broadcastMessage: async () => {},
 }));
 
 const { hostFileReadTool } = await import("./read.js");

package/src/tools/host-filesystem/read.ts

@@ -4,45 +4,53 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import {
+  AUDIO_EXTENSIONS,
+  readAudioFile,
+} from "../shared/filesystem/audio-read.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
-class HostFileReadTool implements Tool {
-  name = "host_file_read";
-  description =
-    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP). For files on your own machine, use file_read instead.";
-  category = "host-filesystem";
-  executionTarget = "host" as const;
-  defaultRiskLevel = RiskLevel.Medium;
+export const hostFileReadTool = {
+  name: "host_file_read",
+  description:
+    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP) and audio (MP3, WAV, OGG, FLAC, AAC, M4A). For files on your own machine, use file_read instead.",
+  category: "host-filesystem",
+  executionTarget: "host",
+  defaultRiskLevel: RiskLevel.Medium,
 
-  input_schema = {
-        type: "object",
-        properties: {
-          path: {
-            type: "string",
-            description: "Absolute path to the host file to read",
-          },
-          offset: {
-            type: "number",
-            description: "Line number to start reading from (1-indexed)",
-          },
-          limit: {
-            type: "number",
-            description: "Maximum number of lines to read",
-          },
-          target_client_id: {
-            type: "string",
-            description:
-              "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
-          },
-        },
-        required: ["path"],
-      };
+  input_schema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Absolute path to the host file to read",
+      },
+      offset: {
+        type: "number",
+        description: "Line number to start reading from (1-indexed)",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of lines to read",
+      },
+      target_client_id: {
+        type: "string",
+        description:
+          "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
+      },
+    },
+    required: ["path"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -142,6 +150,14 @@ class HostFileReadTool implements Tool {
       return readImageFile(pathCheck.resolved);
     }
 
+    if (AUDIO_EXTENSIONS.has(ext)) {
+      const pathCheck = hostPolicy(rawPath);
+      if (!pathCheck.ok) {
+        return { content: `Error: ${pathCheck.error}`, isError: true };
+      }
+      return readAudioFile(pathCheck.resolved);
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
     const result = ops.readFileSafe({
@@ -183,7 +199,5 @@ class HostFileReadTool implements Tool {
     }
 
     return { content: result.value.content, isError: false };
-  }
-}
-
-export const hostFileReadTool: Tool = new HostFileReadTool();
+  },
+} satisfies ToolDefinition;

package/src/tools/host-filesystem/transfer.test.ts

@@ -1,4 +1,10 @@
-import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, mock, test } from "bun:test";
@@ -18,12 +24,28 @@ mock.module("../../daemon/host-transfer-proxy.js", () => ({
     get instance() {
       return {
         isAvailable: () => mockProxyAvailable,
-        requestToSandbox: (args: { sourcePath: string; destPath: string; overwrite?: boolean; conversationId: string }) => {
-          toSandboxCalls.push({ sourcePath: args.sourcePath, destPath: args.destPath });
+        requestToSandbox: (args: {
+          sourcePath: string;
+          destPath: string;
+          overwrite?: boolean;
+          conversationId: string;
+        }) => {
+          toSandboxCalls.push({
+            sourcePath: args.sourcePath,
+            destPath: args.destPath,
+          });
           return Promise.resolve({ content: "ok", isError: false });
         },
-        requestToHost: (args: { sourcePath: string; destPath: string; overwrite: boolean; conversationId: string }) => {
-          toHostCalls.push({ sourcePath: args.sourcePath, destPath: args.destPath });
+        requestToHost: (args: {
+          sourcePath: string;
+          destPath: string;
+          overwrite: boolean;
+          conversationId: string;
+        }) => {
+          toHostCalls.push({
+            sourcePath: args.sourcePath,
+            destPath: args.destPath,
+          });
           return Promise.resolve({ content: "ok", isError: false });
         },
       };
@@ -38,6 +60,7 @@ mock.module("../../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
     listClientsByCapability: () => [],
   },
+  broadcastMessage: async () => {},
 }));
 
 const { hostFileTransferTool } = await import("./transfer.js");
@@ -244,7 +267,9 @@ describe("host_file_transfer managed mode", () => {
     );
 
     expect(toSandboxCalls.length).toBe(1);
-    expect(toSandboxCalls[0].destPath).toBe(join(workingDir, "relative", "file.txt"));
+    expect(toSandboxCalls[0].destPath).toBe(
+      join(workingDir, "relative", "file.txt"),
+    );
   });
 
   test("to_host relative source is pre-resolved before proxy call", async () => {

package/src/tools/host-filesystem/transfer.ts

@@ -7,53 +7,61 @@ import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
-class HostFileTransferTool implements Tool {
-  name = "host_file_transfer";
-  description =
-    "Copy a file between the assistant's workspace and the host machine. Set direction to 'to_host' to send a workspace file to the host, or 'to_sandbox' to pull a host file into the workspace. When multiple clients support host_file, specify which one to use with target_client_id.";
-  category = "host-filesystem";
-  executionTarget = "host" as const;
-  defaultRiskLevel = RiskLevel.Medium;
+export const hostFileTransferTool = {
+  name: "host_file_transfer",
 
-  input_schema = {
-        type: "object",
-        properties: {
-          source_path: {
-            type: "string",
-            description:
-              "Source file path. For to_host, a workspace path — relative paths resolve against the sandbox working directory; /workspace/... paths are also accepted. For to_sandbox, must be an absolute host path.",
-          },
-          dest_path: {
-            type: "string",
-            description:
-              "Destination path. For to_host, must be an absolute host path. For to_sandbox, a workspace path — relative paths resolve against the sandbox working directory; /workspace/... paths are also accepted.",
-          },
-          direction: {
-            type: "string",
-            enum: ["to_host", "to_sandbox"],
-            description:
-              "Transfer direction: 'to_host' sends a workspace file to the host, 'to_sandbox' pulls a host file into the workspace.",
-          },
-          overwrite: {
-            type: "boolean",
-            description:
-              "Whether to overwrite the destination file if it already exists (default: false)",
-          },
-          activity: {
-            type: "string",
-            description:
-              "Brief description of why the file is being transferred (for audit logging)",
-          },
-          target_client_id: {
-            type: "string",
-            description:
-              "ID of the specific client to transfer files to/from. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
-          },
-        },
-        required: ["source_path", "dest_path", "direction"],
-      };
+  description:
+    "Copy a file between the assistant's workspace and the host machine. Set direction to 'to_host' to send a workspace file to the host, or 'to_sandbox' to pull a host file into the workspace. When multiple clients support host_file, specify which one to use with target_client_id.",
+
+  category: "host-filesystem",
+
+  executionTarget: "host",
+
+  defaultRiskLevel: RiskLevel.Medium,
+
+  input_schema: {
+    type: "object",
+    properties: {
+      source_path: {
+        type: "string",
+        description:
+          "Source file path. For to_host, a workspace path — relative paths resolve against the sandbox working directory; /workspace/... paths are also accepted. For to_sandbox, must be an absolute host path.",
+      },
+      dest_path: {
+        type: "string",
+        description:
+          "Destination path. For to_host, must be an absolute host path. For to_sandbox, a workspace path — relative paths resolve against the sandbox working directory; /workspace/... paths are also accepted.",
+      },
+      direction: {
+        type: "string",
+        enum: ["to_host", "to_sandbox"],
+        description:
+          "Transfer direction: 'to_host' sends a workspace file to the host, 'to_sandbox' pulls a host file into the workspace.",
+      },
+      overwrite: {
+        type: "boolean",
+        description:
+          "Whether to overwrite the destination file if it already exists (default: false)",
+      },
+      activity: {
+        type: "string",
+        description:
+          "Brief description of why the file is being transferred (for audit logging)",
+      },
+      target_client_id: {
+        type: "string",
+        description:
+          "ID of the specific client to transfer files to/from. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
+      },
+    },
+    required: ["source_path", "dest_path", "direction"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -219,86 +227,91 @@ class HostFileTransferTool implements Tool {
     // target_client_id case is caught by the scoped guard at the top of
     // execute(); on macos a stale target_client_id is silently ignored
     // here, matching the read/write/edit pattern.
-    return this.executeLocal(resolvedSourcePath, resolvedDestPath, overwrite);
+    return executeLocal(resolvedSourcePath, resolvedDestPath, overwrite);
+  },
+} satisfies ToolDefinition;
+
+/**
+ * Local-mode filesystem copy. Module-level so the `host_file_transfer`
+ * tool can be authored as a plain {@link ToolDefinition} literal without
+ * losing access to this helper — the registry stores finalized literal
+ * references, so `this`-based method dispatch is no longer available
+ * on registered tools.
+ */
+async function executeLocal(
+  sourcePath: string,
+  destPath: string,
+  overwrite: boolean,
+): Promise<ToolExecutionResult> {
+  // Resolve symlinks on the source to ensure we read the real file.
+  let resolvedSource: string;
+  try {
+    resolvedSource = await realpath(sourcePath);
+  } catch {
+    return {
+      content: `Error: source file not found: ${sourcePath}`,
+      isError: true,
+    };
   }
 
-  private async executeLocal(
-    sourcePath: string,
-    destPath: string,
-    overwrite: boolean,
-  ): Promise<ToolExecutionResult> {
-    // Resolve symlinks on the source to ensure we read the real file.
-    let resolvedSource: string;
-    try {
-      resolvedSource = await realpath(sourcePath);
-    } catch {
+  // Verify the source is a regular file (not a directory).
+  try {
+    const stat = await lstat(resolvedSource);
+    if (stat.isDirectory()) {
       return {
-        content: `Error: source file not found: ${sourcePath}`,
+        content: `Error: source path is a directory, not a file: ${sourcePath}. To transfer a directory, archive it first (e.g. tar or zip) and transfer the archive.`,
         isError: true,
       };
     }
-
-    // Verify the source is a regular file (not a directory).
-    try {
-      const stat = await lstat(resolvedSource);
-      if (stat.isDirectory()) {
-        return {
-          content: `Error: source path is a directory, not a file: ${sourcePath}. To transfer a directory, archive it first (e.g. tar or zip) and transfer the archive.`,
-          isError: true,
-        };
-      }
-      if (!stat.isFile()) {
-        return {
-          content: `Error: source path is not a regular file: ${sourcePath}`,
-          isError: true,
-        };
-      }
-    } catch (err) {
+    if (!stat.isFile()) {
       return {
-        content: `Error: cannot stat source file: ${err instanceof Error ? err.message : String(err)}`,
+        content: `Error: source path is not a regular file: ${sourcePath}`,
         isError: true,
       };
     }
+  } catch (err) {
+    return {
+      content: `Error: cannot stat source file: ${err instanceof Error ? err.message : String(err)}`,
+      isError: true,
+    };
+  }
 
-    // Ensure the destination parent directory exists.
-    try {
-      await mkdir(dirname(destPath), { recursive: true });
-    } catch (err) {
-      return {
-        content: `Error: failed to create destination directory: ${err instanceof Error ? err.message : String(err)}`,
-        isError: true,
-      };
-    }
+  // Ensure the destination parent directory exists.
+  try {
+    await mkdir(dirname(destPath), { recursive: true });
+  } catch (err) {
+    return {
+      content: `Error: failed to create destination directory: ${err instanceof Error ? err.message : String(err)}`,
+      isError: true,
+    };
+  }
 
-    // COPYFILE_EXCL makes the call fail atomically if dest exists,
-    // avoiding a TOCTOU race vs. a separate lstat check.
-    try {
-      const flags = overwrite ? 0 : constants.COPYFILE_EXCL;
-      await copyFile(resolvedSource, destPath, flags);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (!overwrite && msg.includes("EEXIST")) {
-        return {
-          content: `Error: destination file already exists: ${destPath}. Set overwrite to true to replace it.`,
-          isError: true,
-        };
-      }
-      const hint = msg.includes("EACCES")
-        ? " (permission denied)"
-        : msg.includes("ENOSPC")
-          ? " (no space left on device)"
-          : "";
+  // COPYFILE_EXCL makes the call fail atomically if dest exists,
+  // avoiding a TOCTOU race vs. a separate lstat check.
+  try {
+    const flags = overwrite ? 0 : constants.COPYFILE_EXCL;
+    await copyFile(resolvedSource, destPath, flags);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!overwrite && msg.includes("EEXIST")) {
       return {
-        content: `Error copying file${hint}: ${msg}`,
+        content: `Error: destination file already exists: ${destPath}. Set overwrite to true to replace it.`,
         isError: true,
       };
     }
-
+    const hint = msg.includes("EACCES")
+      ? " (permission denied)"
+      : msg.includes("ENOSPC")
+        ? " (no space left on device)"
+        : "";
     return {
-      content: `Successfully copied ${sourcePath} to ${destPath}`,
-      isError: false,
+      content: `Error copying file${hint}: ${msg}`,
+      isError: true,
     };
   }
-}
 
-export const hostFileTransferTool: Tool = new HostFileTransferTool();
+  return {
+    content: `Successfully copied ${sourcePath} to ${destPath}`,
+    isError: false,
+  };
+}

package/src/tools/host-filesystem/write.test.ts

@@ -26,6 +26,7 @@ mock.module("../../runtime/assistant-event-hub.js", () => ({
   assistantEventHub: {
     listClientsByCapability: () => [],
   },
+  broadcastMessage: async () => {},
 }));
 
 const { hostFileWriteTool } = await import("./write.js");