@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/tools/shared/zod-tool-schema.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+
+import type { ToolExecutionResult } from "../types.js";
+
+/**
+ * Derive a tool's LLM-facing `input_schema` from its Zod input schema, so the
+ * schema the model sees and the validation the executor runs share one source
+ * and cannot drift (`TOOL_INPUT_SCHEMAS` in `../tool-input-schemas.ts` holds
+ * the executor-side half).
+ *
+ * Conversion uses Zod 4's native `z.toJSONSchema` (mirroring
+ * `workflows/leaf-runner.ts`), then adjusts the output for the tool-definition
+ * context:
+ *
+ * - The `$schema` marker is dropped — tool definitions don't carry one.
+ * - `additionalProperties` values of `false` / `{}` are dropped. They are
+ *   authoring artifacts of `z.object` / `z.looseObject`, not intentional
+ *   contract: runtime validation never rejects unknown keys (registry schemas
+ *   must tolerate injected fields like `activity`, see
+ *   `schema-transforms.ts`), so advertising `additionalProperties: false`
+ *   would claim a strictness the runtime doesn't enforce.
+ *
+ * `advertiseRequired` names fields to mark required in the advertised schema
+ * even though the Zod schema treats them as optional. This is the one
+ * sanctioned divergence, and only in the tolerant direction: the model is told
+ * to always send the field (e.g. `activity`, which drives status UX), but a
+ * call that omits it still executes rather than failing on a field the tool
+ * doesn't need.
+ */
+export function toToolInputSchema(
+  schema: z.ZodType,
+  opts?: { advertiseRequired?: readonly string[] },
+): Record<string, unknown> {
+  const json = z.toJSONSchema(schema, { unrepresentable: "any" }) as Record<
+    string,
+    unknown
+  >;
+  delete json.$schema;
+  stripPermissiveAdditionalProperties(json);
+
+  for (const field of opts?.advertiseRequired ?? []) {
+    const required = Array.isArray(json.required) ? json.required : [];
+    if (!required.includes(field)) {
+      json.required = [...required, field];
+    }
+  }
+  return json;
+}
+
+/**
+ * Recursively remove `additionalProperties` keys whose value is `false` or the
+ * empty schema `{}`. A real subschema (e.g. `additionalProperties:
+ * { type: "string" }` from `z.record`) is left intact.
+ */
+function stripPermissiveAdditionalProperties(node: unknown): void {
+  if (Array.isArray(node)) {
+    for (const entry of node) {
+      stripPermissiveAdditionalProperties(entry);
+    }
+    return;
+  }
+  if (node === null || typeof node !== "object") {
+    return;
+  }
+  const record = node as Record<string, unknown>;
+  const ap = record.additionalProperties;
+  if (
+    ap === false ||
+    (typeof ap === "object" &&
+      ap !== null &&
+      !Array.isArray(ap) &&
+      Object.keys(ap).length === 0)
+  ) {
+    delete record.additionalProperties;
+  }
+  for (const value of Object.values(record)) {
+    stripPermissiveAdditionalProperties(value);
+  }
+}
+
+/**
+ * Wrap an optional field's schema so an explicit `null` parses as "omitted"
+ * (`undefined`). Models routinely send `null` for optional fields they mean
+ * to skip, and executors read such fields via `input.x ?? fallback`, where
+ * null and absent are equivalent — validation must not reject null there.
+ * The derived JSON Schema is the inner schema's (the null-tolerance is
+ * runtime slack, not advertised contract).
+ */
+export function nullAsOmitted<T extends z.ZodType>(schema: T) {
+  return z.preprocess((value) => value ?? undefined, schema.optional());
+}
+
+/**
+ * Render a failed tool-input parse as a compact `field: message` summary the
+ * model can correct from. Mirrors `runtime/routes/parse-body.ts`.
+ */
+export function formatToolInputError(
+  toolName: string,
+  error: z.ZodError,
+): string {
+  const detail = error.issues
+    .map((issue) => `${issue.path.join(".") || "(input)"}: ${issue.message}`)
+    .join("; ");
+  return `Invalid input for tool "${toolName}": ${detail}. Fix the listed field(s) and retry the call.`;
+}
+
+/**
+ * Failed-parse tool result for executors that validate their own input (the
+ * pre-execution gate in `ToolApprovalHandler` produces the same message, so
+ * the error reads identically whichever layer catches it first).
+ */
+export function invalidToolInputResult(
+  toolName: string,
+  error: z.ZodError,
+): ToolExecutionResult {
+  return { content: formatToolInputError(toolName, error), isError: true };
+}

package/src/tools/subagent/abort.ts

@@ -1,15 +1,23 @@
 import { getSubagentManager } from "../../subagent/index.js";
