@vellumai/assistant 0.10.12 → 0.11.0-staging.1

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

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
 
+import { z } from "zod";
+
 import {
   addDocumentConversation,
   deleteDocument,
@@ -14,6 +16,10 @@ import {
   updateDocumentContent,
 } from "../../documents/document-store.js";
 import { canActOnPrivilegedDocuments } from "../../runtime/effective-capabilities.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 function isPrivilegedDocumentActor(context: ToolContext): boolean {
@@ -62,14 +68,83 @@ function validateSurfaceId(
   return input.surface_id;
 }
 
+// ── Model-input schemas ─────────────────────────────────────────────
+//
+// One schema per tool entry point, `safeParse`d at the top of each
+// `execute*`. Skill-owned tools are skipped by the central
+// `TOOL_INPUT_SCHEMAS` gate, so validation lives in the executor
+// (`ask_question` pre-registry precedent); the advertised `input_schema`
+// stays hand-written in the document-editor skill's `TOOLS.json`, and
+// `document-tool-input-schemas.test.ts` guards the two against structural
+// drift.
+//
+// Tolerance matches the executors' own reads — the schemas only reject
+// values the executors would otherwise pass downstream unchecked
+// (`document_find`'s `query` reaching `.toLowerCase()` as a non-string) or
+// persist unvalidated (`document_create`'s `title`):
+//
+// - `nullAsOmitted` on optionals where null and absent are equivalent under
+//   the falsy/`??` reads — including `surface_id`, whose bespoke
+//   `validateSurfaceId` / `resolveUpdateSurfaceId` error messages stay the
+//   contract for the missing/empty cases.
+// - `.catch(undefined)` on `document_list`'s `query`, which the executor
+//   silently ignores when malformed (falls back to the conversation list).
+// - `document_update`'s `mode` is deliberately UNDECLARED (loose
+//   passthrough): its bespoke check owns the error message and the
+//   `{ mode: null }` tolerance that mirrors `validateInputAgainstSchema`.
+
+export const documentOpenInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+});
+
+export const documentCreateInputSchema = z.looseObject({
+  title: nullAsOmitted(z.string()),
+  initial_content: nullAsOmitted(z.string()),
+});
+
+export const documentUpdateInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  content: nullAsOmitted(z.string()),
+});
+
+export const documentReadInputSchema = documentOpenInputSchema;
+
+export const documentListInputSchema = z.looseObject({
+  query: z.string().optional().catch(undefined),
+});
+
+export const documentDeleteInputSchema = documentOpenInputSchema;
+
+export const documentFindInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  query: z.string(),
+  regex: nullAsOmitted(z.boolean()),
+  case_sensitive: nullAsOmitted(z.boolean()),
+});
+
+export const documentReplaceTextInputSchema = z.looseObject({
+  surface_id: nullAsOmitted(z.string()),
+  find: z.string(),
+  replace: nullAsOmitted(z.string()),
+  regex: nullAsOmitted(z.boolean()),
+  case_sensitive: nullAsOmitted(z.boolean()),
+  max_replacements: nullAsOmitted(z.number()),
+});
+
 // ── Exported execute functions ──────────────────────────────────────
 
 export function executeDocumentOpen(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentOpenInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_open", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -140,17 +215,23 @@ function maybeReuseEmptyDocument(
   initialContent: string,
   context: ToolContext,
 ): ToolExecutionResult | null {
-  if (initialContent.length === 0) return null;
+  if (initialContent.length === 0) {
+    return null;
+  }
   const existing = findRecentEmptyDocumentByTitle(
     context.conversationId,
     title,
     EMPTY_DOCUMENT_DEDUPE_WINDOW_MS,
   );
-  if (!existing) return null;
+  if (!existing) {
+    return null;
+  }
 
   const surfaceId = existing.surfaceId;
   const update = updateDocumentContent(surfaceId, initialContent, "replace");
-  if (!update.success) return null;
+  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).
@@ -200,11 +281,17 @@ 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 parsedInput = documentCreateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_create", parsedInput.error);
+  }
+  const title = parsedInput.data.title || "Untitled Document";
+  const initialContent = parsedInput.data.initial_content || "";
 
   const reused = maybeReuseEmptyDocument(title, initialContent, context);
-  if (reused) return reused;
+  if (reused) {
+    return reused;
+  }
 
   const surfaceId = `doc-${randomUUID()}`;
 
@@ -298,11 +385,17 @@ export function executeDocumentUpdate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentUpdateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_update", parsedInput.error);
+  }
   if (typeof input.content !== "string") {
     return invalidInput("content is required and must be a string");
   }
   const surfaceIdOrError = resolveUpdateSurfaceId(input, context);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   // Loose `!= null` to match validateInputAgainstSchema, which treats null as
   // "absent" for enum checks — without this, { mode: null } passes the
