@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/tools/host-terminal/host-shell.ts

@@ -11,6 +11,8 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
 
+import { z } from "zod";
+
 import { supportsHostProxy } from "../../channels/types.js";
 import { getConfig } from "../../config/loader.js";
 import { HostBashProxy } from "../../daemon/host-bash-proxy.js";
@@ -36,6 +38,11 @@ import {
   formatShellOutput,
   MAX_OUTPUT_LENGTH,
 } from "../shared/shell-output.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+  toToolInputSchema,
+} from "../shared/zod-tool-schema.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
 import type {
   ToolContext,
@@ -90,6 +97,56 @@ function buildHostBashProxyEnv(conversationId: string): Record<string, string> {
   return env;
 }
 
+/**
+ * Model-input schema, the single source for both runtime validation (via
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below.
+ * `timeout_seconds` / `background` / `target_client_id` / `activity` catch
+ * to `undefined` so a malformed value degrades to its default (configured
+ * timeout, foreground, untargeted, status-only). `working_dir` treats an
+ * explicit null as omitted (the run defaults to the user home) but does NOT
+ * catch — a malformed working directory fails the parse rather than
+ * silently running in the wrong place, and the null-byte / absolute-path
+ * checks stay bespoke below.
+ */
+export const hostShellInputSchema = z.looseObject({
+  command: z.string().min(1).describe("The host 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),
+  working_dir: nullAsOmitted(
+    z
+      .string()
+      .describe(
+        "Optional absolute host working directory (defaults to user home)",
+      ),
+  ),
+  timeout_seconds: z
+    .number()
+    .describe(
+      "Optional timeout in seconds. Uses configured default and max limits.",
+    )
+    .optional()
+    .catch(undefined),
+  background: z
+    .boolean()
+    .describe(
+      "Run the command in the background on the host machine. 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),
+  target_client_id: z
+    .string()
+    .describe(
+      "ID of the specific client to execute this command on. Required when multiple clients support host_bash; omit when only one client is connected. Obtain IDs from `assistant clients list --capability host_bash`.",
+    )
+    .optional()
+    .catch(undefined),
+});
+
 export const hostShellTool = {
   name: "host_bash",
   description:
@@ -98,64 +155,24 @@ export const hostShellTool = {
   executionTarget: "host",
   defaultRiskLevel: RiskLevel.Medium,
 
-  input_schema: {
-    type: "object",
-    properties: {
-      command: {
-        type: "string",
-        description: "The host 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".',
-      },
-      working_dir: {
-        type: "string",
-        description:
-          "Optional absolute host working directory (defaults to user home)",
-      },
-      timeout_seconds: {
-        type: "number",
-        description:
-          "Optional timeout in seconds. Uses configured default and max limits.",
-      },
-      background: {
-        type: "boolean",
-        description:
-          "Run the command in the background on the host machine. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
-      },
-      target_client_id: {
-        type: "string",
-        description:
-          "ID of the specific client to execute this command on. Required when multiple clients support host_bash; omit when only one client is connected. Obtain IDs from `assistant clients list --capability host_bash`.",
-      },
-    },
-    required: ["command", "activity"],
-  },
+  input_schema: toToolInputSchema(hostShellInputSchema, {
+    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 = hostShellInputSchema.safeParse(input);
+    if (!parsed.success) {
+      return invalidToolInputResult("host_bash", parsed.error);
     }
+    const command = parsed.data.command;
     if (command.includes("\0")) {
       return { content: "Error: command contains null bytes", isError: true };
     }
 
-    const rawWorkingDir = input.working_dir;
-    if (rawWorkingDir != null && typeof rawWorkingDir !== "string") {
-      return {
-        content: "Error: working_dir must be a string when provided",
-        isError: true,
-      };
-    }
+    const rawWorkingDir = parsed.data.working_dir;
     if (typeof rawWorkingDir === "string" && rawWorkingDir.includes("\0")) {
       return {
         content: "Error: working_dir contains null bytes",
@@ -168,7 +185,7 @@ export const hostShellTool = {
         isError: true,
       };
     }
-    const background = input.background === true;
+    const background = parsed.data.background === true;
     if (background && context.diskPressureCleanupModeActive === true) {
       return {
         content:
@@ -178,9 +195,8 @@ export const hostShellTool = {
     }
 
     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 config = getConfig();
@@ -230,10 +246,7 @@ export const hostShellTool = {
     // Proxy to connected client for execution on the user's machine
     // when a capable client is available (managed/cloud-hosted mode).
     if (HostBashProxy.instance.isAvailable()) {
-      const rawSec =
-        typeof input.timeout_seconds === "number"
-          ? input.timeout_seconds
-          : shellDefaultTimeoutSec;
+      const rawSec = parsed.data.timeout_seconds ?? shellDefaultTimeoutSec;
       const normalizedTimeout = Math.max(
         1,
         Math.min(rawSec, shellMaxTimeoutSec),
@@ -419,10 +432,7 @@ export const hostShellTool = {
     const workingDir =
       typeof rawWorkingDir === "string" ? rawWorkingDir : homedir();
 
-    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;
 
@@ -500,7 +510,9 @@ export const hostShellTool = {
       let completed = false;
 
       child.on("close", (code) => {
-        if (completed) {return;}
+        if (completed) {
+          return;
+        }
         completed = true;
         clearTimeout(timer);
         const stdout = Buffer.concat(stdoutChunks).toString();
@@ -572,7 +584,9 @@ export const hostShellTool = {
       });
 
       child.on("error", (err) => {
-        if (completed) {return;}
+        if (completed) {
+          return;
+        }
         completed = true;
         clearTimeout(timer);
         const status = aborted ? "cancelled" : "failed";

package/src/tools/policy-context.ts

@@ -1,10 +1,29 @@
 import { getConfig } from "../config/loader.js";
-import { isProcToSkillsActive } from "../config/memory-v3-gate.js";
+import { isV3TierActive } from "../config/memory-v3-gate.js";
 import type { ExecutionContext } from "../permissions/approval-policy.js";
+import type { ChannelPermissionCoordinates } from "../permissions/channel-permission-query.js";
 import type { PolicyContext } from "../permissions/types.js";
 import { getToolOwner } from "./registry.js";
 import type { Tool, ToolContext } from "./types.js";
 
+/**
+ * Channel coordinates of the turn, in {@link PolicyContext} shape. The
+ * permission checker reaches these through the policy context, while the
+ * sensitive-tool gate runs before one exists and reads a `ToolContext`
+ * directly — both resolve the same permission-matrix cell, so the field
+ * mapping lives here once rather than in each lane.
+ */
+export function channelCoordinatesFromToolContext(
+  context?: ToolContext,
+): ChannelPermissionCoordinates {
+  return {
+    trustClass: context?.trustClass,
+    sourceChannel: context?.executionChannel,
+    channelExternalId: context?.channelPermissionChannelId,
+    channelConversationType: context?.channelConversationType,
+  };
+}
+
 /**
  * Derive the execution context from the tool context fields.
  * - Guardian + non-interactive → "background" (scheduled jobs, reminders)
@@ -42,15 +61,13 @@ export function buildPolicyContext(
   // origin-scoped grant can fire for them.
   const originSignals = {
     requestOrigin: context?.requestOrigin,
-    trustClass: context?.trustClass,
-    sourceChannel: context?.executionChannel,
-    channelExternalId: context?.channelPermissionChannelId,
-    channelConversationType: context?.channelConversationType,
-    // Precompute the proc-to-skills gate (flag on AND v3 live) here so the
-    // permission checker — a leaf module that must not read config — can deny
-    // the memory-retrospective skill-authoring grant whenever the feature is
-    // inactive, just by reading this boolean.
-    procToSkillsActive: isProcToSkillsActive(getConfig()),
+    ...channelCoordinatesFromToolContext(context),
+    // Precompute the proc-to-skills gate — the v3 tier being active, i.e.
+    // memory on AND v3 live — here so the permission checker, a leaf module
+    // that must not read config, can deny the memory-retrospective
+    // skill-authoring grant whenever the feature is inactive just by reading
+    // this boolean.
+    procToSkillsActive: isV3TierActive(getConfig()),
   };
 
   const ownerKind = getToolOwner(tool.name)?.kind;

package/src/tools/schedule/create.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import { resolveCapabilities } from "../../runtime/capabilities.js";
 import { validateScheduleInferenceProfile } from "../../schedule/inference-profile.js";
 import { formatIntegrationSummary } from "../../schedule/integration-status.js";
@@ -18,6 +20,10 @@ import {
   CapabilityManifestSchema,
   resolveCapabilities as resolveWorkflowCapabilities,
 } from "../../workflows/capabilities.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 const VALID_MODES: ScheduleMode[] = ["notify", "execute", "script", "workflow"];
@@ -27,6 +33,48 @@ const VALID_ROUTING_INTENTS: RoutingIntent[] = [
   "all_channels",
 ];
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeScheduleCreate}.
+ * 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 schedule skill's
+ * `TOOLS.json`, and `schedule-tool-input-schemas.test.ts` guards the two
+ * against structural drift.
+ *
+ * Tolerance matches the executor's own reads — this schema only rejects
+ * values the executor would otherwise pass into the store unchecked:
+ *
+ * - `nullAsOmitted` on optionals read via `?? fallback`, where null and
+ *   absent are equivalent.
+ * - `.catch(undefined)` on `workflow_name`, which the executor
+ *   silently coerces to null when malformed.
+ * - `mode`, `routing_intent`, `capabilities`, and `workflow_args` are
+ *   deliberately UNDECLARED (loose passthrough): the first two keep their
+ *   bespoke `VALID_*` error messages, `capabilities` must reach
+ *   `CapabilityManifestSchema` (and the `requireFreshApproval` promotion in
+ *   `executor.ts`) unaltered, and `workflow_args` accepts any JSON value the
+ *   workflow runtime accepts.
+ */
+export const scheduleCreateInputSchema = z.looseObject({
+  name: nullAsOmitted(z.string()),
+  description: nullAsOmitted(z.string()),
+  syntax: nullAsOmitted(z.enum(["cron", "rrule"])),
+  expression: nullAsOmitted(z.string()),
+  fire_at: nullAsOmitted(z.string()),
+  timezone: nullAsOmitted(z.string()),
+  message: nullAsOmitted(z.string()),
+  script: nullAsOmitted(z.string()),
+  enabled: nullAsOmitted(z.boolean()),
+  workflow_name: z.string().optional().catch(undefined),
+  routing_hints: nullAsOmitted(z.looseObject({})),
+  quiet: nullAsOmitted(z.boolean()),
+  reuse_conversation: nullAsOmitted(z.boolean()),
+  max_retries: nullAsOmitted(z.int()),
+  retry_backoff_ms: nullAsOmitted(z.int()),
+  timeout_ms: z.int().optional(),
+  inference_profile: z.string().optional(),
+});
+
 export async function executeScheduleCreate(
   input: Record<string, unknown>,
   context: ToolContext,
@@ -38,27 +86,32 @@ export async function executeScheduleCreate(
       isError: true,
     };
   }
-  const name = input.name as string;
-  const description = input.description as string | undefined;
-  const timezone = (input.timezone as string) ?? null;
-  const message = (input.message as string) ?? "";
-  const script = (input.script as string) ?? null;
-  const enabled = (input.enabled as boolean) ?? true;
-  const fireAt = input.fire_at as string | undefined;
+  const parsedInput = scheduleCreateInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("schedule_create", parsedInput.error);
+  }
+  const parsed = parsedInput.data;
+
+  const name = parsed.name;
+  const description = parsed.description;
+  const timezone = parsed.timezone ?? null;
+  const message = parsed.message ?? "";
+  const script = parsed.script ?? null;
+  const enabled = parsed.enabled ?? true;
+  const fireAt = parsed.fire_at;
+  // mode / routing_intent / workflow_args (and capabilities, read below) stay
+  // raw-input reads: they are undeclared in the schema (see its doc comment).
   const mode = (input.mode as ScheduleMode | undefined) ?? "execute";
   const routingIntent = input.routing_intent as string | undefined;
-  const routingHints = input.routing_hints as
-    | Record<string, unknown>
-    | undefined;
-  const quiet = (input.quiet as boolean) ?? false;
-  const reuseConversation = input.reuse_conversation as boolean | undefined;
-  const maxRetries = input.max_retries as number | undefined;
-  const retryBackoffMs = input.retry_backoff_ms as number | undefined;
-  const timeoutMs = input.timeout_ms as number | undefined;
-  const workflowName =
-    typeof input.workflow_name === "string" ? input.workflow_name.trim() : null;
+  const routingHints = parsed.routing_hints;
+  const quiet = parsed.quiet ?? false;
+  const reuseConversation = parsed.reuse_conversation;
+  const maxRetries = parsed.max_retries;
+  const retryBackoffMs = parsed.retry_backoff_ms;
+  const timeoutMs = parsed.timeout_ms;
+  const workflowName = parsed.workflow_name?.trim() ?? null;
   const workflowArgs = input.workflow_args;
-  const inferenceProfile = input.inference_profile as string | undefined;
+  const inferenceProfile = parsed.inference_profile;
 
   // Validated workflow capability manifest, resolved only for workflow mode.
   // Left null for non-workflow modes so `createSchedule` persists no manifest.
@@ -72,30 +125,20 @@ export async function executeScheduleCreate(
   }
 
   if (inferenceProfile !== undefined) {
-    if (typeof inferenceProfile !== "string") {
-      return {
-        content: "Error: inference_profile must be a string",
-        isError: true,
-      };
-    }
     const profileError = validateScheduleInferenceProfile(inferenceProfile);
     if (profileError) {
       return { content: `Error: ${profileError}`, isError: true };
     }
   }
 
-  if (!name || typeof name !== "string") {
+  if (!name) {
     return {
       content: "Error: name is required and must be a string",
       isError: true,
     };
   }
 
-  if (
-    !description ||
-    typeof description !== "string" ||
-    description.trim().length === 0
-  ) {
+  if (!description || description.trim().length === 0) {
     return {
       content: "Error: description is required and must be a non-empty string",
       isError: true,
@@ -112,7 +155,7 @@ export async function executeScheduleCreate(
 
   // Mode-specific field validation
   if (mode === "script") {
-    if (!script || typeof script !== "string") {
+    if (!script) {
       return {
         content:
           "Error: script is required for script mode and must be a non-empty string",
@@ -251,8 +294,8 @@ export async function executeScheduleCreate(
 
   // ── Recurring schedule (expression) ──────────────────────────────
   const resolved = normalizeScheduleSyntax({
-    syntax: input.syntax as "cron" | "rrule" | undefined,
-    expression: input.expression as string | undefined,
+    syntax: parsed.syntax,
+    expression: parsed.expression,
   });
 
   if (!resolved) {

package/src/tools/schedule/delete.ts

@@ -1,12 +1,31 @@
+import { z } from "zod";
+
 import { deleteSchedule, getSchedule } from "../../schedule/schedule-store.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 executeScheduleDelete}.
+ * Same in-tool pattern and drift guard as {@link scheduleCreateInputSchema}
+ * in `create.ts` — see that schema's doc comment for the framework.
+ */
+export const scheduleDeleteInputSchema = z.looseObject({
+  job_id: nullAsOmitted(z.string()),
+});
+
 export async function executeScheduleDelete(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const jobId = input.job_id as string;
-  if (!jobId || typeof jobId !== "string") {
+  const parsedInput = scheduleDeleteInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("schedule_delete", parsedInput.error);
+  }
+  const jobId = parsedInput.data.job_id;
+  if (!jobId) {
     return { content: "Error: job_id is required", isError: true };
   }
 

package/src/tools/schedule/list.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import { hasSetConstructs } from "../../schedule/recurrence-engine.js";
 import {
   describeCronExpression,
@@ -6,6 +8,10 @@ import {
   getScheduleRuns,
   listSchedules,
 } from "../../schedule/schedule-store.js";
+import {
+  invalidToolInputResult,
+  nullAsOmitted,
+} from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
 function describeSchedule(job: {
@@ -13,7 +19,9 @@ function describeSchedule(job: {
   expression: string | null;
   cronExpression: string | null;
 }): string {
-  if (job.expression == null) return "One-time";
+  if (job.expression == null) {
+    return "One-time";
+  }
   if (job.syntax === "rrule") {
     const label = hasSetConstructs(job.expression) ? "[RRULE set] " : "";
     return `${label}${job.expression}`;
@@ -29,12 +37,26 @@ function describeAuthoredPurpose(job: { description: string }): string {
   return job.description || "(none)";
 }
 
+/**
+ * Model-input schema, `safeParse`d at the top of {@link executeScheduleList}.
+ * Same in-tool pattern and drift guard as {@link scheduleCreateInputSchema}
+ * in `create.ts` — see that schema's doc comment for the framework.
+ */
+export const scheduleListInputSchema = z.looseObject({
+  enabled_only: nullAsOmitted(z.boolean()),
+  job_id: nullAsOmitted(z.string()),
+});
+
 export async function executeScheduleList(
   input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const jobId = input.job_id as string | undefined;
-  const enabledOnly = (input.enabled_only as boolean) ?? false;
+  const parsedInput = scheduleListInputSchema.safeParse(input);
+  if (!parsedInput.success) {
+    return invalidToolInputResult("schedule_list", parsedInput.error);
+  }
+  const jobId = parsedInput.data.job_id;
+  const enabledOnly = parsedInput.data.enabled_only ?? false;
 
   // Detail mode for a specific job
   if (jobId) {