@vellumai/assistant 0.8.4 → 0.8.6

package/src/tools/credential-execution/make-authenticated-request.ts

@@ -13,7 +13,6 @@
 import { GrantProposalSchema, renderProposal } from "@vellumai/service-contracts/credential-rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -24,13 +23,10 @@ class MakeAuthenticatedRequestTool implements Tool {
   description =
     "Execute an authenticated HTTP request through CES. CES injects the credential and returns the response - the assistant never sees raw secrets.";
   category = "credential-execution";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.High;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           credentialHandle: {
@@ -68,9 +64,7 @@ class MakeAuthenticatedRequestTool implements Tool {
           },
         },
         required: ["credentialHandle", "method", "url", "purpose"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/credential-execution/manage-secure-command-tool.ts

@@ -18,7 +18,6 @@
 import type { ManageSecureCommandTool } from "@vellumai/service-contracts/rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -31,13 +30,10 @@ class ManageSecureCommandToolImpl implements Tool {
     "Accepts only bundle metadata for guardian review - never raw bytes or file paths. " +
     "Each invocation requires fresh approval.";
   category = "credential-execution";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.High;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           action: {
@@ -236,9 +232,7 @@ class ManageSecureCommandToolImpl implements Tool {
           },
         },
         required: ["action", "toolName"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/credential-execution/run-authenticated-command.ts

@@ -13,7 +13,6 @@
 import { GrantProposalSchema, renderProposal } from "@vellumai/service-contracts/credential-rpc";
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -24,13 +23,10 @@ class RunAuthenticatedCommandTool implements Tool {
   description =
     "Execute a command with credential environment variables injected by CES. The command runs inside the CES sandbox - the assistant never sees raw secrets.";
   category = "credential-execution";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.High;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           credentialHandle: {
@@ -97,9 +93,7 @@ class RunAuthenticatedCommandTool implements Tool {
           },
         },
         required: ["credentialHandle", "command", "purpose"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/credentials/vault.ts

@@ -10,7 +10,6 @@ import {
   getActiveConnection,
 } from "../../oauth/oauth-store.js";
 import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { credentialKey } from "../../security/credential-key.js";
 import {
   deleteSecureKeyAsync,
@@ -75,13 +74,10 @@ class CredentialStoreTool implements Tool {
   description =
     "Store, list, delete, or prompt for credentials in the secure vault";
   category = "credentials";
+  executionTarget = "sandbox" as const;
   defaultRiskLevel = RiskLevel.Low;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
+  input_schema = {
         type: "object",
         properties: {
           action: {
@@ -181,9 +177,7 @@ class CredentialStoreTool implements Tool {
           },
         },
         required: ["action"],
-      },
-    };
-  }
+      };
 
   async execute(
     input: Record<string, unknown>,

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,14 +42,171 @@ 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 surfaceIdOrError = validateSurfaceId(input);
+  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  const surfaceId = surfaceIdOrError;
+  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,
+  };
+}
+
+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
@@ -115,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);
@@ -170,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);
   }
@@ -227,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);
   }
@@ -250,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;
@@ -301,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

@@ -1,4 +1,3 @@
-import { getTool } from "./registry.js";
 import type { ExecutionTarget } from "./types.js";
 
 export interface ManifestOverride {
@@ -6,28 +5,24 @@ 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. 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.
+ */
+export function resolveExecutionTarget(tool: {
+  name: string;
+  executionTarget?: ExecutionTarget;
+}): ExecutionTarget {
+  if (tool.executionTarget) return tool.executionTarget;
+  if (tool.name.startsWith("host_") || tool.name.startsWith("computer_use_")) {
     return "host";
   }
   return "sandbox";

package/src/tools/executor.ts

@@ -22,12 +22,13 @@ 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";
 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,
@@ -77,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,
     };
 
@@ -126,7 +128,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",
@@ -236,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
@@ -331,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

@@ -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>,