diff --git a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts index 88ad0d3e2cd..e2a6ee7da19 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts @@ -394,6 +394,28 @@ describe("qualified ACPX runtime sidecar", () => { for (const agent of ["cursor", "codex", "pi"]) expect(create({ agent, tools: [] }, evidence, () => undefined, CLAUDE_TOOL_USE_META_KEY).captureSemanticReceipt).toBeUndefined(); }); + it("records the actual sidecar bridge's input coercions as runtime diagnostics", async () => { + const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8"); + const start = source.indexOf(" semanticTools: {"); + const end = source.indexOf(" onGoalUpdate:", start); + const diagnostics: Array<[string, string]> = []; + const create = new Function("params", "activeCopilotEvidence", "waitForTool", "diagnostic", "RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE", "CLAUDE_TOOL_USE_META_KEY", + `return ({ ${source.slice(start, end)} }).semanticTools;`); + const handler = vi.fn(async () => ({ ok: true })); + const bridge = await startRunnerToolBridge(create({ agent: "claude", tools: [{ name: "update_case", inputSchema: { + type: "object", required: ["patch"], properties: { patch: { type: "object" } } } }] }, undefined, handler, + (code: string, message: string) => diagnostics.push([code, message]), "runner_tool_bridge_diagnostic", CLAUDE_TOOL_USE_META_KEY)); + try { + const body = await fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, + body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "update_case", arguments: { patch: '{"status":"done"}' } } }) }).then(response => response.json() as Promise<{ result: { isError?: boolean } }>); + expect(body.result.isError).not.toBe(true); + expect(handler).toHaveBeenCalledOnce(); + expect(diagnostics).toHaveLength(1); + expect(diagnostics[0]![0]).toBe("runner_tool_bridge_diagnostic"); + expect(JSON.parse(diagnostics[0]![1])).toMatchObject({ schema: "paperclip.runner.tool-input-coerced/v1", tool: "update_case", paths: ["/patch"] }); + } finally { await bridge.close(); } + }); + it("keeps a native tool pending through controller downtime without a duplicate side effect", async () => { const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8"); const start = source.indexOf(" semanticTools: {"); diff --git a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts index f83d4c290bd..3833b9c6108 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts @@ -1,5 +1,6 @@ #!/usr/bin/env node import { recordSidecarShutdownThenQueue, sidecarShutdownSnapshot } from "./acpx-sidecar-shutdown.js"; +import { RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE } from "../drivers/tool-input-coercion.js"; import { classifyClaudeStatusBanner } from "../drivers/acpx/claude-status-banners.js"; import { resolveGrokDisableWebSearch } from "../drivers/acpx/grok-web-search.js"; import { toolFileChangesFromAcpContent, workspaceRootsFor, type ToolFileChange } from "../tool-file-changes.js"; @@ -376,6 +377,7 @@ async function dispatch( timeoutMs: null, ...(params.agent === "claude" ? { providerToolUseIdMetaKey: CLAUDE_TOOL_USE_META_KEY } : {}), ...(params.agent === "copilot" ? { captureSemanticReceipt: () => activeCopilotEvidence?.captureSemanticReceipt() } : {}), + onDiagnostic: message => diagnostic(RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE, message), }, onGoalUpdate: (goal) => { // Admission can emit a snapshot before the verified host is assigned. diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.test.ts b/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.test.ts index f5631d9521c..2c0344cd19b 100644 --- a/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.test.ts +++ b/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.test.ts @@ -114,3 +114,19 @@ it("forwards closed tool delivery records after binding and drops any record tha expect(frames).toEqual([{ method: "warning", params: { threadId: "actual-session", message: JSON.stringify({ ...delivery, socketRequestIndex: 2, socketIdleMs: 5270 }) } }]); }); + +it("forwards closed input-coercion records and drops any that could carry values", () => { + const frames: { params: { message: string } }[] = []; + const forward = createOpenCodeFinishDiagnosticForwarder(frame => frames.push(frame as never)); + forward.bind("session"); + const record = { schema: "paperclip.runner.tool-input-coerced/v1", tool: "paperclip_finish", callIdSha256: "c".repeat(64), coercion: "json_string_to_object", paths: ["/continuation", "/evidence/0"] }; + forward.diagnostic(JSON.stringify(record)); + for (const bad of [ + { ...record, value: "secret" }, + { ...record, paths: ["/continuation value"] }, + { ...record, paths: [] }, + { ...record, coercion: "other" }, + { ...record, tool: "x y" }, + ]) forward.diagnostic(JSON.stringify(bad)); + expect(frames.map(frame => JSON.parse(frame.params.message))).toEqual([record]); +}); diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.ts b/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.ts index f7d9baa926a..a718a856dd4 100644 --- a/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.ts +++ b/packages/paperclip-runner/src/cli/opencode-proxy-finish-diagnostics.ts @@ -3,6 +3,7 @@ export function createOpenCodeFinishDiagnosticForwarder(send: (frame: Warning) = let threadId: string | undefined; let offered: Record | undefined; let rejections = 0; + let coercions = 0; const emit = (value: Record) => { if (!threadId) return; try { send({ method: "warning", params: { threadId, message: JSON.stringify(value) } }); } catch {} @@ -22,6 +23,11 @@ export function createOpenCodeFinishDiagnosticForwarder(send: (frame: Warning) = if (validToolDelivery(value)) emit(value); return; } + if (value && typeof value === "object" && !Array.isArray(value) + && value.schema === "paperclip.runner.tool-input-coerced/v1") { + if (coercions < 32 && validInputCoercion(value)) { coercions += 1; emit(value); } + return; + } if (!value || typeof value !== "object" || Array.isArray(value) || value.schema !== "paperclip.opencode.finish-input-diagnostic/v1" || typeof value.schemaSha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.schemaSha256)) return; @@ -57,3 +63,15 @@ function validToolDelivery(value: Record): boolean { && typeof value.outcome === "string" && ["result", "error", "unanswered"].includes(value.outcome) && typeof value.written === "boolean"; } + +const INPUT_COERCION_KEYS = "callIdSha256,coercion,paths,schema,tool"; +// Coercion records name the tool and the repaired field paths only. Reject +// anything else so this channel cannot forward tool inputs. +function validInputCoercion(value: Record): boolean { + return Object.keys(value).sort().join(",") === INPUT_COERCION_KEYS + && typeof value.callIdSha256 === "string" && /^[a-f0-9]{64}$/.test(value.callIdSha256) + && value.coercion === "json_string_to_object" + && typeof value.tool === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(value.tool) + && Array.isArray(value.paths) && value.paths.length > 0 && value.paths.length <= 32 + && value.paths.every(path => typeof path === "string" && /^(\/[A-Za-z0-9_.-]{1,64}){1,16}$/.test(path)); +} diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts b/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts index 83c65e173c8..2a506e50361 100644 --- a/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts +++ b/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.test.ts @@ -52,6 +52,18 @@ describe("Codex ACPX harness driver", () => { expect(events.find(event => event.eventType === "run.result.proposed")?.payload).toEqual(capture.mock.calls[0]![0]); await session.close({ reason: "same-invocation normalization verified" }); }); + it("records the runner bridge's input coercion diagnostics as run events", async () => { + const fixture = driverFixture({ agent: "claude", model: "explicit-test-model", providerPolicy: { readOnly: true } }, { runtimeEvents: [] }); + const session = await fixture.driver.openSession({ runId: "run-coercion", normalizedSessionId: "session-1", workingDirectory: "/workspace" }); + await session.startTurn({ message: { role: "user", text: "Work" } }); + const message = JSON.stringify({ schema: "paperclip.runner.tool-input-coerced/v1", tool: "paperclip_finish", paths: ["/continuation"] }); + fixture.hostOptions!.semanticTools!.onDiagnostic!(message); + fixture.finishTurn({ status: "completed" }); + const events = await collectUntil(session.events(), "turn.completed"); + expect(events.filter(event => event.eventType === "harness.diagnostic").map(event => event.payload)) + .toContainEqual({ code: "runner_tool_bridge_diagnostic", message }); + await session.close({ reason: "coercion recorded" }); + }); it("does not commit a direct normalized input digest when proposal retention is backpressured", async () => { const fixture = driverFixture({ agent: "copilot", model: "explicit-test-model", providerPolicy: { readOnly: true } }, { maxBufferedEvents: 4, terminalEventReserve: 0, diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts b/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts index 020bfdebade..73751878397 100644 --- a/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts +++ b/packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts @@ -1,4 +1,5 @@ import { type CopilotToolEvidence } from "./copilot-tool-evidence.js"; +import { RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE } from "../tool-input-coercion.js"; import { classifyClaudeStatusBanner } from "./claude-status-banners.js"; import { resolveCompletionContinuation } from "../completion-continuation.js"; import { isProviderMode } from "../../contracts/provider-mode.js"; @@ -499,6 +500,7 @@ export class CodexAcpxDriver implements HarnessDriver { } return session.dispatchTool(call); }, + onDiagnostic: (message) => session?.recordToolBridgeDiagnostic(message), }, }, input.signal, @@ -1151,6 +1153,13 @@ class CodexAcpxSession implements HarnessSession { return this.#copilotToolEvidence?.captureSemanticReceipt(); } + /** Records a runner tool bridge diagnostic, such as an accepted input coercion, as a run event. */ + recordToolBridgeDiagnostic(message: string): void { + if (this.#closed) return; + this.#emit("harness.diagnostic", { code: RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE, message }, + this.#activeTurnId ? { turnId: this.#activeTurnId } : {}); + } + async dispatchTool(call: RunnerToolCall): Promise { this.#assertOpen(); if (this.#pendingTerminal) { diff --git a/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.test.ts b/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.test.ts index f871999474b..2e0566b7e40 100644 --- a/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.test.ts +++ b/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.test.ts @@ -714,6 +714,23 @@ describe("Cursor Cloud native driver", () => { expect((await f.session.read?.())?.providerStatus).toBe("CANCELLED"); }); + it("records a runner bridge input coercion as a run diagnostic", async () => { + const f = await fixture(); + await f.session.startTurn({ message: { role: "user", text: "Wait for a reply" } }); await f.peer.created.promise; + await waitFor(() => f.events.some(event => event.eventType === "item.delta")); + const initialized = await rpc(f.options.relay.socketPath, { id: 0, method: "initialize" }, relayHeaders(f.peer)); + const continuation = { kind: "response_wake", summary: "wait", idempotencyKey: "k" }; + const args = { reportedWorkDisposition: "yielded", summary: "Waiting.", evidence: [], verification: [], + completionClaim: { contractRevision: "1", objectiveSatisfied: false, criteria: [], remainingWork: [] }, continuation: JSON.stringify(continuation) }; + await rpc(f.options.relay.socketPath, { id: "coerced", method: "tools/call", params: { name: "paperclip_finish", arguments: args } }, relayHeaders(f.peer), initialized.session); + expect(f.handler).toHaveBeenCalledWith(expect.objectContaining({ arguments: { ...args, continuation } })); + const recorded = f.events.filter(event => event.eventType === "harness.diagnostic" && event.payload.code === "runner_tool_bridge_diagnostic"); + expect(recorded.map(event => JSON.parse(String(event.payload.message)))).toEqual([ + expect.objectContaining({ schema: "paperclip.runner.tool-input-coerced/v1", tool: "paperclip_finish", paths: ["/continuation"] }), + ]); + await f.session.interrupt!({}); + }); + it("retains only an accepted semantic receipt and waits for actual provider termination", async () => { const f = await fixture(); await f.session.startTurn({ message: { role: "user", text: "Finish semantically" } }); await f.peer.created.promise; diff --git a/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.ts b/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.ts index 630e065ea04..752e3f4730a 100644 --- a/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.ts +++ b/packages/paperclip-runner/src/drivers/cursor-cloud/cursor-cloud-driver.ts @@ -1,4 +1,5 @@ import { randomBytes, randomUUID } from "node:crypto"; +import { RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE } from "../tool-input-coercion.js"; import { chmod, lstat } from "node:fs/promises"; import { dirname, isAbsolute, resolve } from "node:path"; import { setTimeout as delay } from "node:timers/promises"; @@ -198,7 +199,8 @@ class CursorCloudSession implements CursorCloudSessionHandle { this.#bridge = await startRunnerToolBridge({ socketPath: this.#options.relay.socketPath, secret: this.#options.relay.token, tools, preserveToolNames: true, timeoutMs: null, sessionScope: () => this.#closed || this.#stopping || this.#pendingTerminal || !active(this.#cp) ? null : this.#cp.turnId, scopeToken: () => this.#closed || this.#stopping || this.#pendingTerminal || !active(this.#cp) ? null : this.#cp.relayTurnToken ?? null, - handler: call => this.#dispatch(call) }); + handler: call => this.#dispatch(call), + onDiagnostic: message => this.#emit("harness.diagnostic", { code: RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE, message }) }); const socket = await lstat(this.#options.relay.socketPath); if (!socket.isSocket() || socket.isSymbolicLink() || (process.getuid && socket.uid !== process.getuid())) throw new Error("Cursor Cloud bound relay socket ownership is unsafe"); await chmod(this.#options.relay.socketPath, 0o600); diff --git a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts index d7e075e2afa..5239a3a29c7 100644 --- a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts +++ b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts @@ -442,7 +442,8 @@ describe("repeated identical tool input rejections", () => { expect(second.startsWith(first)).toBe(true); expect(second).toContain("This exact call has now been rejected 2 times with the same arguments. Arguments received each time: none."); expect(second).toContain("Expected properties: required idempotencyKey, case, instructions; optional to, toAgentId, phase,"); - expect(second).toContain("send every field as a top-level argument of handoff_case in one call"); + expect(second).toContain("Required fields idempotencyKey, case, instructions did not arrive; if you sent them, send every field as a top-level argument of handoff_case in one call."); + expect(second).not.toContain("wrong type"); const third = (await call(bridge, "3", {})).result.content[0]!.text; expect(third).toMatch(/^This call was not accepted: handoff_case was already rejected 2 times in this run with these exact arguments\./); @@ -457,6 +458,102 @@ describe("repeated identical tool input rejections", () => { expect(handler).toHaveBeenCalledOnce(); }); + // Recorded in chat-eval cohort 13: on the DigitalOcean host paperclip_finish + // arrived with continuation as JSON text, and the same call was rejected + // until the guard stopped it. + it("accepts an object-typed field sent as JSON text and records the coercion", async () => { + const handler = vi.fn(async () => ({ accepted: true })); + const diagnostics: string[] = []; + const bridge = await startOpenCodeMcpBridge({ handler, onDiagnostic: message => diagnostics.push(message) }); + bridges.push(bridge); + const report = { summary: "s", completionClaim: { contractRevision: "r", objectiveSatisfied: true, criteria: [], remainingWork: [] }, evidence: [], verification: [] }; + const continuation = { kind: "response_wake", summary: "wait", idempotencyKey: "k" }; + const response = await call(bridge, "c1", { ...report, reportedWorkDisposition: "yielded", continuation: JSON.stringify(continuation) }, "paperclip_finish"); + expect(response.result.isError).toBeUndefined(); + expect(handler).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ arguments: { ...report, reportedWorkDisposition: "yielded", continuation } })); + const coerced = diagnostics.map(message => JSON.parse(message)).filter(entry => entry.schema === "paperclip.runner.tool-input-coerced/v1"); + expect(coerced).toEqual([expect.objectContaining({ tool: "paperclip_finish", coercion: "json_string_to_object", paths: ["/continuation"] })]); + expect(JSON.stringify(coerced)).not.toContain("wait"); + }); + + it("records a coercion only for a newly admitted call, never for a rejected or replayed one", async () => { + const handler = vi.fn(async () => ({ accepted: true })); + const diagnostics: string[] = []; + const bridge = await startOpenCodeMcpBridge({ handler, onDiagnostic: message => diagnostics.push(message) }); + bridges.push(bridge); + const coercions = () => diagnostics.map(message => JSON.parse(message)).filter(entry => entry.schema === "paperclip.runner.tool-input-coerced/v1"); + const report = { summary: "s", completionClaim: { contractRevision: "r", objectiveSatisfied: true, criteria: [], remainingWork: [] }, evidence: [], verification: [] }; + const continuation = JSON.stringify({ kind: "response_wake", summary: "wait", idempotencyKey: "k" }); + const rejected = await call(bridge, "r1", { ...report, reportedWorkDisposition: "done", continuation }, "paperclip_finish"); + expect(rejected.result.isError).toBe(true); + expect(coercions()).toEqual([]); + const sent = { ...report, reportedWorkDisposition: "yielded", continuation }; + expect((await call(bridge, "y1", sent, "paperclip_finish")).result.isError).toBeUndefined(); + expect((await call(bridge, "y1", sent, "paperclip_finish")).result.isError).toBeUndefined(); + expect(handler).toHaveBeenCalledOnce(); + expect(coercions()).toHaveLength(1); + }); + + it("never parses text in a field that accepts text, nor text that is not an object", async () => { + const handler = vi.fn(async () => ({ ok: true })); + const bridge = await startOpenCodeMcpBridge({ tools: [{ name: "note", inputSchema: { + type: "object", required: ["body", "options"], additionalProperties: false, + properties: { body: { type: "string" }, options: { type: "object", required: ["mode"], properties: { mode: { type: "string" } } } }, + } }], handler }); + bridges.push(bridge); + const body = '{"mode":"x"}'; + expect((await call(bridge, "n1", { body, options: '{"mode":"fast"}' }, "note")).result.isError).toBeUndefined(); + expect(handler).toHaveBeenLastCalledWith(expect.objectContaining({ arguments: { body, options: { mode: "fast" } } })); + for (const [id, options] of [["n2", "[1]"], ["n3", "fast"], ["n4", '{"mode":']]) { + const rejected = await call(bridge, id, { body, options }, "note"); + expect(rejected.result.isError).toBe(true); + expect(rejected.result.content[0]!.text).toContain("/options must be object"); + } + // Parsed text that is still invalid is reported by what is wrong inside it. + const inner = await call(bridge, "n5", { body, options: '{"mode":1}' }, "note"); + expect(inner.result.content[0]!.text).toBe("Invalid tool input: /options/mode must be string"); + expect(handler).toHaveBeenCalledOnce(); + }); + + it("parses object items sent as JSON text inside arrays, and never parses text items", async () => { + const handler = vi.fn(async () => ({ accepted: true })); + const diagnostics: string[] = []; + const bridge = await startOpenCodeMcpBridge({ handler, onDiagnostic: message => diagnostics.push(message) }); + bridges.push(bridge); + const claim = { contractRevision: "r", objectiveSatisfied: true, criteria: [], remainingWork: [{ description: "Polish copy", blocksCompletion: false }] }; + const sent = { summary: "s", reportedWorkDisposition: "done", verification: [], + evidence: [JSON.stringify({ ref: "doc:plan" })], + completionClaim: { ...claim, remainingWork: [JSON.stringify(claim.remainingWork[0])] } }; + expect((await call(bridge, "a1", sent, "paperclip_finish")).result.isError).toBeUndefined(); + expect(handler).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ arguments: { + ...sent, evidence: [{ ref: "doc:plan" }], completionClaim: claim, + } })); + const coerced = diagnostics.map(message => JSON.parse(message)).filter(entry => entry.schema === "paperclip.runner.tool-input-coerced/v1"); + expect(coerced).toEqual([expect.objectContaining({ paths: ["/evidence/0", "/completionClaim/remainingWork/0"] })]); + + const tags = await startOpenCodeMcpBridge({ tools: [{ name: "tag", inputSchema: { + type: "object", required: ["labels"], properties: { labels: { type: "array", items: { type: "string" } } }, + } }], handler }); + bridges.push(tags); + expect((await call(tags, "t1", { labels: ['{"a":1}'] }, "tag")).result.isError).toBeUndefined(); + expect(handler).toHaveBeenLastCalledWith(expect.objectContaining({ arguments: { labels: ['{"a":1}'] } })); + }); + + it("says that fields with the wrong type arrived instead of saying they did not arrive", async () => { + const bridge = await startOpenCodeMcpBridge({ handler: async () => ({ accepted: true }) }); + bridges.push(bridge); + const report = { summary: "s", completionClaim: { contractRevision: "r", objectiveSatisfied: true, criteria: [], remainingWork: [] }, evidence: [], verification: [] }; + const args = { ...report, reportedWorkDisposition: "yielded", continuation: "wait for the reply" }; + await call(bridge, "w1", args, "paperclip_finish"); + const second = (await call(bridge, "w2", args, "paperclip_finish")).result.content[0]!.text; + expect(second).toContain("This exact call has now been rejected 2 times"); + expect(second).toContain("Every field you sent arrived, but one has the wrong type: continuation must be an object or null, not text (send the object itself, not its JSON as quoted text)."); + expect(second).not.toContain("did not arrive"); + const third = (await call(bridge, "w3", args, "paperclip_finish")).result.content[0]!.text; + expect(third).toContain("continuation must be an object or null, not text"); + expect(third).not.toContain("did not arrive"); + }); + it("applies the completion tool's continuation rule outside its advertised schema", async () => { const bridge = await startOpenCodeMcpBridge({ handler: async () => ({ accepted: true }) }); bridges.push(bridge); diff --git a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts index c3f603f7153..5e947b226bc 100644 --- a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts +++ b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts @@ -4,6 +4,7 @@ import type { Socket } from "node:net"; import type { ValidateFunction } from "ajv/dist/2020.js"; import { admitToolInputSchema } from "../tool-input-schema.js"; import { toolInputError } from "../tool-input-error.js"; +import { admitToolInput, TOOL_INPUT_COERCION_DIAGNOSTIC_SCHEMA } from "../tool-input-coercion.js"; import { RepeatedToolInputRejectionGuard } from "../repeated-tool-input-rejection.js"; import { toolInputVariantError } from "../../contracts/tool-input-variants.js"; @@ -63,6 +64,7 @@ const DEFAULT_MAX_BODY_BYTES = 1_048_576; const MAX_RESULT_BYTES = 1_048_576; const TOOL_DELIVERY_DIAGNOSTIC_SCHEMA = "paperclip.opencode.tool-delivery-diagnostic/v1"; const MAX_TOOL_DELIVERY_DIAGNOSTICS = 256; +const MAX_TOOL_INPUT_COERCION_DIAGNOSTICS = 64; type SocketUse = { requests: number; lastResponseAt: number | null }; type ToolDelivery = { @@ -109,6 +111,20 @@ export async function startOpenCodeMcpBridge( }; try { options.onDiagnostic(JSON.stringify(diagnostic)); } catch { /* Optional diagnostics never change admission. */ } }; + let coercionDiagnostics = 0; + // Records each call accepted only after an object-typed field sent as JSON + // text was parsed back into its object. Names fields, never their values. + const diagnoseInputCoercion = (tool: string, callId: string, paths: string[]) => { + if (!options.onDiagnostic || coercionDiagnostics++ >= MAX_TOOL_INPUT_COERCION_DIAGNOSTICS) return; + const diagnostic = { + schema: TOOL_INPUT_COERCION_DIAGNOSTIC_SCHEMA, + tool, + callIdSha256: createHash("sha256").update(callId).digest("hex"), + coercion: "json_string_to_object", + paths, + }; + try { options.onDiagnostic(JSON.stringify(diagnostic)); } catch { /* Optional diagnostics never change admission. */ } + }; let deliveryDiagnostics = 0; const diagnoseToolDelivery = ( callId: string, @@ -154,6 +170,7 @@ export async function startOpenCodeMcpBridge( handler: options.handler, onRejectedCall: options.onRejectedCall, diagnoseFinishInput, + diagnoseInputCoercion, timeoutMs: options.timeoutMs === null ? null : options.timeoutMs ?? DEFAULT_TIMEOUT_MS, privateToolTimeoutMs: options.privateToolTimeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS, privateToolNames: new Set(privateTools.map((tool) => tool.name)), @@ -248,6 +265,7 @@ async function handleRequest( privateToolNames: ReadonlySet; maxBodyBytes: number; diagnoseFinishInput: (rejection?: FinishInputRejection) => void; + diagnoseInputCoercion: (tool: string, callId: string, paths: string[]) => void; }, ): Promise { setSecurityHeaders(response); @@ -342,9 +360,10 @@ async function handleRequest( writeRpc(response, id, { isError: true, content: [{ type: "text", text: "Unsupported tool." }] }); return; } - const args = params.arguments ?? {}; + const received = params.arguments ?? {}; const validator = context.validators.get(tool); - const schemaValid = validator !== undefined && validator(args); + const admitted = admitToolInput(validator, received); + const { args, schemaValid } = admitted; // The completion tool's yielded-only continuation rule is not part of its // advertised schema; some hosts hide a root conditional's arguments. const variantError = schemaValid && tool === PRP_COMPLETION_TOOL_NAME ? toolInputVariantError(tool, args) : null; @@ -379,6 +398,7 @@ async function handleRequest( context.privateToolNames.has(tool) ? context.privateToolTimeoutMs : context.timeoutMs, ); if (!existing) { + if (admitted.coercedPaths) context.diagnoseInputCoercion(tool, callId, admitted.coercedPaths); if (context.calls.size >= 2_048) context.calls.delete(context.calls.keys().next().value!); context.calls.set(callId, { fingerprint, promise: execution, waiting: new Set() }); context.controllers.set(callId, controller!); diff --git a/packages/paperclip-runner/src/drivers/repeated-tool-input-rejection.ts b/packages/paperclip-runner/src/drivers/repeated-tool-input-rejection.ts index a25ac4666b1..ecf61cc61a5 100644 --- a/packages/paperclip-runner/src/drivers/repeated-tool-input-rejection.ts +++ b/packages/paperclip-runner/src/drivers/repeated-tool-input-rejection.ts @@ -1,5 +1,6 @@ import { createHash } from "node:crypto"; import { semanticCanonicalJson } from "./semantic-tool-receipt.js"; +import { declaredSchemaTypes, jsonValueType, matchesDeclaredType } from "./tool-input-coercion.js"; /** Identical rejections after which the guard tells the model to stop. */ export const REPEATED_TOOL_INPUT_REJECTION_LIMIT = 2; @@ -37,11 +38,11 @@ export class RepeatedToolInputRejectionGuard { const expected = expectedProperties(schema); if (count === REPEATED_TOOL_INPUT_REJECTION_LIMIT) { return `${error} This exact call has now been rejected ${count} times with the same arguments. ${receivedArguments(args)}${expected ? ` ${expected}` : ""} ` - + `If you meant to send other arguments, they did not arrive: send every field as a top-level argument of ${tool} in one call. ` + + `${inputProblem(tool, args, schema)} ` + "An identical call will not be accepted again in this run. Change the arguments, or stop and tell the user what blocked you."; } return `This call was not accepted: ${tool} was already rejected ${count - 1} times in this run with these exact arguments. ${receivedArguments(args)}${expected ? ` ${expected}` : ""} ` - + `The error each time was: ${error} Repeating it unchanged cannot succeed. Stop calling ${tool} with these arguments: change them, or stop and tell the user what blocked you.`; + + `The error each time was: ${error} ${inputProblem(tool, args, schema)} Repeating it unchanged cannot succeed. Stop calling ${tool} with these arguments: change them, or stop and tell the user what blocked you.`; } } @@ -69,3 +70,44 @@ export function expectedProperties(schema: unknown): string { const optional = properties.filter(key => !required.includes(key)); return `Expected properties: ${required.length ? `required ${names(required)}` : "none required"}${optional.length ? `; optional ${names(optional)}` : ""}.`; } + +const TYPE_NAMES: Record = { + object: "an object", array: "an array", string: "text", number: "a number", integer: "a whole number", boolean: "true or false", null: "null", +}; + +function typeList(types: readonly string[]): string { + const named = types.map(type => TYPE_NAMES[type] ?? type); + return named.length <= 1 ? named.join("") : `${named.slice(0, -1).join(", ")} or ${named.at(-1)}`; +} + +/** + * Names what is actually wrong with the repeated call. Required fields that + * are absent may have been dropped by the host; fields that arrived with the + * wrong type did arrive and must be sent differently. Telling a model that + * sent every field that its arguments "did not arrive" sends it looking for + * the wrong fault. + */ +export function inputProblem(tool: string, args: unknown, schema: unknown): string { + const root = typeof schema === "object" && schema !== null ? schema as Schema : {}; + const properties = typeof root.properties === "object" && root.properties !== null ? root.properties as Record : {}; + const received = typeof args === "object" && args !== null && !Array.isArray(args) ? args as Record : {}; + const required = Array.isArray(root.required) ? root.required.filter((key): key is string => typeof key === "string") : []; + const missing = required.filter(key => !Object.hasOwn(received, key)); + const wrongTypes = Object.keys(received).sort() + .filter(key => Object.hasOwn(properties, key) && !matchesDeclaredType(properties[key], received[key])) + .slice(0, MAX_LISTED) + .map(key => { + const actual = jsonValueType(received[key]); + const encoded = actual === "string" && declaredSchemaTypes(properties[key])?.includes("object") ? " (send the object itself, not its JSON as quoted text)" : ""; + return `${key} must be ${typeList(declaredSchemaTypes(properties[key]) ?? [])}, not ${TYPE_NAMES[actual] ?? actual}${encoded}`; + }); + const parts: string[] = []; + if (missing.length) { + parts.push(`Required ${missing.length === 1 ? "field" : "fields"} ${names(missing)} did not arrive; if you sent ${missing.length === 1 ? "it" : "them"}, send every field as a top-level argument of ${tool} in one call.`); + } + if (wrongTypes.length) { + parts.push(`${missing.length ? "The fields you did send arrived" : "Every field you sent arrived"}, but ${wrongTypes.length === 1 ? "one has" : "some have"} the wrong type: ${wrongTypes.join("; ")}.`); + } + if (!parts.length) parts.push("Every field you sent arrived; change the values the error names."); + return parts.join(" "); +} diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts index 44855fad482..d1414296904 100644 --- a/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts @@ -788,3 +788,45 @@ describe("runner bridge repeated identical input rejections", () => { expect(handler).not.toHaveBeenCalled(); }); }); + +describe("runner bridge input coercion", () => { + it("accepts an object-typed field sent as JSON text, records it, and keeps text fields as text", async () => { + const handler = vi.fn(async () => ({ ok: true })); + const diagnostics: string[] = []; + const bridge = await startRunnerToolBridge({ + tools: [{ name: "update_case", inputSchema: { type: "object", additionalProperties: false, required: ["title", "patch"], properties: { + title: { type: "string" }, patch: { type: ["object", "null"], required: ["status"], properties: { status: { type: "string" } } }, + } } }], + handler, + onDiagnostic: message => diagnostics.push(message), + }); + bridges.push(bridge); + const send = async (id: number, args: unknown) => ((await (await rpc(bridge, { id, method: "tools/call", params: { name: "update_case", arguments: args } })).json()) as { + result: { isError?: boolean; content: Array<{ text: string }> }; + }).result; + expect((await send(1, { title: '{"a":1}', patch: '{"status":"done"}' })).isError).not.toBe(true); + expect(handler).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ arguments: { title: '{"a":1}', patch: { status: "done" } } })); + expect(diagnostics.map(message => JSON.parse(message))).toEqual([ + expect.objectContaining({ schema: "paperclip.runner.tool-input-coerced/v1", tool: "update_case", paths: ["/patch"] }), + ]); + expect((await send(2, { title: "t", patch: "done" })).isError).toBe(true); + expect(handler).toHaveBeenCalledOnce(); + }); +}); + +describe("runner bridge receipts for coerced input", () => { + it("binds the receipt to the arguments as the host sent them, while the handler gets the parsed object", async () => { + const receipts: SemanticToolReceipt[] = []; + const handler = vi.fn(async () => ({ accepted: true })); + const bridge = await startRunnerToolBridge({ captureSemanticReceipt: () => receipt => receipts.push(receipt), handler }); + bridges.push(bridge); + const continuation = { kind: "response_wake", summary: "wait", idempotencyKey: "k" }; + const raw = { reportedWorkDisposition: "yielded", summary: "Waiting for the reply.", evidence: [], verification: [], + completionClaim: { contractRevision: "1", objectiveSatisfied: false, criteria: [], remainingWork: [] }, continuation: JSON.stringify(continuation) }; + const body = await (await rpc(bridge, { id: 9, method: "tools/call", params: { name: "paperclip_finish", arguments: raw } })).json() as ToolCallBody; + expect(handler).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ arguments: { ...raw, continuation } })); + expect(receipts).toHaveLength(1); + expect(readNativeSemanticReceipt({ contents: body.result.content })).toEqual(receipts[0]); + expect(receipts[0]!.inputSha256).toBe(semanticInputSha256(raw)); + }); +}); diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts index a049b866094..7ccabc60adc 100644 --- a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts @@ -10,6 +10,7 @@ import { import type { ValidateFunction } from "ajv/dist/2020.js"; import { admitToolInputSchema } from "./tool-input-schema.js"; import { toolInputError } from "./tool-input-error.js"; +import { admitToolInput, TOOL_INPUT_COERCION_DIAGNOSTIC_SCHEMA } from "./tool-input-coercion.js"; import { RepeatedToolInputRejectionGuard } from "./repeated-tool-input-rejection.js"; import { toolInputVariantError } from "../contracts/tool-input-variants.js"; @@ -64,6 +65,8 @@ export interface RunnerToolBridgeOptions { socketPath?: string; sessionScope?: () => string | null; scopeToken?: () => string | null; + /** Receives one JSON diagnostic per call accepted after input coercion. */ + onDiagnostic?: (message: string) => void; } export interface RunnerToolBridge { @@ -107,6 +110,22 @@ const RESERVED_TOOLS: readonly RunnerToolDefinition[] = [ }, ]; +function inputCoercionDiagnostics(onDiagnostic: ((message: string) => void) | undefined) { + let recorded = 0; + // Names the coerced fields, never their values. + return (tool: string, callId: string, paths: string[]) => { + if (!onDiagnostic || recorded++ >= 64) return; + const diagnostic = { + schema: TOOL_INPUT_COERCION_DIAGNOSTIC_SCHEMA, + tool, + callIdSha256: createHash("sha256").update(callId).digest("hex"), + coercion: "json_string_to_object", + paths, + }; + try { onDiagnostic(JSON.stringify(diagnostic)); } catch { /* Optional diagnostics never change admission. */ } + }; +} + export function canonicalRunnerToolName(name: string): string { const trimmed = name.trim(); if (trimmed === PRP_COMPLETION_TOOL_NAME || trimmed === PRP_BLOCK_TOOL_NAME) { @@ -154,6 +173,7 @@ export async function startRunnerToolBridge( admittedTools: new Map(admittedTools.map((tool) => [tool.name, tool])), validators, rejections: new RepeatedToolInputRejectionGuard(), + diagnoseInputCoercion: inputCoercionDiagnostics(options.onDiagnostic), calls, controllers, requestCalls: new Map(), @@ -246,6 +266,7 @@ async function handleRequest( admittedTools: Map; validators: Map; rejections: RepeatedToolInputRejectionGuard; + diagnoseInputCoercion: (tool: string, callId: string, paths: string[]) => void; calls: Map; controllers: Map; requestCalls: Map; @@ -393,9 +414,11 @@ async function handleRequest( const requestKey = sessionKey + rpcIdKey(id); const callKey = providerToolUseId === undefined ? requestKey : `tool-use:${providerToolUseId}`; const cancelKey = mcpSessionKey(request) + requestKey; - const args = params.arguments ?? {}; const validator = context.validators.get(tool); - const rejection = validator === undefined || !validator(args) + const received = params.arguments ?? {}; + const admitted = admitToolInput(validator, received); + const { args } = admitted; + const rejection = !admitted.schemaValid ? toolInputError(validator, args) // The completion tool's yielded-only continuation rule is not part of its // advertised schema; some hosts hide a root conditional's arguments. @@ -450,11 +473,13 @@ async function handleRequest( if (!normalizationInvalid) normalizedInputSha256 = digest; }; }; + // The receipt binds the arguments as the host sent them, which a provider + // compares with its own raw input; the handler gets any coerced form. const withReceipt = (result: RunnerToolCallResult): RunnerToolCallResult => { receiptSealed = true; if (!context.captureSemanticReceipt) return result; try { - const bound = appendSemanticToolReceipt({ tool, callId, arguments: args, normalizedInputSha256: normalizationInvalid ? null : normalizedInputSha256 }, result); + const bound = appendSemanticToolReceipt({ tool, callId, arguments: received, normalizedInputSha256: normalizationInvalid ? null : normalizedInputSha256 }, result); try { observeReceipt?.(bound.receipt); } catch { /* Evidence cannot change the tool outcome. */ } return bound.result; } catch { return result; } @@ -484,6 +509,7 @@ async function handleRequest( return withReceipt({ isError: true, content: [{ type: "text", text: safeError(error) }] }); }); if (!existing) { + if (admitted.coercedPaths) context.diagnoseInputCoercion(tool, callId, admitted.coercedPaths); context.calls.set(callKey, { fingerprint, promise: execution }); context.controllers.set(callKey, controller!); void execution diff --git a/packages/paperclip-runner/src/drivers/tool-input-coercion.ts b/packages/paperclip-runner/src/drivers/tool-input-coercion.ts new file mode 100644 index 00000000000..8434bebc00a --- /dev/null +++ b/packages/paperclip-runner/src/drivers/tool-input-coercion.ts @@ -0,0 +1,155 @@ +import type { ValidateFunction } from "ajv/dist/2020.js"; + +type SchemaNode = { type?: unknown; properties?: unknown; items?: unknown }; + +export type JsonValueType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null"; + +export type ToolInputCoercion = { + /** A copy of the input with each coerced field replaced by its parsed object. */ + input: unknown; + /** JSON Pointer paths of the coerced fields, for example `/continuation`. */ + paths: string[]; +}; + +const MAX_DEPTH = 8; + +function node(schema: unknown): SchemaNode | undefined { + return typeof schema === "object" && schema !== null && !Array.isArray(schema) ? schema as SchemaNode : undefined; +} + +function isPlainObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +/** The JSON types a schema node declares through `type`, or null when it declares none. */ +export function declaredSchemaTypes(schema: unknown): string[] | null { + const type = node(schema)?.type; + if (typeof type === "string") return [type]; + if (Array.isArray(type) && type.length > 0 && type.every(entry => typeof entry === "string")) return type as string[]; + return null; +} + +export function jsonValueType(value: unknown): JsonValueType { + if (value === null) return "null"; + if (Array.isArray(value)) return "array"; + if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number"; + if (typeof value === "string" || typeof value === "boolean" || typeof value === "object") return typeof value as JsonValueType; + return "null"; +} + +/** Whether a value has one of the types a schema node declares; true when it declares none. */ +export function matchesDeclaredType(schema: unknown, value: unknown): boolean { + const types = declaredSchemaTypes(schema); + if (types === null) return true; + const actual = jsonValueType(value); + return types.includes(actual) || (actual === "integer" && types.includes("number")); +} + +function parseObject(text: string): Record | null { + const trimmed = text.trim(); + if (!trimmed.startsWith("{")) return null; + try { + const parsed: unknown = JSON.parse(trimmed); + return isPlainObject(parsed) ? parsed : null; + } catch { + return null; + } +} + +function escapePointer(key: string): string { + return key.replace(/~/g, "~0").replace(/\//g, "~1"); +} + +function coerceValue(schema: SchemaNode | undefined, value: unknown, path: string, paths: string[], depth: number): unknown { + if (depth > MAX_DEPTH) return value; + const types = declaredSchemaTypes(schema); + let next = value; + // Only a value that can never be a string is read as encoded JSON: a + // string there is invalid, so parsing it cannot replace a valid meaning. + if (typeof value === "string" && types?.includes("object") && !types.includes("string")) { + const parsed = parseObject(value); + if (parsed === null) return value; + paths.push(path); + next = parsed; + } + if (isPlainObject(next) && (types === null || types.includes("object"))) return coerceObject(schema, next, path, paths, depth); + if (Array.isArray(next) && types?.includes("array")) { + const items = node(schema?.items); + if (!items) return next; + let result = next; + next.forEach((entry, index) => { + const coerced = coerceValue(items, entry, `${path}/${index}`, paths, depth + 1); + if (coerced !== entry) { + if (result === next) result = [...next]; + result[index] = coerced; + } + }); + return result; + } + return next; +} + +function coerceObject( + schema: SchemaNode | undefined, + value: Record, + path: string, + paths: string[], + depth: number, +): Record { + const properties = isPlainObject(schema?.properties) ? schema.properties : undefined; + if (!properties || depth > MAX_DEPTH) return value; + let result = value; + for (const [key, entry] of Object.entries(value)) { + if (!Object.hasOwn(properties, key)) continue; + const next = coerceValue(node(properties[key]), entry, `${path}/${escapePointer(key)}`, paths, depth + 1); + if (next !== entry) { + if (result === value) result = { ...value }; + result[key] = next; + } + } + return result; +} + +/** + * Some model hosts send an object-typed tool argument as its JSON text, for + * example `continuation: "{\"kind\":\"response_wake\"}"`. Returns a copy of + * the input with each such string parsed back into the object it encodes, or + * null when nothing qualifies. A field is coerced only when its schema + * declares `object` and does not allow `string`, and the text parses to a + * plain JSON object, so a valid string is never reinterpreted. The caller + * must still validate the result before dispatching it. + */ +export function coerceJsonStringObjects(schema: unknown, input: unknown): ToolInputCoercion | null { + if (!isPlainObject(input)) return null; + const paths: string[] = []; + const coerced = coerceObject(node(schema), input, "", paths, 0); + return paths.length > 0 ? { input: coerced, paths } : null; +} + +/** The run-event diagnostic recorded when a bridge accepts a coerced call. */ +export const TOOL_INPUT_COERCION_DIAGNOSTIC_SCHEMA = "paperclip.runner.tool-input-coerced/v1"; +/** The run-event diagnostic code a driver records a runner tool bridge diagnostic under. */ +export const RUNNER_TOOL_BRIDGE_DIAGNOSTIC_CODE = "runner_tool_bridge_diagnostic"; + +export type AdmittedToolInput = { + /** The arguments to dispatch: the coerced copy when coercion made them valid, otherwise what arrived. */ + args: unknown; + schemaValid: boolean; + /** Set only when the call was accepted because of coercion. */ + coercedPaths?: string[]; +}; + +/** + * Validate tool arguments, accepting an object-typed field sent as JSON text + * when parsing it makes the whole call valid. When the call stays invalid, + * `validator.errors` describe the parsed form, so the model is told what is + * wrong inside the object rather than only that it arrived as text. + */ +export function admitToolInput(validator: ValidateFunction | undefined, received: unknown): AdmittedToolInput { + if (validator === undefined) return { args: received, schemaValid: false }; + if (validator(received)) return { args: received, schemaValid: true }; + const coerced = coerceJsonStringObjects(validator.schema, received); + if (coerced === null) return { args: received, schemaValid: false }; + if (validator(coerced.input)) return { args: coerced.input, schemaValid: true, coercedPaths: coerced.paths }; + return { args: received, schemaValid: false }; +}