@vellumai/assistant 0.10.12 → 0.11.0-staging.1

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: [

package/src/tools/terminal/shell.ts

@@ -1,6 +1,8 @@
 import type { ChildProcess } from "node:child_process";
 import { spawn } from "node:child_process";
 
+import { z } from "zod";
+
 import type { BackgroundToolCompletedEvent } from "../../api/events/background-tool-completed.js";
 import { getConfig } from "../../config/loader.js";
 import { RiskLevel } from "../../permissions/types.js";
@@ -30,6 +32,10 @@ import {
   formatShellOutput,
   MAX_OUTPUT_LENGTH,
 } from "../shared/shell-output.js";
+import {
+  invalidToolInputResult,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import type { ProxyEnvVars } from "../tool-types.js";
 import type {
   ToolContext,
@@ -49,6 +55,55 @@ function buildCredentialRefTrace(
 
 const log = getLogger("shell-tool");
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. Optional
+ * fields catch to `undefined` so a malformed value degrades to its
+ * default: `timeout_seconds` falls back to the configured
+ * default (it is also read defensively pre-execution by
+ * `computePerToolTimeoutMs`), `network_mode` falls back to "off" (the
+ * `=== "proxied"` coercion), `background` to foreground (the `=== true`
+ * coercion), `credential_ids` to none, and `activity` is status-only.
+ */
+export const shellInputSchema = z.looseObject({
+  command: z.string().min(1).describe("The shell command to execute"),
+  activity: z
+    .string()
+    .describe(
+      'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
+    )
+    .optional()
+    .catch(undefined),
+  timeout_seconds: z
+    .number()
+    .describe(
+      "Optional timeout in seconds. Defaults to the configured default (120s). Cannot exceed the configured maximum.",
+    )
+    .optional()
+    .catch(undefined),
+  network_mode: z
+    .enum(["off", "proxied"])
+    .describe(
+      'Network access mode for the command. "off" (default) blocks network access; "proxied" routes traffic through the credential proxy.',
+    )
+    .optional()
+    .catch(undefined),
+  credential_ids: z
+    .array(z.string())
+    .describe(
+      'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
+    )
+    .optional()
+    .catch(undefined),
+  background: z
+    .boolean()
+    .describe(
+      "Run the command in the background. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const shellTool = {
   name: "bash",
   description: "Execute a shell command on the local machine",
@@ -56,55 +111,19 @@ export const shellTool = {
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Medium,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      command: {
-        type: "string",
-        description: "The shell command to execute",
-      },
-      activity: {
-        type: "string",
-        description:
-          'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
-      },
-      timeout_seconds: {
-        type: "number",
-        description:
-          "Optional timeout in seconds. Defaults to the configured default (120s). Cannot exceed the configured maximum.",
-      },
-      network_mode: {
-        type: "string",
-        enum: ["off", "proxied"],
-        description:
-          'Network access mode for the command. "off" (default) blocks network access; "proxied" routes traffic through the credential proxy.',
-      },
-      credential_ids: {
-        type: "array",
-        items: { type: "string" },
-        description:
-          'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
-      },
-      background: {
-        type: "boolean",
-        description:
-          "Run the command in the background. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
-      },
-    },
-    required: ["command", "activity"],
-  },
+  input_schema: toToolInputSchema(shellInputSchema, {
+    advertiseRequired: ["activity"],
+  }),
 
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
-    const command = input.command as string;
-    if (!command || typeof command !== "string") {
-      return {
-        content: "Error: command is required and must be a string",
-        isError: true,
-      };
+    const parsed = shellInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("bash", parsed.error);
     }
+    const command = parsed.data.command;
 
     // Reject commands containing null bytes - they cause truncation at the
     // OS level while the parser sees the full string, enabling bypass.
@@ -112,7 +131,7 @@ export const shellTool = {
       return { content: "Error: command contains null bytes", isError: true };
     }
 
-    const background = input.background === true;
+    const background = parsed.data.background === true;
     if (background && context.diskPressureCleanupModeActive === true) {
       return {
         content:
@@ -123,15 +142,12 @@ export const shellTool = {
 
     const config = getConfig();
 
-    const networkMode: "off" | "proxied" =
-      input.network_mode === "proxied" ? "proxied" : "off";
+    const networkMode: "off" | "proxied" = parsed.data.network_mode ?? "off";
 
     const rawCredentialRefs: string[] = [];
-    if (Array.isArray(input.credential_ids)) {
-      for (const id of input.credential_ids) {
-        if (typeof id === "string" && id.length > 0) {
-          rawCredentialRefs.push(id);
-        }
+    for (const id of parsed.data.credential_ids ?? []) {
+      if (id.length > 0) {
+        rawCredentialRefs.push(id);
       }
     }
 
@@ -222,10 +238,7 @@ export const shellTool = {
     }
 
     const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
-    const requestedSec =
-      typeof input.timeout_seconds === "number"
-        ? input.timeout_seconds
-        : shellDefaultTimeoutSec;
+    const requestedSec = parsed.data.timeout_seconds ?? shellDefaultTimeoutSec;
     const timeoutSec = Math.max(1, Math.min(requestedSec, shellMaxTimeoutSec));
     const timeoutMs = timeoutSec * 1000;