+import { invalidToolInputResult } from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
-import { resolveSubagentId } from "./resolve.js";
+import { resolveSubagentId, subagentRefInputSchema } from "./resolve.js";
+
+export const subagentAbortInputSchema = subagentRefInputSchema;
 
 export async function executeSubagentAbort(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const subagentId = resolveSubagentId(input, context);
-  if (!subagentId && input.label) {
+  const parsedInput = subagentAbortInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("subagent_abort", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+  const subagentId = resolveSubagentId(parsed, context);
+  if (!subagentId && parsed.label) {
     return {
-      content: `No subagent found with label "${input.label as string}".`,
+      content: `No subagent found with label "${parsed.label}".`,
       isError: true,
     };
   }

package/src/tools/subagent/consult-deadline.ts

@@ -29,8 +29,12 @@ export function createConsultDeadline(opts: {
 
   const recordProgress = (): void => {
     // Once aborted, don't re-arm — the consult is already being torn down.
-    if (controller.signal.aborted) return;
-    if (idleTimer) clearTimeout(idleTimer);
+    if (controller.signal.aborted) {
+      return;
+    }
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+    }
     idleTimer = setTimeout(() => controller.abort(), opts.idleMs);
   };
 
@@ -41,7 +45,9 @@ export function createConsultDeadline(opts: {
   recordProgress();
 
   const dispose = (): void => {
-    if (idleTimer) clearTimeout(idleTimer);
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+    }
     clearTimeout(maxTimer);
   };
 

package/src/tools/subagent/message.ts

@@ -1,17 +1,33 @@
+import { z } from "zod";
+
 import { getSubagentManager } from "../../subagent/index.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
-import { resolveSubagentId } from "./resolve.js";
+import { resolveSubagentId, subagentRefInputSchema } from "./resolve.js";
+
+export const subagentMessageInputSchema = z.looseObject({
+  ...subagentRefInputSchema.shape,
+  content: nullAsOmitted(z.string()),
+});
 
 export async function executeSubagentMessage(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const subagentId = resolveSubagentId(input, context);
-  const content = input.content as string;
+  const parsedInput = subagentMessageInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("subagent_message", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+  const subagentId = resolveSubagentId(parsed, context);
+  const content = parsed.content;
 
-  if (!subagentId && input.label) {
+  if (!subagentId && parsed.label) {
     return {
-      content: `No subagent found with label "${input.label as string}".`,
+      content: `No subagent found with label "${parsed.label}".`,
       isError: true,
     };
   }

package/src/tools/subagent/notify-parent.ts

@@ -1,17 +1,56 @@
+import { z } from "zod";
+
 import { RiskLevel } from "../../permissions/types.js";
 import { notifyParentFromChild } from "../../subagent/notify.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+  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. `message`
+ * stays runtime-optional (`advertiseRequired`) so the bespoke
+ * '"message" is required.' check keeps its test-asserted error; `urgency`
+ * catches to `undefined` so a malformed value degrades to "info" instead of
+ * forwarding garbage to the parent's notification.
+ */
+export const notifyParentInputSchema = z.looseObject({
+  message: nullAsOmitted(
+    z.string().describe("The notification content for the parent."),
+  ),
+  urgency: z
+    .enum(["info", "important", "blocked"])
+    .describe(
+      "'info' for progress updates, 'important' for key findings, 'blocked' when you need guidance.",
+    )
+    .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 async function executeSubagentNotifyParent(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const message = input.message as string;
-  const urgency = (input.urgency as string) || "info";
+  const parsed = notifyParentInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return invalidToolInputResult("notify_parent", parsed.error);
+  }
+  const message = parsed.data.message;
+  const urgency = parsed.data.urgency ?? "info";
 
   if (!message) {
     return { content: '"message" is required.', isError: true };
@@ -41,27 +80,9 @@ export const notifyParentTool = {
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      message: {
-        type: "string",
-        description: "The notification content for the parent.",
-      },
-      urgency: {
-        type: "string",
-        enum: ["info", "important", "blocked"],
-        description:
-          "'info' for progress updates, 'important' for key findings, 'blocked' when you need guidance.",
-      },
-      activity: {
-        type: "string",
-        description:
-          "Brief non-technical explanation of what you are doing and why, shown as a status update.",
-      },
-    },
-    required: ["message", "activity"],
-  },
+  input_schema: toToolInputSchema(notifyParentInputSchema, {
+    advertiseRequired: ["message", "activity"],
+  }),
 
   async execute(
     input: Record<string, unknown>,

package/src/tools/subagent/read.ts

@@ -1,17 +1,28 @@
 import { getMessages } from "../../persistence/conversation-crud.js";
 import { extractTextFromStoredMessageContent } from "../../persistence/message-content.js";
 import { getSubagentManager, TERMINAL_STATUSES } from "../../subagent/index.js";
+import { invalidToolInputResult } from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
-import { resolveSubagentId } from "./resolve.js";
+import { resolveSubagentId, subagentRefInputSchema } from "./resolve.js";
+
+// `last_n` is deliberately UNDECLARED (loose passthrough): the executor's
+// typeof-guarded read below ignores it when malformed — including non-integer
+// numbers the advertised `integer` type wouldn't admit.
+export const subagentReadInputSchema = subagentRefInputSchema;
 
 export async function executeSubagentRead(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const subagentId = resolveSubagentId(input, context);
-  if (!subagentId && input.label) {
+  const parsedInput = subagentReadInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("subagent_read", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+  const subagentId = resolveSubagentId(parsed, context);
+  if (!subagentId && parsed.label) {
     return {
-      content: `No subagent found with label "${input.label as string}".`,
+      content: `No subagent found with label "${parsed.label}".`,
       isError: true,
     };
   }

package/src/tools/subagent/resolve.ts

@@ -1,18 +1,40 @@
+import { z } from "zod";
+
 import { getSubagentManager } from "../../subagent/index.js";
+import { nullAsOmitted } from "../shared/zod-tool-schema.js";
 import type { ToolContext } from "../types.js";
 
 /**
- * Resolve a subagent ID from tool input.
+ * Shared model-input schema for the subagent tools that address an existing
+ * subagent by `subagent_id` or `label` (`subagent_status` / `subagent_abort`,
+ * extended by `subagent_message` / `subagent_read`). Same in-tool pattern and
+ * TOOLS.json drift guard as the other bundled-skill tools — see
+ * `subagent-tool-input-schemas.test.ts` and the schema block in
+ * `tools/document/document-tool.ts` for the framework. The
+ * '"subagent_id" or "label" is required' / not-found error messages stay
+ * bespoke in each executor.
+ */
+export const subagentRefInputSchema = z.looseObject({
+  subagent_id: nullAsOmitted(z.string()),
+  label: nullAsOmitted(z.string()),
+});
+
+export type SubagentRefInput = z.infer<typeof subagentRefInputSchema>;
+
+/**
+ * Resolve a subagent ID from parsed tool input.
  * Accepts either `subagent_id` (direct UUID) or `label` (case-insensitive lookup).
  */
 export function resolveSubagentId(
-  input: Record<string, unknown>,
+  input: SubagentRefInput,
   context: ToolContext,
 ): string | undefined {
-  if (input.subagent_id) return input.subagent_id as string;
+  if (input.subagent_id) {
+    return input.subagent_id;
+  }
   if (input.label) {
     const state = getSubagentManager().getByLabel(
-      input.label as string,
+      input.label,
       context.conversationId,
     );
     return state?.config.id;

package/src/tools/subagent/spawn.ts

@@ -1,8 +1,10 @@
+import { z } from "zod";
+
+import type { AssistantEvent } from "../../api/index.js";
 import { validateInferenceProfileKey } from "../../config/inference-profile-validation.js";
 import { resolveDefaultProfileKey } from "../../config/llm-resolver.js";
 import { getConfig } from "../../config/loader.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
-import type { ServerMessage } from "../../daemon/message-protocol.js";
 import {
   getConversationOverrideProfile,
   getMessages,
@@ -19,6 +21,10 @@ import {
 } from "../../subagent/index.js";
 import type { SubagentRole } from "../../subagent/types.js";
 import { getLogger } from "../../util/logger.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 import { createConsultDeadline } from "./consult-deadline.js";
 
@@ -42,16 +48,40 @@ const ADVISOR_IDLE_TIMEOUT_MS = 60_000;
  */
 const ADVISOR_MAX_TIMEOUT_MS = 300_000;
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeSubagentSpawn}.
+ * 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.
+ *
+ * `fork` / `send_result_to_user` (deliberate `=== true` / `!== false`
+ * coercions) and `role` (SubagentManager.spawn's "Invalid subagent role"
+ * error, asserted by tests, owns non-enum values) are deliberately
+ * UNDECLARED — loose passthrough.
+ */
+export const subagentSpawnInputSchema = z.looseObject({
+  label: nullAsOmitted(z.string()),
+  objective: nullAsOmitted(z.string()),
+  context: nullAsOmitted(z.string()),
+  inference_profile: z.string().optional(),
+});
+
 export async function executeSubagentSpawn(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const label = input.label as string;
-  const objective = input.objective as string;
-  const extraContext = input.context as string | undefined;
+  const parsedInput = subagentSpawnInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("subagent_spawn", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+
+  const label = parsed.label;
+  const objective = parsed.objective;
+  const extraContext = parsed.context;
   const fork = input.fork === true;
   const role = (input.role as string | undefined) ?? undefined;
-  const inferenceProfile = input.inference_profile;
+  const inferenceProfile = parsed.inference_profile;
 
   // For fork mode, sendResultToUser defaults to false unless explicitly set to true.
   // For regular mode, sendResultToUser defaults to true (existing behavior).
@@ -69,12 +99,6 @@ export async function executeSubagentSpawn(
   let requestedOverrideProfile: string | undefined;
   let forceOverrideProfile = false;
   if (inferenceProfile !== undefined) {
-    if (typeof inferenceProfile !== "string") {
-      return {
-        content: "Error: inference_profile must be a string",
-        isError: true,
-      };
-    }
     const profileError = validateInferenceProfileKey(inferenceProfile);
     if (profileError) {
       return {
@@ -105,7 +129,7 @@ export async function executeSubagentSpawn(
       context,
       label,
       objective,
-      sendToClient: sendToClient as (msg: ServerMessage) => void,
+      sendToClient: sendToClient as (msg: AssistantEvent) => void,
       requestedOverrideProfile,
     });
   }
@@ -238,7 +262,7 @@ async function runAdvisorConsult(args: {
   label: string;
   /** The agent's own `objective` — its framing of what it wants advised on. */
   objective: string;
-  sendToClient: (msg: ServerMessage) => void;
+  sendToClient: (msg: AssistantEvent) => void;
   requestedOverrideProfile: string | undefined;
 }): Promise<ToolExecutionResult> {
   const { context, label, objective, sendToClient, requestedOverrideProfile } =

package/src/tools/subagent/status.ts

@@ -1,19 +1,27 @@
 import { getSubagentManager } from "../../subagent/index.js";
+import { invalidToolInputResult } from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
-import { resolveSubagentId } from "./resolve.js";
+import { resolveSubagentId, subagentRefInputSchema } from "./resolve.js";
+
+export const subagentStatusInputSchema = subagentRefInputSchema;
 
 export async function executeSubagentStatus(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const subagentId = resolveSubagentId(input, context);
+  const parsedInput = subagentStatusInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("subagent_status", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+  const subagentId = resolveSubagentId(parsed, context);
   const manager = getSubagentManager();
 
   // If a label was provided but didn't resolve, that's an error — don't fall
   // through to the "list all" path.
-  if (!subagentId && input.label) {
+  if (!subagentId && parsed.label) {
     return {
-      content: `No subagent found with label "${input.label as string}".`,
+      content: `No subagent found with label "${parsed.label}".`,
       isError: true,
     };
   }

package/src/tools/system/request-permission.ts

@@ -1,4 +1,10 @@
+import { z } from "zod";
+
 import { RiskLevel } from "../../permissions/types.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -52,6 +58,26 @@ const FRIENDLY_NAMES: Record<PermissionType, string> = {
   camera: "Camera",
 };
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `activity`
+ * is advertised-required purely to guide the model (it is shown in the
+ * prompt UI, never read here), so it stays runtime-optional via
+ * `advertiseRequired`.
+ */
+export const requestSystemPermissionInputSchema = z.looseObject({
+  permission_type: z
+    .enum(PERMISSION_TYPES)
+    .describe("The macOS system permission to request"),
+  activity: z
+    .string()
+    .describe(
+      "Short explanation of why this permission is needed (shown in the prompt)",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const requestSystemPermissionTool = {
   name: "request_system_permission",
   description:
@@ -62,39 +88,22 @@ export const requestSystemPermissionTool = {
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.High,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      permission_type: {
-        type: "string",
-        enum: [...PERMISSION_TYPES],
-        description: "The macOS system permission to request",
-      },
-      activity: {
-        type: "string",
-        description:
-          "Short explanation of why this permission is needed (shown in the prompt)",
-      },
-    },
-    required: ["permission_type", "activity"],
-  },
+  input_schema: toToolInputSchema(requestSystemPermissionInputSchema, {
+    advertiseRequired: ["activity"],
+  }),
 
   async execute(
     input: Record<string, unknown>,
     _context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const permType = input.permission_type as string;
-    if (!PERMISSION_TYPES.includes(permType as PermissionType)) {
-      return {
-        content: `Error: unknown permission type "${permType}". Valid types: ${PERMISSION_TYPES.join(
-          ", ",
-        )}`,
-        isError: true,
-      };
+    const parsed = requestSystemPermissionInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("request_system_permission", parsed.error);
     }
+    const permType = parsed.data.permission_type;
 
-    const friendly = FRIENDLY_NAMES[permType as PermissionType];
-    const settingsUrl = SETTINGS_URLS[permType as PermissionType];
+    const friendly = FRIENDLY_NAMES[permType];
+    const settingsUrl = SETTINGS_URLS[permType];
 
     return {
       content: [