@vellumai/assistant 0.10.12 → 0.11.0-staging.2

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;

package/src/tools/filesystem/read.ts

@@ -1,5 +1,7 @@
 import { extname } from "node:path";
 
+import { z } from "zod";
+
 import { RiskLevel } from "../../permissions/types.js";
 import {
   AUDIO_EXTENSIONS,
@@ -10,13 +12,49 @@ import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.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. `offset` and
+ * `limit` catch to `undefined` because the tool has always ignored non-numeric
+ * values rather than failing the read.
+ */
+export const fileReadInputSchema = z.looseObject({
+  path: z
+    .string()
+    .min(1)
+    .describe(
+      "The path to the file to read (absolute or relative to working directory)",
+    ),
+  offset: z
+    .number()
+    .describe("Line number to start reading from (1-indexed)")
+    .optional()
+    .catch(undefined),
+  limit: z
+    .number()
+    .describe("Maximum number of lines to read")
+    .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 fileReadTool = {
   name: "file_read",
   description:
@@ -25,47 +63,27 @@ export const fileReadTool = {
   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: toToolInputSchema(fileReadInputSchema, {
+    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 = fileReadInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("file_read", parsed.error);
     }
+    const { path: rawPath, offset, limit } = parsed.data;
 
     // For image files, delegate to the shared image reader.
     const ext = extname(rawPath).toLowerCase();
     if (IMAGE_EXTENSIONS.has(ext)) {
-      const pathCheck = sandboxPolicy(rawPath, context.workingDir);
+      const pathCheck = sandboxPolicyWithHostFallback(
+        rawPath,
+        context.workingDir,
+      );
       if (!pathCheck.ok) {
         return {
           content: `Error: ${pathCheck.error}. To read files outside the workspace, use the host_file_read tool instead.`,
@@ -77,7 +95,10 @@ export const fileReadTool = {
 
     // For audio files, delegate to the shared audio reader.
     if (AUDIO_EXTENSIONS.has(ext)) {
-      const pathCheck = sandboxPolicy(rawPath, context.workingDir);
+      const pathCheck = sandboxPolicyWithHostFallback(
+        rawPath,
+        context.workingDir,
+      );
       if (!pathCheck.ok) {
         return {
           content: `Error: ${pathCheck.error}. To read files outside the workspace, use the host_file_read tool instead.`,
@@ -88,14 +109,10 @@ export const fileReadTool = {
     }
 
     const ops = new FileSystemOps((path, opts) =>
-      sandboxPolicy(path, context.workingDir, opts),
+      sandboxPolicyWithHostFallback(path, context.workingDir, opts),
     );
 
-    const result = ops.readFileSafe({
-      path: rawPath,
-      offset: typeof input.offset === "number" ? input.offset : undefined,
-      limit: typeof input.limit === "number" ? input.limit : undefined,
-    });
+    const result = ops.readFileSafe({ path: rawPath, offset, limit });
 
     if (!result.ok) {
       const { error } = result;

package/src/tools/filesystem/write.ts

@@ -1,13 +1,19 @@
 import { join, resolve, sep } from "node:path";
 
+import { z } from "zod";
+
 import { getAppsDir } from "../../apps/app-store.js";
 import { RiskLevel } from "../../permissions/types.js";
-import { enqueuePkbIndexJob } from "../../plugins/defaults/memory/jobs/embed-pkb-file.js";
+import { enqueuePkbIndexJob } from "../../plugins/defaults/memory/v1/jobs/embed-pkb-file.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
-import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
+import { sandboxPolicyWithHostFallback } from "../shared/filesystem/path-policy.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -56,6 +62,29 @@ function isInsidePkbRoot(absPath: string, pkbRoot: string): boolean {
   return normalized.startsWith(rootWithSep);
 }
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. Loose so
+ * injected fields (e.g. `activity`, which the model must send but the tool
+ * never reads) pass through untouched.
+ */
+export const fileWriteInputSchema = z.looseObject({
+  path: z
+    .string()
+    .min(1)
+    .describe(
+      "The path to the file to write (absolute or relative to working directory)",
+    ),
+  content: z.string().describe("The content to write to the file"),
+  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 fileWriteTool = {
   name: "file_write",
   description:
@@ -64,46 +93,19 @@ export const fileWriteTool = {
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      path: {
-        type: "string",
-        description:
-          "The path to the file to write (absolute or relative to working directory)",
-      },
-      content: {
-        type: "string",
-        description: "The content to write to the file",
-      },
-      activity: {
-        type: "string",
-        description:
-          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-      },
-    },
-    required: ["path", "content", "activity"],
-  },
+  input_schema: toToolInputSchema(fileWriteInputSchema, {
+    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 fileContent = input.content;
-    if (typeof fileContent !== "string") {
-      return {
-        content: "Error: content is required and must be a string",
-        isError: true,
-      };
+    const parsed = fileWriteInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("file_write", parsed.error);
     }
+    const { path: rawPath, content: fileContent } = parsed.data;
 
     // Redirect self-contained interactive HTML artifacts to app-builder.
     // Exempt writes that land inside the apps directory (app-builder's own
@@ -116,7 +118,7 @@ export const fileWriteTool = {
     }
 
     const ops = new FileSystemOps((path, opts) =>
-      sandboxPolicy(path, context.workingDir, opts),
+      sandboxPolicyWithHostFallback(path, context.workingDir, opts),
     );
 
     const result = ops.writeFileSafe({ path: rawPath, content: fileContent });
@@ -137,7 +139,11 @@ export const fileWriteTool = {
           isError: true,
         };
       }
-      return { content: `Error: ${error.message}`, isError: true };
+      const hint =
+        error.code === "PATH_OUT_OF_BOUNDS"
+          ? ". To write files outside the workspace, use the host_file_write tool instead."
+          : "";
+      return { content: `Error: ${error.message}${hint}`, isError: true };
     }
 
     const { filePath, oldContent, newContent, isNewFile } = result.value;