diff --git a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts index 43b47b5f96b..293788a626b 100644 --- a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts +++ b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts @@ -342,7 +342,7 @@ async function handleRequest( ? "continuation" : errors.some(error => error.instancePath === "") ? "root" : "other"; context.diagnoseFinishInput({ input: params.arguments, callId, validationCategory }); } - const error = toolInputError(validator); + const error = toolInputError(validator, args); try { context.onRejectedCall?.({ tool, callId, arguments: args }, error); } catch {} outcome = "error"; writeRpc(response, id, { diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts index 1ce220b7f7b..b67b76b36e0 100644 --- a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts @@ -373,7 +373,7 @@ async function handleRequest( writeToolError( response, id, - toolInputError(validator), + toolInputError(validator, args), ); return; } diff --git a/packages/paperclip-runner/src/drivers/tool-input-error.test.ts b/packages/paperclip-runner/src/drivers/tool-input-error.test.ts index 0d2f2145282..4aa3993525b 100644 --- a/packages/paperclip-runner/src/drivers/tool-input-error.test.ts +++ b/packages/paperclip-runner/src/drivers/tool-input-error.test.ts @@ -1,6 +1,7 @@ import { Ajv2020 } from "ajv/dist/2020.js"; import { expect, it } from "vitest"; import { toolInputError } from "./tool-input-error.js"; +import { createCaseAction } from "../protocol-actions/case-data.js"; it("leaves ordinary validation errors unchanged and excludes guidance from unrelated scopes", () => { const validate = new Ajv2020({ allErrors: true }).compile({ type: "object", required: ["id", "child"], properties: { @@ -23,3 +24,25 @@ it("bounds and deduplicates direct missing-property descriptions", () => { expect(result).not.toContain("e".repeat(1000)); expect(result).not.toContain("a".repeat(1001)); }); + +it("names the missing create_case fields, what the call included, and a short example", () => { + const validate = new Ajv2020({ allErrors: true, strict: false }).compile(createCaseAction.live.descriptor.inputSchema); + const input = { workflow_document_text: "Investigate, then verify." }; + expect(validate(input)).toBe(false); + const result = toolInputError(validate, input); + expect(result).toContain("missing required fields: idempotencyKey, caseType, title, kickoff."); + expect(result).toContain("This call included only: workflow_document_text."); + expect(result).toContain('Missing fields example: {"idempotencyKey":"","caseType":"","title":"","kickoff":{"toAgentId":"<toAgentId>","phase":"<phase>","instructions":"<instructions>"}}'); + expect(result).not.toContain("must have required property"); +}); + +it("keeps other validation errors after the missing fields", () => { + const validate = new Ajv2020({ allErrors: true }).compile({ type: "object", required: ["id", "count"], properties: { + id: { type: "string" }, count: { type: "integer" }, child: { type: "object", required: ["id"], properties: { id: { type: "string" } } }, + } }); + const input = { child: {} }; + validate(input); + expect(toolInputError(validate, input)).toBe( + 'Invalid tool input: missing required fields: id, count. This call included only: child. Send every required field together in one call, alongside the fields you already sent. Missing fields example: {"id":"<id>","count":0} Also: /child must have required property \'id\'', + ); +}); diff --git a/packages/paperclip-runner/src/drivers/tool-input-error.ts b/packages/paperclip-runner/src/drivers/tool-input-error.ts index b3692e65b08..275c43616c2 100644 --- a/packages/paperclip-runner/src/drivers/tool-input-error.ts +++ b/packages/paperclip-runner/src/drivers/tool-input-error.ts @@ -1,15 +1,50 @@ -import type { ValidateFunction } from "ajv/dist/2020.js"; +import type { ErrorObject, ValidateFunction } from "ajv/dist/2020.js"; + +type JsonSchemaNode = { + type?: unknown; + properties?: Record<string, JsonSchemaNode>; + required?: unknown; + description?: unknown; +}; + +const MAX_LISTED_FIELDS = 12; +const MAX_EXAMPLE_LENGTH = 600; + +function isRootRequiredError(error: ErrorObject) { + return error.keyword === "required" && error.instancePath === "" && error.schemaPath === "#/required"; +} + +function placeholder(key: string, schema: JsonSchemaNode | undefined, depth: number): unknown { + const type = Array.isArray(schema?.type) ? schema?.type.find(entry => entry !== "null") : schema?.type; + if (type === "object") { + const required = Array.isArray(schema?.required) ? schema.required.filter((entry): entry is string => typeof entry === "string") : []; + if (depth >= 2 || required.length === 0) return {}; + return Object.fromEntries(required.map(child => [child, placeholder(child, schema?.properties?.[child], depth + 1)])); + } + if (type === "array") return []; + if (type === "integer" || type === "number") return 0; + if (type === "boolean") return false; + return `<${key}>`; +} + +function listFields(keys: string[]) { + const shown = keys.slice(0, MAX_LISTED_FIELDS).join(", "); + return keys.length > MAX_LISTED_FIELDS ? `${shown}, and ${keys.length - MAX_LISTED_FIELDS} more` : shown; +} /** Return schema-owned recovery guidance without changing validation or dispatch. */ -export function toolInputError(validator: ValidateFunction | undefined): string { +export function toolInputError(validator: ValidateFunction | undefined, input?: unknown): string { const errors = validator?.errors ?? []; - const detail = errors.map(error => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`).join("; "); const schema = validator?.schema; - const properties = typeof schema === "object" && schema !== null ? schema.properties : undefined; + const rootSchema = typeof schema === "object" && schema !== null ? schema as JsonSchemaNode : undefined; + const properties = rootSchema?.properties; + const missing = [...new Set(errors.filter(isRootRequiredError) + .map(error => error.params.missingProperty) + .filter((key): key is string => typeof key === "string"))]; + const otherErrors = missing.length ? errors.filter(error => !isRootRequiredError(error)) : errors; + const detail = otherErrors.map(error => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`).join("; "); const guidance = new Set<string>(); for (const error of errors) { - // Only direct required properties are supported. Nested schemas and refs - // need their own resolution; do not attach guidance from a different scope. if (error.keyword !== "required" || error.instancePath !== "") continue; const key = error.params.missingProperty; if (typeof key !== "string" || !properties || !Object.hasOwn(properties, key)) continue; @@ -17,5 +52,16 @@ export function toolInputError(validator: ValidateFunction | undefined): string if (typeof description === "string" && description.trim()) guidance.add(description.slice(0, 1000)); if (guidance.size === 3) break; } - return `Invalid tool input${detail ? `: ${detail}` : "."}${guidance.size ? ` ${[...guidance].join(" ")}` : ""}`; + const parts: string[] = []; + if (missing.length) { + const received = typeof input === "object" && input !== null && !Array.isArray(input) ? Object.keys(input) : []; + const example = JSON.stringify(Object.fromEntries(missing.map(key => [key, placeholder(key, properties?.[key], 0)]))); + parts.push(`missing required field${missing.length === 1 ? "" : "s"}: ${listFields(missing)}.`); + parts.push(received.length ? `This call included only: ${listFields(received)}.` : "This call included no fields."); + parts.push("Send every required field together in one call, alongside the fields you already sent."); + if (example.length <= MAX_EXAMPLE_LENGTH) parts.push(`Missing fields example: ${example}`); + } + if (detail) parts.push(missing.length ? `Also: ${detail}` : detail); + const body = parts.join(" "); + return `Invalid tool input${body ? `: ${body}` : "."}${guidance.size ? ` ${[...guidance].join(" ")}` : ""}`; }