@vellumai/assistant 0.10.12 → 0.11.0-staging.1

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;

package/src/tools/followups/followup_create.ts

@@ -1,8 +1,30 @@
+import { z } from "zod";
+
 import { getContact } from "../../contacts/contact-store.js";
 import { createFollowUp } from "../../followups/followup-store.js";
 import type { FollowUp } from "../../followups/types.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeFollowupCreate}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools — see the schema block in `tools/document/document-tool.ts` for the
+ * framework. The bespoke non-empty (trim) checks keep their current error
+ * semantics; `expected_response_hours` is deliberately UNDECLARED (loose
+ * passthrough) so its bespoke positive-number check owns the error message
+ * for every malformed shape.
+ */
+export const followupCreateInputSchema = z.looseObject({
+  channel: nullAsOmitted(z.string()),
+  conversation_id: nullAsOmitted(z.string()),
+  contact_id: nullAsOmitted(z.string()),
+  reminder_schedule_id: nullAsOmitted(z.string()),
+});
+
 function formatFollowUp(f: FollowUp): string {
   const lines = [
     `Follow-up ${f.id}`,
@@ -11,14 +33,17 @@ function formatFollowUp(f: FollowUp): string {
     `  Status: ${f.status}`,
     `  Sent at: ${new Date(f.sentAt).toISOString()}`,
   ];
-  if (f.contactId) lines.push(`  Contact ID: ${f.contactId}`);
+  if (f.contactId) {
+    lines.push(`  Contact ID: ${f.contactId}`);
+  }
   if (f.expectedResponseBy) {
     lines.push(
       `  Expected response by: ${new Date(f.expectedResponseBy).toISOString()}`,
     );
   }
-  if (f.reminderScheduleId)
+  if (f.reminderScheduleId) {
     lines.push(`  Reminder schedule: ${f.reminderScheduleId}`);
+  }
   return lines.join("\n");
 }
 
@@ -26,20 +51,22 @@ export async function executeFollowupCreate(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const channel = input.channel as string | undefined;
-  if (!channel || typeof channel !== "string" || channel.trim().length === 0) {
+  const parsedInput = followupCreateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("followup_create", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+
+  const channel = parsed.channel;
+  if (!channel || channel.trim().length === 0) {
     return {
       content: "Error: channel is required and must be a non-empty string",
       isError: true,
     };
   }
 
-  const conversationId = input.conversation_id as string | undefined;
-  if (
-    !conversationId ||
-    typeof conversationId !== "string" ||
-    conversationId.trim().length === 0
-  ) {
+  const conversationId = parsed.conversation_id;
+  if (!conversationId || conversationId.trim().length === 0) {
     return {
       content:
         "Error: conversation_id is required and must be a non-empty string",
@@ -47,11 +74,13 @@ export async function executeFollowupCreate(
     };
   }
 
-  const contactId = input.contact_id as string | undefined;
+  const contactId = parsed.contact_id;
+  // Loose passthrough (see schema doc comment) — the bespoke check below
+  // owns every malformed shape.
   const expectedResponseHours = input.expected_response_hours as
     | number
     | undefined;
-  const reminderScheduleId = input.reminder_schedule_id as string | undefined;
+  const reminderScheduleId = parsed.reminder_schedule_id;
 
   // Validate contact exists if provided
   if (contactId) {

package/src/tools/followups/followup_list.ts

@@ -1,12 +1,30 @@
+import { z } from "zod";
+
 import {
   getOverdueFollowUps,
   listFollowUps,
 } from "../../followups/followup-store.js";
 import type { FollowUp, FollowUpStatus } from "../../followups/types.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 const VALID_STATUSES = ["pending", "resolved", "overdue", "nudged"] as const;
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeFollowupList}.
+ * Same in-tool pattern and TOOLS.json drift guard as the other bundled-skill
+ * tools. `status` is deliberately UNDECLARED (loose passthrough): the bespoke
+ * `VALID_STATUSES` check owns the "Invalid status" error (test-asserted).
+ */
+export const followupListInputSchema = z.looseObject({
+  channel: nullAsOmitted(z.string()),
+  contact_id: nullAsOmitted(z.string()),
+  overdue_only: nullAsOmitted(z.boolean()),
+});
+
 function formatFollowUpSummary(f: FollowUp): string {
   const parts = [
     `- **${f.channel}** conversation:${f.conversationId} (ID: ${f.id})`,
@@ -14,7 +32,9 @@ function formatFollowUpSummary(f: FollowUp): string {
   parts.push(
     `  Status: ${f.status} | Sent: ${new Date(f.sentAt).toISOString()}`,
   );
-  if (f.contactId) parts.push(`  Contact: ${f.contactId}`);
+  if (f.contactId) {
+    parts.push(`  Contact: ${f.contactId}`);
+  }
   if (f.expectedResponseBy) {
     const deadline = new Date(f.expectedResponseBy);
     const isOverdue = f.status === "pending" && deadline.getTime() < Date.now();
@@ -29,10 +49,14 @@ export async function executeFollowupList(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  const parsedInput = followupListInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("followup_list", parsedInput.error);
+  }
   const status = input.status as FollowUpStatus | undefined;
-  const channel = input.channel as string | undefined;
-  const contactId = input.contact_id as string | undefined;
-  const overdueOnly = input.overdue_only as boolean | undefined;
+  const channel = parsedInput.data.channel;
+  const contactId = parsedInput.data.contact_id;
+  const overdueOnly = parsedInput.data.overdue_only;
 
   if (
     status &&
@@ -51,8 +75,12 @@ export async function executeFollowupList(
 
     if (overdueOnly || status === "overdue") {
       results = getOverdueFollowUps();
-      if (channel) results = results.filter((f) => f.channel === channel);
-      if (contactId) results = results.filter((f) => f.contactId === contactId);
+      if (channel) {
+        results = results.filter((f) => f.channel === channel);
+      }
+      if (contactId) {
+        results = results.filter((f) => f.contactId === contactId);
+      }
     } else {
       results = listFollowUps({ status, channel, contactId });
     }

package/src/tools/followups/followup_resolve.ts

@@ -1,10 +1,28 @@
+import { z } from "zod";
+
 import {
   resolveByConversation,
   resolveFollowUp,
 } from "../../followups/followup-store.js";
 import type { FollowUp } from "../../followups/types.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
+/**
+ * Model-input schema, `safeParse`d at the top of
+ * {@link executeFollowupResolve}. Same in-tool pattern and TOOLS.json drift
+ * guard as the other bundled-skill tools. The bespoke either-or check below
+ * keeps its error message.
+ */
+export const followupResolveInputSchema = z.looseObject({
+  id: nullAsOmitted(z.string()),
+  channel: nullAsOmitted(z.string()),
+  conversation_id: nullAsOmitted(z.string()),
+});
+
 function formatFollowUp(f: FollowUp): string {
   const lines = [
     `Follow-up ${f.id}`,
@@ -12,7 +30,9 @@ function formatFollowUp(f: FollowUp): string {
     `  Conversation: ${f.conversationId}`,
     `  Status: ${f.status}`,
   ];
-  if (f.contactId) lines.push(`  Contact ID: ${f.contactId}`);
+  if (f.contactId) {
+    lines.push(`  Contact ID: ${f.contactId}`);
+  }
   return lines.join("\n");
 }
 
@@ -20,9 +40,11 @@ export async function executeFollowupResolve(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const id = input.id as string | undefined;
-  const channel = input.channel as string | undefined;
-  const conversationId = input.conversation_id as string | undefined;
+  const parsedInput = followupResolveInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("followup_resolve", parsedInput.error);
+  }
+  const { id, channel, conversation_id: conversationId } = parsedInput.data;
 
   if (!id && !(channel && conversationId)) {
     return {

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

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
@@ -5,12 +7,46 @@ 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";
 import { hostPolicy } 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 — mirrors
+ * `filesystem/edit.ts`. `replace_all` catches to `undefined` — anything
+ * but a literal `true` means "single match"; `target_client_id` catches so
+ * a non-string (or empty) value means "untargeted".
+ */
+export const hostFileEditInputSchema = z.looseObject({
+  path: z.string().min(1).describe("Absolute host path to the file to edit"),
+  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 instead of requiring a unique match (default: false)",
+    )
+    .optional()
+    .catch(undefined),
+  target_client_id: z
+    .string()
+    .describe(
+      "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const hostFileEditTool = {
   name: "host_file_edit",
   description:
@@ -19,66 +55,21 @@ export const hostFileEditTool = {
   executionTarget: "host",
   defaultRiskLevel: RiskLevel.Medium,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      path: {
-        type: "string",
-        description: "Absolute host path to the file to edit",
-      },
-      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 instead of requiring a unique match (default: false)",
-      },
-      target_client_id: {
-        type: "string",
-        description:
-          "ID of the specific client to execute this on. Required when multiple clients support host_file; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_file`.",
-      },
-    },
-    required: ["path", "old_string", "new_string"],
-  },
+  input_schema: toToolInputSchema(hostFileEditInputSchema),
 
   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 = hostFileEditInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("host_file_edit", parsed.error);
     }
+    const {
+      path: rawPath,
+      old_string: oldString,
+      new_string: newString,
+    } = parsed.data;
 
     if (oldString === newString) {
       return {
@@ -87,12 +78,11 @@ export const hostFileEditTool = {
       };
     }
 
-    const replaceAll = input.replace_all === true;
+    const replaceAll = parsed.data.replace_all === true;
 
     const targetClientId =
-      typeof input.target_client_id === "string" &&
-      input.target_client_id !== ""
-        ? input.target_client_id
+      parsed.data.target_client_id !== ""
+        ? parsed.data.target_client_id
         : undefined;
 
     const transportInterface = context.transportInterface;
@@ -154,8 +144,8 @@ export const hostFileEditTool = {
         {
           operation: "edit",
           path: rawPath,
-          old_string: oldString as string,
-          new_string: newString as string,
+          old_string: oldString,
+          new_string: newString,
           replace_all: replaceAll,
           targetClientId,
         },