mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
fix(runner): accept object fields sent as JSON text and name wrong-type rejections (#21485)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Paperclip runner checks each tool call from the model against the tool's input schema before it sends the call to the control plane > - Some model hosts send an object argument as its JSON text. On the DigitalOcean host, `paperclip_finish` arrived with `continuation` as a string > - The runner rejected these calls, and the repeated-rejection guard then told the model that its arguments "did not arrive", which is wrong when every field arrived with the wrong type > - This pull request makes the runner parse such a string back into its object when that is safe, records each coercion as a run event, and makes the guard name the actual problem > - The benefit is fewer stuck finish calls, and guidance that points the model at the real fault ## Linked Issues or Issue Description Refs #21398 **What happened?** Chat-eval cohort 13 ran OpenCode with `openrouter/deepseek/deepseek-v4.1-flash-1017` on master `df1b12ad8e`. On the DigitalOcean host, 6 of the 8 remaining "Invalid tool input" rejections were `paperclip_finish` calls with `continuation` sent as a JSON string (`/continuation must be object,null`). Examples: `gateways-profiles.rotate-token`, `instance-operations.restart-service`, and `questions-and-approvals.multi-part-question`. The run diagnostic recorded `continuationShape: "string"`. After the second identical rejection, the guard from #21398 said "If you meant to send other arguments, they did not arrive". Every argument had arrived; one had the wrong type. **Expected behavior** When a schema field is object-typed, does not allow text, and the text parses to a plain JSON object that makes the call valid, the runner accepts the call with the parsed object and logs a run event. When a call stays invalid, the guard says which required fields are missing and which fields have the wrong type. **Steps to reproduce** 1. Start the OpenCode MCP bridge. 2. Call `paperclip_finish` with `reportedWorkDisposition: "yielded"` and `continuation` as `JSON.stringify({ kind: "response_wake", ... })`. 3. Before this change, the bridge returns `Invalid tool input: /continuation must be object,null`. ## What Changed - Added `packages/paperclip-runner/src/drivers/tool-input-coercion.ts`. `admitToolInput` validates the arguments. If they are invalid, it parses a string in an object-typed field back into its object. It does this only when the field's schema declares `object`, does not allow `string`, the text parses to a plain JSON object, and the whole coerced call validates. It applies to any object-typed field at any depth, not only `continuation`. - The OpenCode MCP bridge and the runner tool bridge use `admitToolInput`. They dispatch the coerced arguments, and they send one `paperclip.runner.tool-input-coerced/v1` diagnostic per accepted coercion. The OpenCode driver already records bridge diagnostics as run events. The diagnostic names the tool and the field paths. It never contains the values. The runner tool bridge has a new optional `onDiagnostic` option. - When parsed text is still invalid, the rejection describes what is wrong inside the parsed object, for example `/options/mode must be string`. - The repeated-rejection guard now says "Required fields X did not arrive" only for missing required fields. For fields with the wrong type, it says "Every field you sent arrived, but one has the wrong type: continuation must be an object or null, not text". ## Verification - `cd packages/paperclip-runner && npx vitest run src/drivers/opencode/mcp-bridge.test.ts src/drivers/runner-tool-bridge.test.ts` (63 tests pass). - Red/green: with the source changes reverted and the new tests kept, 5 tests fail: coercion acceptance and its run event (both bridges), no coercion for text fields or non-object text, the wrong-type guard wording, and the missing-field guard wording. With the change, all of them pass. - `npx tsc --noEmit -p packages/paperclip-runner` passes. - A narrow paid run of `questions-and-approvals.multi-part-question`, `runs-adapters.inspect-failed-run` and `budgets-costs.explain-hard-stop` ran on a branch that combines this PR with the two sibling cohort-13 PRs. The results are in a PR comment. ## Risks - Low risk. Coercion runs only after a call fails validation, and the call is accepted only if the coerced form validates. A field that allows text is never parsed, so a valid string never changes meaning. - Previous-release story (upgrade-safe run state): this change adds no persisted run, session, launch or pack state. It changes only how one in-flight tool call is admitted. Saved state carries forward unchanged. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude Code with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2756be2f32
commit
2a8b485140
14 files changed
+489
-9
No files matched your search
@@ -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: {");
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]);
|
||||
});
|
||||
@@ -3,6 +3,7 @@ export function createOpenCodeFinishDiagnosticForwarder(send: (frame: Warning) =
|
||||
let threadId: string | undefined;
|
||||
let offered: Record<string, unknown> | undefined;
|
||||
let rejections = 0;
|
||||
let coercions = 0;
|
||||
const emit = (value: Record<string, unknown>) => {
|
||||
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<string, unknown>): 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<string, unknown>): 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));
|
||||
}
|
||||
@@ -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,
|
||||
|
||||
@@ -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<unknown> {
|
||||
this.#assertOpen();
|
||||
if (this.#pendingTerminal) {
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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<string>;
|
||||
maxBodyBytes: number;
|
||||
diagnoseFinishInput: (rejection?: FinishInputRejection) => void;
|
||||
diagnoseInputCoercion: (tool: string, callId: string, paths: string[]) => void;
|
||||
},
|
||||
): Promise<void> {
|
||||
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!);
|
||||
|
||||
@@ -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<string, string> = {
|
||||
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<string, unknown> : {};
|
||||
const received = typeof args === "object" && args !== null && !Array.isArray(args) ? args as Record<string, unknown> : {};
|
||||
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(" ");
|
||||
}
|
||||
@@ -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));
|
||||
});
|
||||
});
|
||||
@@ -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<string, string>(),
|
||||
@@ -246,6 +266,7 @@ async function handleRequest(
|
||||
admittedTools: Map<string, RunnerToolDefinition>;
|
||||
validators: Map<string, ValidateFunction>;
|
||||
rejections: RepeatedToolInputRejectionGuard;
|
||||
diagnoseInputCoercion: (tool: string, callId: string, paths: string[]) => void;
|
||||
calls: Map<string, AdmittedCall>;
|
||||
controllers: Map<string, AbortController>;
|
||||
requestCalls: Map<string, string>;
|
||||
@@ -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
|
||||
|
||||
@@ -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<string, unknown> {
|
||||
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<string, unknown> | 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<string, unknown>,
|
||||
path: string,
|
||||
paths: string[],
|
||||
depth: number,
|
||||
): Record<string, unknown> {
|
||||
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 };
|
||||
}
|
||||
Reference in new issue
Block a user