@@ -368,8 +461,14 @@ export function executeDocumentRead(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentReadInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_read", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -396,10 +495,11 @@ export function executeDocumentList(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
-  const query =
-    typeof input.query === "string" && input.query.trim().length > 0
-      ? input.query.trim()
-      : undefined;
+  const parsedInput = documentListInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_list", parsedInput.error);
+  }
+  const query = parsedInput.data.query?.trim() || undefined;
   const docs = query
     ? searchDocumentsByTitle(
         query,
@@ -427,8 +527,14 @@ export function executeDocumentDelete(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentDeleteInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_delete", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  if (typeof surfaceIdOrError !== "string") {
+    return surfaceIdOrError;
+  }
   const surfaceId = surfaceIdOrError;
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -452,12 +558,18 @@ export function executeDocumentFind(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentFindInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_find", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  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;
+  const query = parsedInput.data.query;
+  const regex = parsedInput.data.regex ?? false;
+  const caseSensitive = parsedInput.data.case_sensitive ?? false;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);
@@ -505,14 +617,20 @@ export function executeDocumentReplaceText(
   input: Record<string, unknown>,
   context: ToolContext,
 ): ToolExecutionResult {
+  const parsedInput = documentReplaceTextInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("document_replace_text", parsedInput.error);
+  }
   const surfaceIdOrError = validateSurfaceId(input);
-  if (typeof surfaceIdOrError !== "string") return surfaceIdOrError;
+  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;
-  const caseSensitive = (input.case_sensitive as boolean | undefined) ?? false;
-  const maxReplacements = input.max_replacements as number | undefined;
+  const find = parsedInput.data.find;
+  const replace = parsedInput.data.replace ?? "";
+  const regex = parsedInput.data.regex ?? false;
+  const caseSensitive = parsedInput.data.case_sensitive ?? false;
+  const maxReplacements = parsedInput.data.max_replacements;
 
   if (!canAccessDocument(surfaceId, context)) {
     return documentNotFound(surfaceId);

package/src/tools/executor.ts

@@ -19,6 +19,8 @@ import {
 } from "../workflows/capabilities.js";
 import { getWorkflowRunManager } from "../workflows/run-manager.js";
 import { executeWithTimeout, safeTimeoutMs } from "./execution-timeout.js";
+import { fileEditInputSchema } from "./filesystem/edit.js";
+import { fileWriteInputSchema } from "./filesystem/write.js";
 import { PermissionChecker } from "./permission-checker.js";
 import { getToolOwner } from "./registry.js";
 import { extractAndSanitize } from "./sensitive-output-placeholders.js";
@@ -99,6 +101,13 @@ export class ToolExecutor {
     }
 
     const tool = gateResult.tool;
+    // The pre-execution gate parsed model-generated input against the tool's
+    // registered Zod schema (`TOOL_INPUT_SCHEMAS`) before any grant was
+    // consumed; substitute the parsed value (with `.catch()` recoveries
+    // applied) so validation and execution see the same input.
+    if (gateResult.parsedInput) {
+      input = gateResult.parsedInput;
+    }
 
     try {
       // A workflow run whose capability manifest grants side-effecting tools or
@@ -469,6 +478,11 @@ export function computePerToolTimeoutMs(
 /**
  * Compute a preview diff for file tools so the confirmation prompt can show
  * what will change. Returns undefined for non-file tools or on any error.
+ * Out-of-workspace targets deliberately produce no preview (strict
+ * sandboxPolicy): the preview runs before the user answers the prompt, and
+ * external file content must not be read — let alone shipped in the
+ * confirmation payload — ahead of approval. Host file tools have no preview
+ * for the same reason.
  */
 function computePreviewDiff(
   toolName: string,
@@ -484,11 +498,13 @@ function computePreviewDiff(
   | undefined {
   try {
     if (toolName === "file_write") {
-      const rawPath = input.path as string;
-      const content = input.content as string;
-      if (!rawPath || typeof content !== "string") {
+      // Parse with the tool's own schema so the preview reads the same shape
+      // the executor will (a call the schema rejects gets no preview).
+      const parsed = fileWriteInputSchema.safeParse(input);
+      if (!parsed.success) {
         return undefined;
       }
+      const { path: rawPath, content } = parsed.data;
       const pathCheck = sandboxPolicy(rawPath, workingDir, {
         mustExist: false,
       });
@@ -508,17 +524,15 @@ function computePreviewDiff(
     }
 
     if (toolName === "file_edit") {
-      const rawPath = input.path as string;
-      const oldString = input.old_string as string;
-      const newString = input.new_string as string;
-      if (
-        !rawPath ||
-        typeof oldString !== "string" ||
-        typeof newString !== "string" ||
-        oldString.length === 0
-      ) {
+      const parsed = fileEditInputSchema.safeParse(input);
+      if (!parsed.success) {
         return undefined;
       }
+      const {
+        path: rawPath,
+        old_string: oldString,
+        new_string: newString,
+      } = parsed.data;
       const pathCheck = sandboxPolicy(rawPath, workingDir);
       if (!pathCheck.ok) {
         return undefined;
@@ -532,7 +546,7 @@ function computePreviewDiff(
         return undefined;
       }
       const content = readFileSync(filePath, "utf-8");
-      const replaceAll = input.replace_all === true;
+      const replaceAll = parsed.data.replace_all === true;
       const result = applyEdit(content, oldString, newString, replaceAll);
       if (!result.ok) {
         return undefined;

package/src/tools/filesystem/edit.ts

@@ -1,13 +1,54 @@
+import { z } from "zod";
+
 import { RiskLevel } from "../../permissions/types.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 { sandboxPolicyWithHostFallback } from "../shared/filesystem/path-policy.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type {
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `replace_all`
+ * catches to `undefined` because the tool has always treated anything but a
+ * literal `true` as "single match" — a malformed value degrades the same way
+ * instead of failing the call.
+ */
+export const fileEditInputSchema = z.looseObject({
+  path: z
+    .string()
+    .min(1)
+    .describe(
+      "The path to the file to edit (absolute or relative to working directory)",
+    ),
+  old_string: z
+    .string()
+    .min(1, { message: "old_string must not be empty" })
+    .describe("The exact text to find in the file"),
+  new_string: z.string().describe("The replacement text"),
+  replace_all: z
+    .boolean()
+    .describe(
+      "Replace all occurrences of old_string instead of requiring a unique match (default: false)",
+    )
+    .optional()
+    .catch(undefined),
+  activity: z
+    .string()
+    .describe(
+      "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const fileEditTool = {
   name: "file_edit",
   description:
@@ -16,67 +57,23 @@ export const fileEditTool = {
   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"],
-  },
+  input_schema: toToolInputSchema(fileEditInputSchema, {
+    advertiseRequired: ["activity"],
+  }),
 
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const rawPath = input.path as string;
-    if (!rawPath || typeof rawPath !== "string") {
-      return {
-        content: "Error: path is required and must be a string",
-        isError: true,
-      };
-    }
-
-    const oldString = input.old_string;
-    if (typeof oldString !== "string") {
-      return {
-        content: "Error: old_string is required and must be a string",
-        isError: true,
-      };
-    }
-
-    const newString = input.new_string;
-    if (typeof newString !== "string") {
-      return {
-        content: "Error: new_string is required and must be a string",
-        isError: true,
-      };
-    }
-
-    if (oldString.length === 0) {
-      return { content: "Error: old_string must not be empty", isError: true };
+    const parsed = fileEditInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("file_edit", parsed.error);
     }
+    const {
+      path: rawPath,
+      old_string: oldString,
+      new_string: newString,
+    } = parsed.data;
 
     if (oldString === newString) {
       return {
@@ -85,10 +82,10 @@ export const fileEditTool = {
       };
     }
 
-    const replaceAll = input.replace_all === true;
+    const replaceAll = parsed.data.replace_all === true;
 
     const ops = new FileSystemOps((path, opts) =>
-      sandboxPolicy(path, context.workingDir, opts),
+      sandboxPolicyWithHostFallback(path, context.workingDir, opts),
     );
 
     const result = ops.editFileSafe({
@@ -116,8 +113,13 @@ export const fileEditTool = {
             content: `Error editing file: ${error.message}`,
             isError: true,
           };
-        default:
-          return { content: `Error: ${error.message}`, isError: true };
+        default: {
+          const hint =
+            error.code === "PATH_OUT_OF_BOUNDS"
+              ? ". To edit files outside the workspace, use the host_file_edit tool instead."
+              : "";
+          return { content: `Error: ${error.message}${hint}`, isError: true };
+        }
       }
     }
 

package/src/tools/filesystem/list.ts

@@ -1,12 +1,40 @@
+import { z } from "zod";
+
 import { RiskLevel } from "../../permissions/types.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type {
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `glob`
+ * catches to `undefined` because the tool has always ignored non-string
+ * values rather than failing the listing.
+ */
+export const fileListInputSchema = z.looseObject({
+  path: z.string().min(1).describe("The directory path to list"),
+  glob: z
+    .string()
+    .describe("Filter entries by glob pattern, e.g. '*.md'")
+    .optional()
+    .catch(undefined),
+  activity: z
+    .string()
+    .describe(
+      "Brief non-technical explanation of what you are doing and why, shown as a status update.",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const fileListTool = {
   name: "file_list",
   description:
@@ -15,46 +43,25 @@ export const fileListTool = {
   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: toToolInputSchema(fileListInputSchema, {
+    advertiseRequired: ["activity"],
+  }),
 
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const rawPath = input.path as string;
-    if (!rawPath || typeof rawPath !== "string") {
-      return {
-        content: "Error: path is required and must be a string",
-        isError: true,
-      };
+    const parsed = fileListInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("file_list", parsed.error);
     }
+    const { path: rawPath, glob } = parsed.data;
 
     const ops = new FileSystemOps((path, opts) =>
       sandboxPolicy(path, context.workingDir, opts),
     );
 
-    const result = ops.listDirSafe({
-      path: rawPath,
-      glob: typeof input.glob === "string" ? input.glob : undefined,
-    });
+    const result = ops.listDirSafe({ path: rawPath, glob });
 
     if (!result.ok) {
       const { error } = result;