@vellumai/assistant 0.8.5 → 0.8.7

package/src/tools/document/document-tool.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
 
 import {
+  addDocumentConversation,
   deleteDocument,
   findInDocument,
+  findRecentEmptyDocumentByTitle,
   getDocumentById,
   getDocumentsForConversation,
   isDocumentAssociatedWithConversation,
@@ -40,13 +42,36 @@ export function canAccessDocument(
   );
 }
 
+function invalidInput(message: string): ToolExecutionResult {
+  return {
+    content: JSON.stringify({
+      success: false,
+      error: `Invalid input: ${message}`,
+    }),
+    isError: true,
+  };
+}
+
+function validateSurfaceId(
+  input: Record<string, unknown>,
+): ToolExecutionResult | string {
+  if (typeof input.surface_id !== "string" || input.surface_id.trim() === "") {
+    return invalidInput(
+      "surface_id is required and must be a non-empty string",
+    );
+  }
+  return input.surface_id;
+}
+
 // ── Exported execute functions ──────────────────────────────────────
 
 export function executeDocumentOpen(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
   }
@@ -101,12 +126,87 @@ export function executeDocumentOpen(
   };
 }
 
+const EMPTY_DOCUMENT_DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+
+/**
+ * If the model just created an empty same-title document in this conversation
+ * and is now creating a second one with real content, reuse the first row
+ * instead of producing a duplicate. Returns `null` when no dedupe applies.
+ *
+ * Only triggers when `initialContent` is non-empty — an empty incoming create
+ * likely means the model intends a fresh blank doc.
+ */
+function maybeReuseEmptyDocument(
+  title: string,
+  initialContent: string,
+  context: ToolContext,
+): ToolExecutionResult | null {
+  if (initialContent.length === 0) return null;
+  const existing = findRecentEmptyDocumentByTitle(
+    context.conversationId,
+    title,
+    EMPTY_DOCUMENT_DEDUPE_WINDOW_MS,
+  );
+  if (!existing) return null;
+
+  const surfaceId = existing.surfaceId;
+  const update = updateDocumentContent(surfaceId, initialContent, "replace");
+  if (!update.success) return null;
+
+  // Defensive idempotent insert (saveDocument from the create-new path already
+  // ran addDocumentConversation; INSERT OR IGNORE makes this a safe no-op).
+  addDocumentConversation(surfaceId, context.conversationId);
+
+  if (context.sendToClient) {
+    // Use document_editor_update — not document_editor_show — because the
+    // empty draft is typically still OPEN on the macOS client. A *_show on an
+    // open doc triggers DocumentManager.closeDocument() → async save() of the
+    // OLD (empty) content, clobbering the initialContent we just persisted.
+    context.sendToClient({
+      type: "document_editor_update",
+      conversationId: context.conversationId,
+      surfaceId,
+      markdown: initialContent,
+      mode: "replace",
+    });
+
+    context.sendToClient({
+      type: "ui_surface_show",
+      conversationId: context.conversationId,
+      surfaceId: `preview-${surfaceId}`,
+      surfaceType: "document_preview",
+      display: "inline",
+      title,
+      data: {
+        title,
+        surfaceId,
+        subtitle: "Document",
+      },
+    });
+  }
+
+  return {
+    content: JSON.stringify({
+      surface_id: surfaceId,
+      title,
+      opened: context.sendToClient != null,
+      reused: true,
+      message: "Document editor reopened (deduped empty draft)",
+    }),
+    isError: false,
+  };
+}
+
 export function executeDocumentCreate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
   const title = (input.title as string | undefined) || "Untitled Document";
   const initialContent = (input.initial_content as string | undefined) || "";
+
+  const reused = maybeReuseEmptyDocument(title, initialContent, context);
+  if (reused) return reused;
+
   const surfaceId = `doc-${randomUUID()}`;
 
   // Persist the document so any client (web or macOS) can fetch it via
