@vellumai/assistant 0.12.4-staging.2 → 0.12.4-staging.4

package/src/skills/validate-input.ts

@@ -3,10 +3,11 @@
  *
  * Deliberate strict subset of JSON Schema: it covers only the keywords
  * actually used by `assistant/src/config/bundled-skills/**\/TOOLS.json`
- * (required / type / enum / items.type) plus unknown-key detection. Anything
- * else (`$ref`, `oneOf`, `anyOf`, `allOf`, `format`, `pattern`, `minimum`,
- * `maximum`, object-shape `additionalProperties`, etc.) is silently skipped so
- * a richer schema can never cause us to reject a legitimate call.
+ * (required / type / enum / nested properties and items / required-only oneOf)
+ * plus unknown-key detection. Anything else (`$ref`, richer `oneOf`, `anyOf`,
+ * `allOf`, `format`, `pattern`, `minimum`, `maximum`, object-shape
+ * `additionalProperties`, etc.) is skipped. Nested objects allow extra keys
+ * unless their schema explicitly closes them.
  *
  * Each error message is written to be agent-readable and self-correcting
  * (e.g. `surface_id is required`, `mode must be one of "replace", "append"`).
@@ -313,6 +314,15 @@ export function validateInputAgainstSchema(
   _toolName: string,
   input: Record<string, unknown>,
   schema: Record<string, unknown> | undefined,
+): InputValidationResult {
+  return validateObjectInput(input, schema, "", true);
+}
+
+function validateObjectInput(
+  input: Record<string, unknown>,
+  schema: Record<string, unknown> | undefined,
+  path: string,
+  rejectUnknown: boolean,
 ): InputValidationResult {
   // Skip when there's no schema or no properties block — matches today's
   // lenient behaviour for tools that declare only `{ type: "object" }`.
@@ -338,17 +348,46 @@ export function validateInputAgainstSchema(
         continue;
       }
       if (!(key in input)) {
-        errors.push(`${key} is required`);
+        errors.push(`${path}${key} is required`);
       }
     }
   }
 
+  // Only enforce alternatives whose complete contract is field presence.
+  // Richer unions stay permissive because unsupported keywords can decide
+  // which branch matches.
+  const alternatives = schema.oneOf;
+  if (
+    Array.isArray(alternatives) &&
+    alternatives.length > 0 &&
+    alternatives.every(
+      (branch) =>
+        isPlainObject(branch) &&
+        Object.keys(branch).every(
+          (key) => key === "required" || key === "description",
+        ) &&
+        Array.isArray(branch.required) &&
+        branch.required.every((key: unknown) => typeof key === "string"),
+    )
+  ) {
+    const choices = alternatives as { required: string[] }[];
+    if (
+      choices.filter((branch) => branch.required.every((key) => key in input))
+        .length !== 1
+    ) {
+      errors.push(
+        `${path ? path.slice(0, -1) : "input"} must match exactly one required field set: ${choices.map((branch) => quoteList(branch.required)).join(" or ")}`,
+      );
+    }
+  }
+
   // 2. Per-property checks: type, enum, items.type.
