@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/tools/filesystem/write.ts

@@ -1,5 +1,6 @@
 import { join, resolve, sep } from "node:path";
 
+import { getAppsDir } from "../../memory/app-store.js";
 import { enqueuePkbIndexJob } from "../../memory/jobs/embed-pkb-file.js";
 import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
 import { RiskLevel } from "../../permissions/types.js";
@@ -9,10 +10,37 @@ 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");
 
+/**
+ * Detects an attempt to write a self-contained interactive HTML document —
+ * the signature of a "visualization" / "artifact" the model should be
+ * building as a real app via the app-builder skill, not dumping as a loose
+ * file. We deliberately trip ONLY on standalone docs with a substantial
+ * INLINE script (the data + rendering live in the file). app-builder's own
+ * scaffold writes a thin shell whose only script is an external module
+ * (`<script type="module" src="/src/main.tsx">`) with an empty body, so this
+ * never blocks the app-builder workflow it redirects to.
+ */
+const STANDALONE_HTML_RE = /<!doctype\s+html|<html[\s>]/i;
+const INLINE_SCRIPT_RE = /<script\b(?![^>]*\bsrc=)[^>]*>[\s\S]{400,}?<\/script>/i;
+
+function isSelfContainedArtifactHtml(path: string, content: string): boolean {
+  if (!/\.html?$/i.test(path)) return false;
+  if (content.length < 3000) return false;
+  if (!STANDALONE_HTML_RE.test(content)) return false;
+  return INLINE_SCRIPT_RE.test(content);
+}
+
+const ARTIFACT_REDIRECT_MESSAGE =
+  'Error: This looks like a self-contained interactive visualization/artifact written as a loose HTML file. Do not build these as standalone .html files. Load the app-builder skill first with `skill_load` using `skill: "app-builder"`, then build it as a real persistent app with `app_create` (the skill loads frontend-design for the visual pass and provides chart widgets). If this genuinely needs to be a raw HTML file inside an existing code project, write it under that project folder.';
+
 /**
  * Returns `true` iff `absPath` is an absolute path that resolves strictly
  * inside `pkbRoot`. Matches the containment semantics used elsewhere in the
@@ -29,34 +57,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;
-
-  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"],
-      };
+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"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -78,6 +106,16 @@ class FileWriteTool implements Tool {
       };
     }
 
+    // Redirect self-contained interactive HTML artifacts to app-builder.
+    // Exempt writes that land inside the apps directory (app-builder's own
+    // scaffold/iteration writes) so we never block the workflow we point to.
+    if (isSelfContainedArtifactHtml(rawPath, fileContent)) {
+      const candidate = resolve(context.workingDir, rawPath);
+      if (!isInsidePkbRoot(candidate, getAppsDir())) {
+        return { content: ARTIFACT_REDIRECT_MESSAGE, isError: true };
+      }
+    }
+
     const ops = new FileSystemOps((path, opts) =>
       sandboxPolicy(path, context.workingDir, opts),
     );
@@ -144,8 +182,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.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.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.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,
+  };
+}