@@ -174,9 +274,24 @@ export function executeDocumentUpdate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
-  const content = input.content as string;
-  const mode = (input.mode as string | undefined) || "append";
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
+  if (typeof input.content !== "string") {
+    return invalidInput("content is required and must be a string");
+  }
+  // Loose `!= null` to match validateInputAgainstSchema, which treats null as
+  // "absent" for enum checks — without this, { mode: null } passes the
+  // factory validator but rejects here. The `?? "append"` below handles null.
+  if (
+    input.mode != null &&
+    input.mode !== "replace" &&
+    input.mode !== "append"
+  ) {
+    return invalidInput('mode must be "replace" or "append"');
+  }
+  const content = input.content;
+  const mode = (input.mode as "replace" | "append" | undefined) ?? "append";
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -229,7 +344,9 @@ export function executeDocumentRead(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
   }
@@ -286,7 +403,9 @@ export function executeDocumentDelete(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
   }
@@ -309,7 +428,9 @@ export function executeDocumentFind(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
   const query = input.query as string;
   const regex = (input.regex as boolean | undefined) ?? false;
   const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
@@ -360,7 +481,9 @@ export function executeDocumentReplaceText(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const surfaceId = input.surface_id as string;
+  const surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
   const find = input.find as string;
   const replace = (input.replace as string) ?? "";
   const regex = (input.regex as boolean | undefined) ?? false;

package/src/tools/execution-target.ts

@@ -11,20 +11,17 @@ export interface ManifestOverride {
  *
  * Resolution order:
  *   1. Declared `executionTarget` on the tool wins.
- *   2. `executionMode === "proxy"` ⇒ host (proxied tools run on the client).
- *   3. Name prefix heuristic — `host_*` / `computer_use_*` ⇒ host.
- *   4. Default sandbox.
+ *   2. Name prefix heuristic — `host_*` / `computer_use_*` ⇒ host.
+ *   3. Default sandbox.
  *
  * Called once per tool at load/construction time. The returned value is
- * stamped onto every `LoadedTool`, so runtime reads are just a field read.
+ * stamped onto every `Tool`, so runtime reads are just a field read.
  */
 export function resolveExecutionTarget(tool: {
   name: string;
   executionTarget?: ExecutionTarget;
-  executionMode?: "local" | "proxy";
 }): ExecutionTarget {
   if (tool.executionTarget) return tool.executionTarget;
-  if (tool.executionMode === "proxy") return "host";
   if (tool.name.startsWith("host_") || tool.name.startsWith("computer_use_")) {
     return "host";
   }

package/src/tools/execution-timeout.ts

@@ -1,9 +1,8 @@
+import { DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC } from "../api/constants/tool-execution.js";
 import type { ToolExecutionResult } from "./types.js";
 
 const TIMEOUT_SENTINEL = Symbol("tool-timeout");
 
-const DEFAULT_TOOL_TIMEOUT_SEC = 120;
-
 /**
  * Convert a config-provided seconds value to a safe milliseconds value,
  * falling back to the default if the input is NaN, non-finite, zero, or negative.
@@ -11,7 +10,7 @@ const DEFAULT_TOOL_TIMEOUT_SEC = 120;
 export function safeTimeoutMs(sec: unknown): number {
   const n = Number(sec);
   if (!Number.isFinite(n) || n <= 0) {
-    return DEFAULT_TOOL_TIMEOUT_SEC * 1000;
+    return DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC * 1000;
   }
   return n * 1000;
 }
@@ -29,7 +28,7 @@ export async function executeWithTimeout(
   const safeMs =
     Number.isFinite(timeoutMs) && timeoutMs > 0
       ? timeoutMs
-      : DEFAULT_TOOL_TIMEOUT_SEC * 1000;
+      : DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC * 1000;
   let timeoutHandle: ReturnType<typeof setTimeout>;
   const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
     timeoutHandle = setTimeout(() => resolve(TIMEOUT_SENTINEL), safeMs);

package/src/tools/executor.ts

@@ -28,7 +28,7 @@ import { applyEdit } from "./shared/filesystem/edit-engine.js";
 import { sandboxPolicy } from "./shared/filesystem/path-policy.js";
 import { MAX_FILE_SIZE_BYTES } from "./shared/filesystem/size-guard.js";
 import { ToolApprovalHandler } from "./tool-approval-handler.js";
-import { resolveToolNameAlias } from "./tool-name-aliases.js";
+import { resolveToolInvocationAlias } from "./tool-name-aliases.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -78,10 +78,11 @@ export class ToolExecutor {
     };
 
     const middlewares = getMiddlewaresFor("toolExecute");
-    const executionName = resolveToolNameAlias(name, context.allowedToolNames);
+    const { name: executionName, input: executionInput } =
+      resolveToolInvocationAlias(name, input, context.allowedToolNames);
     const pipelineArgs: ToolExecuteArgs = {
       name: executionName,
-      input,
+      input: executionInput,
       context,
     };
 
@@ -241,48 +242,18 @@ export class ToolExecutor {
         permApprovalReason = "grant_scoped_consumed";
       }
 
-      // Execute the tool - proxy tools delegate to an external resolver.
-      // Use the shared per-tool timeout helper so the pipeline runner and
-      // the inner execute-with-timeout wrapper agree on the same budget.
-      let execResult: ToolExecutionResult;
+      // Execute the tool. Tools that forward to an external resolver
+      // (computer-use, ui-surface, apps, meet) handle that dispatch in
+      // their own `execute()` body — the executor no longer special-cases
+      // proxy mode here.
       const toolTimeoutMs = computePerToolTimeoutMs(name, input);
-
       const execContext = context;
 
-      if (tool.executionMode === "proxy") {
-        if (!context.proxyToolResolver) {
-          const msg = `No proxy resolver configured for proxy tool "${name}". This tool requires an external resolver (e.g. a connected macOS client for computer-use tools).`;
-          const durationMs = Date.now() - startTime;
-          emitLifecycleEvent(context, {
-            type: "error",
-            toolName: name,
-            executionTarget,
-            input,
-            workingDir: context.workingDir,
-            conversationId: context.conversationId,
-            requestId: context.requestId,
-            riskLevel,
-            matchedTrustRuleId: permMatchedTrustRuleId,
-            decision: "error",
-            durationMs,
-            errorMessage: msg,
-            isExpected: true,
-            errorCategory: "tool_failure",
-          });
-          return { content: msg, isError: true };
-        }
-        execResult = await executeWithTimeout(
-          context.proxyToolResolver(name, input),
-          toolTimeoutMs,
-          name,
-        );
-      } else {
-        execResult = await executeWithTimeout(
-          tool.execute(input, execContext),
-          toolTimeoutMs,
-          name,
-        );
-      }
+      let execResult: ToolExecutionResult = await executeWithTimeout(
+        tool.execute(input, execContext),
+        toolTimeoutMs,
+        name,
+      );
 
       // CES approval bridge: if the tool returned an approval_required
       // indicator, present the proposal to the guardian via the existing
@@ -336,19 +307,11 @@ export class ToolExecutor {
             "CES approval granted - retrying tool invocation with grantId",
           );
 
-          if (tool.executionMode === "proxy") {
-            execResult = await executeWithTimeout(
-              context.proxyToolResolver!(name, retryInput),
-              toolTimeoutMs,
-              name,
-            );
-          } else {
-            execResult = await executeWithTimeout(
-              tool.execute(retryInput, execContext),
-              toolTimeoutMs,
-              name,
-            );
-          }
+          execResult = await executeWithTimeout(
+            tool.execute(retryInput, execContext),
+            toolTimeoutMs,
+            name,
+          );
         } else if (
           bridgeResult.outcome === "denied" ||
           bridgeResult.outcome === "timeout"

package/src/tools/filesystem/edit.ts

@@ -3,45 +3,49 @@ import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatEditDiff } from "../shared/filesystem/format-diff.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
-
-class FileEditTool implements Tool {
-  name = "file_edit";
-  description =
-    "Replace an exact string in a file on your own machine with a new string. Use this for surgical edits instead of rewriting entire files. Use host_file_edit 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 edit (absolute or relative to working directory)",
-          },
-          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 of old_string instead of requiring a unique match (default: false)",
-          },
-          activity: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-          },
-        },
-        required: ["path", "old_string", "new_string", "activity"],
-      };
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
+
+export const fileEditTool = {
+  name: "file_edit",
+  description:
+    "Replace an exact string in a file on your own machine with a new string. Use this for surgical edits instead of rewriting entire files. Use host_file_edit 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 edit (absolute or relative to working directory)",
+      },
+      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 of old_string instead of requiring a unique match (default: false)",
+      },
+      activity: {
+        type: "string",
+        description:
+          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+      },
+    },
+    required: ["path", "old_string", "new_string", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -152,8 +156,7 @@ class FileEditTool implements Tool {
       isError: false,
       diff: { filePath, oldContent, newContent, isNewFile: false },
     };
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const fileEditTool = new FileEditTool();
 registerTool(fileEditTool);

package/src/tools/filesystem/list.ts

@@ -2,35 +2,39 @@ import { RiskLevel } from "../../permissions/types.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.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 FileListTool implements Tool {
-  name = "file_list";
-  description =
-    "List the contents of a directory on your own machine. Returns file and subdirectory names with type indicators and sizes.";
-  category = "filesystem";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
+export const fileListTool = {
+  name: "file_list",
+  description:
+    "List the contents of a directory on your own machine. Returns file and subdirectory names with type indicators and sizes.",
+  category: "filesystem",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
 
-  input_schema = {
-        type: "object",
-        properties: {
-          path: {
-            type: "string",
-            description: "The directory path to list",
-          },
-          glob: {
-            type: "string",
-            description: "Filter entries by glob pattern, e.g. '*.md'",
-          },
-          activity: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-          },
-        },
-        required: ["path", "activity"],
-      };
+  input_schema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "The directory path to list",
+      },
+      glob: {
+        type: "string",
+        description: "Filter entries by glob pattern, e.g. '*.md'",
+      },
+      activity: {
+        type: "string",
+        description:
+          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+      },
+    },
+    required: ["path", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -80,8 +84,7 @@ class FileListTool implements Tool {
     }
 
     return { content: result.value.listing, isError: false };
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const fileListTool = new FileListTool();
 registerTool(fileListTool);

package/src/tools/filesystem/read.ts

@@ -2,46 +2,54 @@ import { extname } from "node:path";
 
 import { RiskLevel } from "../../permissions/types.js";
 import { registerTool } from "../registry.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 { sandboxPolicy } from "../shared/filesystem/path-policy.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
-class FileReadTool implements Tool {
-  name = "file_read";
-  description =
-    "Read the contents of a file on your own machine. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. Use host_file_read for files on your guardian's device instead.";
-  category = "filesystem";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
+export const fileReadTool = {
+  name: "file_read",
+  description:
+    "Read the contents of a file on your own machine. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. For audio files (MP3, WAV, OGG, FLAC, AAC, M4A), returns the audio for listening. Use host_file_read 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 read (absolute or relative to working directory)",
-          },
-          offset: {
-            type: "number",
-            description: "Line number to start reading from (1-indexed)",
-          },
-          limit: {
-            type: "number",
-            description: "Maximum number of lines to read",
-          },
-          activity: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-          },
-        },
-        required: ["path", "activity"],
-      };
+  input_schema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description:
+          "The path to the file to read (absolute or relative to working directory)",
+      },
+      offset: {
+        type: "number",
+        description: "Line number to start reading from (1-indexed)",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of lines to read",
+      },
+      activity: {
+        type: "string",
+        description:
+          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+      },
+    },
+    required: ["path", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -68,6 +76,18 @@ class FileReadTool implements Tool {
       return readImageFile(pathCheck.resolved);
     }
 
+    // For audio files, delegate to the shared audio reader.
+    if (AUDIO_EXTENSIONS.has(ext)) {
+      const pathCheck = sandboxPolicy(rawPath, context.workingDir);
+      if (!pathCheck.ok) {
+        return {
+          content: `Error: ${pathCheck.error}. To read files outside the workspace, use the host_file_read tool instead.`,
+          isError: true,
+        };
+      }
+      return readAudioFile(pathCheck.resolved);
+    }
+
     const ops = new FileSystemOps((path, opts) =>
       sandboxPolicy(path, context.workingDir, opts),
     );
@@ -105,8 +125,7 @@ class FileReadTool implements Tool {
     }
 
     return { content: result.value.content, isError: false };
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const fileReadTool = new FileReadTool();
 registerTool(fileReadTool);