-  for (const [key, rawSubSchema] of Object.entries(properties)) {
-    if (!(key in input)) {
+  for (const [property, rawSubSchema] of Object.entries(properties)) {
+    if (!(property in input)) {
       continue;
     }
-    const value = input[key];
+    const key = `${path}${property}`;
+    const value = input[property];
     // Skip type-checking for absent values; presence is enforced by the
     // `required` check above. Note: `null` IS a present value and is
     // type-checked below — only schemas that explicitly opt in to null via
@@ -381,13 +420,25 @@ export function validateInputAgainstSchema(
       if (!matchesType(value, type)) {
         errors.push(
           type === "boolean" && typeof value === "string"
-            ? `${key} must be a boolean — pass true or false as a JSON boolean, not a string`
+            ? `${key} must be a boolean: pass true or false as a JSON boolean, not a string`
             : `${key} must be ${typeArticle(type)} ${type}`,
         );
         // No point checking enum/items if the base type is wrong.
         continue;
       }
 
+      if (type === "object" && isPlainObject(value)) {
+        const nested = validateObjectInput(
+          value,
+          rawSubSchema,
+          `${key}.`,
+          rawSubSchema.additionalProperties === false,
+        );
+        if (!nested.ok) {
+          errors.push(...nested.errors);
+        }
+      }
+
       // 2a. Enum (string enums are the only shape used today).
       const enumValues = rawSubSchema.enum;
       if (Array.isArray(enumValues) && enumValues.length > 0) {
@@ -412,6 +463,17 @@ export function validateInputAgainstSchema(
               errors.push(
                 `${key}[${index}] must be ${typeArticle(itemTypeName)} ${itemTypeName}`,
               );
+            } else if (itemTypeName === "object" && isPlainObject(element)) {
+              const itemSchema = rawSubSchema.items as Record<string, unknown>;
+              const nested = validateObjectInput(
+                element,
+                itemSchema,
+                `${key}[${index}].`,
+                itemSchema.additionalProperties === false,
+              );
+              if (!nested.ok) {
+                errors.push(...nested.errors);
+              }
             }
           });
         }
@@ -420,10 +482,12 @@ export function validateInputAgainstSchema(
   }
 
   // 3. Unknown keys — parity with the previous `validateNoUnknownParams`.
-  const unknownKeys = Object.keys(input).filter((k) => !knownKeySet.has(k));
+  const unknownKeys = rejectUnknown
+    ? Object.keys(input).filter((k) => !knownKeySet.has(k))
+    : [];
   for (const key of unknownKeys) {
     errors.push(
-      `Unknown parameter "${key}". Supported: ${quoteList(knownKeys)}`,
+      `Unknown parameter "${path}${key}". Supported: ${quoteList(knownKeys)}`,
     );
   }
 

package/src/tools/skills/execute.ts

@@ -178,7 +178,7 @@ export function augmentSkillExecuteError(
 export const skillExecuteTool = {
   name: "skill_execute",
   description:
-    "Execute a tool provided by a loaded skill. Use this instead of calling skill tools directly. The skill's instructions (from skill_load) describe available tools and their parameters. For browser automation, use the `assistant browser` CLI commands instead.",
+    "Execute a tool provided by a loaded skill. When skill_load is available, call it for the owning skill before first use, even if a capability card says it is available. Use the current instructions and input schema over remembered arguments. Use this instead of calling skill tools directly. For browser automation, use the `assistant browser` CLI commands instead.",
   category: "skills",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,

package/src/tools/skills/format-input-schema.ts

@@ -0,0 +1,15 @@
+import { getWorkspaceDirDisplay } from "../../util/platform.js";
+
+/** Preserve nested fields and alternatives when disclosing a skill's input. */
+export function formatSkillInputSchema(schema: object): string {
+  const workspaceDir = getWorkspaceDirDisplay();
+  const json = JSON.stringify(
+    schema,
+    (_key, value: unknown) =>
+      typeof value === "string"
+        ? value.replaceAll("{workspaceDir}", workspaceDir)
+        : value,
+    2,
+  );
+  return `Input schema for \`skill_execute.input\`:\n\`\`\`json\n${json}\n\`\`\``;
+}

package/src/tools/skills/load.ts

@@ -35,6 +35,7 @@ import type {
   ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
+import { formatSkillInputSchema } from "./format-input-schema.js";
 
 /** Skill sources eligible for inline command expansion in v1. */
 const INLINE_COMMAND_ELIGIBLE_SOURCES = new Set([
@@ -123,32 +124,7 @@ function formatToolSchemas(
       tool.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay()),
     );
 
-    const schema = tool.input_schema;
-    const properties = schema.properties as
-      | Record<string, Record<string, unknown>>
-      | undefined;
-    if (properties && Object.keys(properties).length > 0) {
-      const requiredSet = new Set<string>(
-        Array.isArray(schema.required) ? (schema.required as string[]) : [],
-      );
-
-      lines.push("Parameters:");
-      for (const [paramName, paramDef] of Object.entries(properties)) {
-        const paramType =
-          typeof paramDef.type === "string" ? paramDef.type : "any";
-        const requiredLabel = requiredSet.has(paramName)
-          ? "required"
-          : "optional";
-        const descPart =
-          typeof paramDef.description === "string"
-            ? `: ${paramDef.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay())}`
-            : "";
-        lines.push(
-          `- ${paramName} (${paramType}, ${requiredLabel})${descPart}`,
-        );
-      }
-    }
-
+    lines.push(formatSkillInputSchema(tool.input_schema));
     lines.push("");
   }
 

package/src/tools/skills/skill-tool-factory.ts

@@ -15,6 +15,7 @@ import { bundledToolInputMisuseMessage } from "../shared/input-misuse.js";
 import { bundledToolInputRepairs } from "../shared/input-repairs.js";
 import type { ExecutionTarget } from "../tool-types.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import { formatSkillInputSchema } from "./format-input-schema.js";
 import { runSkillToolScript } from "./skill-script-runner.js";
 
 const riskMap: Record<SkillToolEntry["risk"], RiskLevel> = {
@@ -94,7 +95,7 @@ export function createSkillTool(
         return {
           content:
             misuse ??
-            `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. Fix the arguments and retry.`,
+            `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. If skill_load is available, load the owning skill for its current instructions. Retry with arguments matching this schema.\n\n${formatSkillInputSchema(entry.input_schema)}`,
           isError: true,
         };
       }