@vellumai/assistant 0.8.3 → 0.8.5

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

@@ -2,9 +2,11 @@ import { randomUUID } from "node:crypto";
 
 import {
   deleteDocument,
+  findInDocument,
   getDocumentById,
   getDocumentsForConversation,
   isDocumentAssociatedWithConversation,
+  replaceInDocument,
   saveDocument,
   searchDocumentsByTitle,
   updateDocumentContent,
@@ -17,7 +19,7 @@ function isPrivilegedDocumentActor(context: ToolContext): boolean {
   );
 }
 
-function documentNotFound(surfaceId: string): ToolExecutionResult {
+export function documentNotFound(surfaceId: string): ToolExecutionResult {
   return {
     content: JSON.stringify({
       success: false,
@@ -28,7 +30,10 @@ function documentNotFound(surfaceId: string): ToolExecutionResult {
   };
 }
 
-function canAccessDocument(surfaceId: string, context: ToolContext): boolean {
+export function canAccessDocument(
+  surfaceId: string,
+  context: ToolContext,
+): boolean {
   return (
     isPrivilegedDocumentActor(context) ||
     isDocumentAssociatedWithConversation(surfaceId, context.conversationId)
@@ -37,6 +42,65 @@ function canAccessDocument(surfaceId: string, context: ToolContext): boolean {
 
 // ── Exported execute functions ──────────────────────────────────────
 
+export function executeDocumentOpen(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  const doc = getDocumentById(surfaceId);
+  if (!doc) {
+    return documentNotFound(surfaceId);
+  }
+
+  if (context.sendToClient) {
+    context.sendToClient({
+      type: "document_editor_show",
+      conversationId: context.conversationId,
+      surfaceId: doc.surfaceId,
+      title: doc.title,
+      initialContent: doc.content,
+    });
+
+    context.sendToClient({
+      type: "ui_surface_show",
+      conversationId: context.conversationId,
+      surfaceId: `preview-${doc.surfaceId}`,
+      surfaceType: "document_preview",
+      display: "inline",
+      title: doc.title,
+      data: {
+        title: doc.title,
+        surfaceId: doc.surfaceId,
+        subtitle: "Document",
+      },
+    });
+
+    return {
+      content: JSON.stringify({
+        success: true,
+        surface_id: doc.surfaceId,
+        title: doc.title,
+        word_count: doc.wordCount,
+        message: "Document editor opened",
+      }),
+      isError: false,
+    };
+  }
+
+  return {
+    content: JSON.stringify({
+      success: false,
+      surface_id: surfaceId,
+      error: "No client connected to open document editor",
+    }),
+    isError: true,
+  };
+}
+
 export function executeDocumentCreate(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -240,3 +304,124 @@ export function executeDocumentDelete(
     isError: false,
   };
 }
+
+export function executeDocumentFind(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  const query = input.query as string;
+  const regex = (input.regex as boolean | undefined) ?? false;
+  const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
+
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  if (regex) {
+    try {
+      new RegExp(query);
+    } catch (e) {
+      return {
+        content: JSON.stringify({
+          success: false,
+          surface_id: surfaceId,
+          error: `Invalid regex: ${e instanceof Error ? e.message : String(e)}`,
+        }),
+        isError: true,
+      };
+    }
+  }
+
+  const result = findInDocument(surfaceId, query, { regex, caseSensitive });
+  if (!result) {
+    return documentNotFound(surfaceId);
+  }
+
+  return {
+    content: JSON.stringify({
+      success: true,
+      surface_id: result.surfaceId,
+      query,
+      total_matches: result.totalMatches,
+      matches: result.matches.map((m) => ({
+        line_number: m.lineNumber,
+        line_content: m.lineContent,
+        match_start: m.matchStart,
+        match_end: m.matchEnd,
+        match_text: m.matchText,
+      })),
+    }),
+    isError: false,
+  };
+}
+
+export function executeDocumentReplaceText(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): ToolExecutionResult {
+  const surfaceId = input.surface_id as string;
+  const find = input.find as string;
+  const replace = (input.replace as string) ?? "";
+  const regex = (input.regex as boolean | undefined) ?? false;
+  const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
+  const maxReplacements = input.max_replacements as number | undefined;
+
+  if (!canAccessDocument(surfaceId, context)) {
+    return documentNotFound(surfaceId);
+  }
+
+  if (regex) {
+    try {
+      new RegExp(find);
+    } catch (err) {
+      return {
+        content: JSON.stringify({
+          success: false,
+          error: `Invalid regex: ${err instanceof Error ? err.message : String(err)}`,
+        }),
+        isError: true,
+      };
+    }
+  }
+
+  const result = replaceInDocument(surfaceId, find, replace, {
+    regex,
+    caseSensitive,
+    maxReplacements,
+  });
+
+  if (!result.success) {
+    return {
+      content: JSON.stringify({
+        success: false,
+        surface_id: surfaceId,
+        error: result.error,
+      }),
+      isError: true,
+    };
+  }
+
+  if (context.sendToClient && result.content_changed) {
+    const doc = getDocumentById(surfaceId);
+    if (doc) {
+      context.sendToClient({
+        type: "document_editor_update",
+        conversationId: context.conversationId,
+        surfaceId,
+        markdown: doc.content,
+        mode: "replace",
+      });
+    }
+  }
+
+  return {
+    content: JSON.stringify({
+      success: true,
+      surface_id: surfaceId,
+      replacements_made: result.replacements_made,
+      content_changed: result.content_changed,
+    }),
+    isError: false,
+  };
+}

package/src/tools/execution-target.ts

@@ -1,4 +1,3 @@
-import { getTool } from "./registry.js";
 import type { ExecutionTarget } from "./types.js";
 
 export interface ManifestOverride {
@@ -6,28 +5,27 @@ export interface ManifestOverride {
   execution_target: "host" | "sandbox";
 }
 
-export function resolveExecutionTarget(
-  toolName: string,
-  manifestOverride?: ManifestOverride,
-): ExecutionTarget {
-  const tool = getTool(toolName);
-  // Manifest-declared execution target is authoritative - check it first so
-  // skill tools with host_/computer_use_ prefixes aren't mis-classified.
-  if (tool?.executionTarget) {
-    return tool.executionTarget;
-  }
-  // Check the tool's executionMode metadata - proxy tools run on the connected
-  // client (host), not inside the sandbox.
-  if (tool?.executionMode === "proxy") {
-    return "host";
-  }
-  // Use manifest metadata for unregistered skill tools so the Permission
-  // Simulator shows accurate execution targets instead of defaulting to sandbox.
-  if (!tool && manifestOverride) {
-    return manifestOverride.execution_target;
-  }
-  // Prefix heuristics for core tools that don't declare an explicit target.
-  if (toolName.startsWith("host_") || toolName.startsWith("computer_use_")) {
+/**
+ * Decide a tool's execution target — sandbox (assistant container) or host
+ * (guardian's device via host-bridge proxy). Pure: same input → same output.
+ *
+ * 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.
+ *
+ * Called once per tool at load/construction time. The returned value is
+ * stamped onto every `LoadedTool`, 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";
   }
   return "sandbox";

package/src/tools/executor.ts

@@ -22,6 +22,7 @@ import { getLogger } from "../util/logger.js";
 import { resolveExecutionTarget } from "./execution-target.js";
 import { executeWithTimeout, safeTimeoutMs } from "./execution-timeout.js";
 import { PermissionChecker } from "./permission-checker.js";
+import { getTool } from "./registry.js";
 import { extractAndSanitize } from "./sensitive-output-placeholders.js";
 import { applyEdit } from "./shared/filesystem/edit-engine.js";
 import { sandboxPolicy } from "./shared/filesystem/path-policy.js";
@@ -126,7 +127,11 @@ export class ToolExecutor {
     let permApprovalMode: string | undefined;
     let permApprovalReason: string | undefined;
     let permRiskThreshold: string | undefined;
-    const executionTarget = resolveExecutionTarget(name);
+    // Registered tools have `executionTarget` stamped at load time; the
+    // `resolveExecutionTarget` fallback only fires for unknown tools (the
+    // executor's name-aliased lookup can race against late registration).
+    const executionTarget =
+      getTool(name)?.executionTarget ?? resolveExecutionTarget({ name });
 
     emitLifecycleEvent(context, {
       type: "start",

package/src/tools/filesystem/edit.ts

@@ -1,5 +1,4 @@
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatEditDiff } from "../shared/filesystem/format-diff.js";
@@ -11,13 +10,10 @@ class FileEditTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -45,9 +41,7 @@ class FileEditTool implements Tool {
           },
         },
         required: ["path", "old_string", "new_string", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/filesystem/list.ts

@@ -1,5 +1,4 @@
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
@@ -10,13 +9,10 @@ class FileListTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -34,9 +30,7 @@ class FileListTool implements Tool {
           },
         },
         required: ["path", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/filesystem/read.ts

@@ -1,7 +1,6 @@
 import { extname } from "node:path";
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import {
@@ -16,13 +15,10 @@ class FileReadTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -45,9 +41,7 @@ class FileReadTool implements Tool {
           },
         },
         required: ["path", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/filesystem/write.ts

@@ -3,7 +3,6 @@ import { join, resolve, sep } from "node:path";
 import { enqueuePkbIndexJob } from "../../memory/jobs/embed-pkb-file.js";
 import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import { registerTool } from "../registry.js";
@@ -35,13 +34,10 @@ class FileWriteTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -60,9 +56,7 @@ class FileWriteTool implements Tool {
           },
         },
         required: ["path", "content", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

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

@@ -1,7 +1,6 @@
 import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 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";
@@ -13,13 +12,10 @@ class HostFileEditTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -46,9 +42,7 @@ class HostFileEditTool implements Tool {
           },
         },
         required: ["path", "old_string", "new_string"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

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

@@ -3,7 +3,6 @@ import { extname } from "node:path";
 import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import {
@@ -18,13 +17,10 @@ class HostFileReadTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -46,9 +42,7 @@ class HostFileReadTool implements Tool {
           },
         },
         required: ["path"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

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

@@ -5,7 +5,6 @@ import { dirname, isAbsolute } from "node:path";
 import { supportsHostProxy } from "../../channels/types.js";
 import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/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";
@@ -15,13 +14,10 @@ class HostFileTransferTool implements Tool {
   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;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           source_path: {
@@ -57,9 +53,7 @@ class HostFileTransferTool implements Tool {
           },
         },
         required: ["source_path", "dest_path", "direction"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

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

@@ -1,7 +1,6 @@
 import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
@@ -13,13 +12,10 @@ class HostFileWriteTool implements Tool {
   description =
     "Write content to a file on your guardian's device, creating it if it does not exist. For files on your own machine, use file_write instead.";
   category = "host-filesystem";
+  executionTarget = "host" as const;
   defaultRiskLevel = RiskLevel.Medium;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           path: {
@@ -37,9 +33,7 @@ class HostFileWriteTool implements Tool {
           },
         },
         required: ["path", "content"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/host-terminal/host-shell.ts

@@ -23,7 +23,6 @@ import { getConfig } from "../../config/loader.js";
 import { isCesShellLockdownEnabled } from "../../credential-execution/feature-gates.js";
 import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
@@ -97,16 +96,13 @@ class HostShellTool implements Tool {
   description =
     "LAST RESORT — Execute a shell command directly on the host machine. You MUST strongly prefer the regular `bash` tool for all commands. Only use `host_bash` when you are absolutely certain the command MUST run on the host machine and CANNOT run in the workspace (e.g., managing host-level system services, accessing host-only peripherals, or interacting with host paths outside the workspace). If in doubt, use `bash` instead. Approval-gated: each invocation must be explicitly approved. Do not use for commands that require injected credentials or secrets.";
   category = "host-terminal";
+  executionTarget = "host" as const;
   // host_bash is a weaker-tier escape hatch under CES lockdown. It remains
   // Medium risk by default but persistent approvals are disabled for
   // untrusted sessions (see execute()).
   defaultRiskLevel = RiskLevel.Medium;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           command: {
@@ -140,9 +136,7 @@ class HostShellTool implements Tool {
           },
         },
         required: ["command", "activity"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/mcp/mcp-tool-factory.ts

@@ -1,7 +1,6 @@
 import type { McpServerConfig } from "../../config/schemas/mcp.js";
 import type { McpServerManager } from "../../mcp/manager.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { toProviderSafeToolName } from "../provider-tool-name.js";
 import { schemaDefinesProperty } from "../schema-transforms.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
@@ -53,13 +52,7 @@ export function createMcpTool(
     ownerMcpServerId: serverId,
     executionTarget: "host",
 
-    getDefinition(): ToolDefinition {
-      return {
-        name: namespacedName,
-        description: metadata.description,
-        input_schema: metadata.inputSchema as ToolDefinition["input_schema"],
-      };
-    },
+    input_schema: metadata.inputSchema as object,
 
     async execute(
       input: Record<string, unknown>,

package/src/tools/memory/register.test.ts

@@ -100,7 +100,7 @@ function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
 
 describe("recallTool definition", () => {
   test("exposes the agentic local search schema", () => {
-    const definition = recallTool.getDefinition();
+    const definition = recallTool;
 
     expect(definition.name).toBe("recall");
     expect(definition.description).toContain("Search local information");