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 6a7be569b2b..753892126c1 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.test.ts @@ -7,6 +7,7 @@ import { acpxProfileActivity } from "../drivers/acpx/profile-activity.js"; import { redactObservabilityDiagnostic } from "../drivers/agent-observability.js"; import { appendSemanticToolReceipt, readNativeSemanticReceipt, semanticInputSha256 } from "../drivers/semantic-tool-receipt.js"; import { startRunnerToolBridge, type RunnerToolCall } from "../drivers/runner-tool-bridge.js"; +import { CLAUDE_TOOL_USE_META_KEY, ClaudeToolUseAdmission } from "../drivers/acpx/claude-tool-use-admission.js"; import { validatePrpStructuredRunResult } from "../protocol/replay-contract.js"; import { resolveCompletionContinuation } from "../drivers/completion-continuation.js"; import { acpxUsageEstimateNotice, persistedAcpxTurnUsage, persistedCursorUsageNotice, qualifiedAcpxUsageBreakdown } from "../drivers/acpx/usage-accounting.js"; @@ -381,15 +382,15 @@ describe("qualified ACPX runtime sidecar", () => { const events: unknown[] = []; let active = true; const evidence = createCopilotToolEvidence({ sessionId: "session-a", turnId: "turn-a", workingDirectory: "/workspace", active: () => active, emit: event => { validateAcpxRichEvent(event); events.push(event); } }); - const create = new Function("params", "activeCopilotEvidence", "waitForTool", `return ({ ${source.slice(start, end)} }).semanticTools;`); - const options = create({ agent: "copilot", tools: [] }, evidence, () => undefined); + const create = new Function("params", "activeCopilotEvidence", "waitForTool", "CLAUDE_TOOL_USE_META_KEY", `return ({ ${source.slice(start, end)} }).semanticTools;`); + const options = create({ agent: "copilot", tools: [] }, evidence, () => undefined, CLAUDE_TOOL_USE_META_KEY); const captured = options.captureSemanticReceipt(); const receipt = appendSemanticToolReceipt({ tool: "get_task_context", callId: "1", arguments: {} }, { content: [{ type: "text", text: "{}" }] }).receipt; captured(receipt); expect(events).toHaveLength(1); expect(events[0]).toMatchObject({ payload: { category: "paperclip_semantic_tool_receipt_v2", provenance: { sessionId: "session-a", turnId: "turn-a" } } }); active = false; captured(receipt); expect(events).toHaveLength(1); - for (const agent of ["cursor", "codex", "pi"]) expect(create({ agent, tools: [] }, evidence, () => undefined).captureSemanticReceipt).toBeUndefined(); + for (const agent of ["cursor", "codex", "pi"]) expect(create({ agent, tools: [] }, evidence, () => undefined, CLAUDE_TOOL_USE_META_KEY).captureSemanticReceipt).toBeUndefined(); }); it("keeps a native tool pending through controller downtime without a duplicate side effect", async () => { @@ -397,13 +398,13 @@ describe("qualified ACPX runtime sidecar", () => { const start = source.indexOf(" semanticTools: {"); const end = source.indexOf(" onGoalUpdate:", start); expect(start).toBeGreaterThan(0); expect(end).toBeGreaterThan(start); - const create = new Function("params", "activeCopilotEvidence", "waitForTool", `return ({ ${source.slice(start, end)} }).semanticTools;`); + const create = new Function("params", "activeCopilotEvidence", "waitForTool", "CLAUDE_TOOL_USE_META_KEY", `return ({ ${source.slice(start, end)} }).semanticTools;`); let admitted!: () => void, complete!: (value: unknown) => void; const started = new Promise(resolve => { admitted = resolve; }); const result = new Promise(resolve => { complete = resolve; }); let signal: AbortSignal | undefined; const handler = vi.fn((call: RunnerToolCall) => { signal = call.signal; admitted(); return result; }); - const bridge = await startRunnerToolBridge(create({ agent: "claude", tools: [{ name: "register_deliverable", inputSchema: { type: "object" } }] }, undefined, handler)); + const bridge = await startRunnerToolBridge(create({ agent: "claude", tools: [{ name: "register_deliverable", inputSchema: { type: "object" } }] }, undefined, handler, CLAUDE_TOOL_USE_META_KEY)); const call = () => fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "saved-call", method: "tools/call", params: { name: "register_deliverable", arguments: {} } }) }).then(response => response.json()); let first: Promise | undefined; @@ -491,6 +492,43 @@ describe("qualified ACPX runtime sidecar", () => { } }); + it("names an admitted Claude call by its announced tool use through the actual sidecar bridge options", async () => { + const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8"); + const start = source.indexOf(" semanticTools: {"), end = source.indexOf(" onGoalUpdate:", start); + const create = new Function("params", "activeCopilotEvidence", "waitForTool", "CLAUDE_TOOL_USE_META_KEY", `return ({ ${source.slice(start, end)} }).semanticTools;`); + const raw = { reportedWorkDisposition: "yielded", summary: "The review fix is published.", evidence: [], verification: [], + completionClaim: { contractRevision: "1", objectiveSatisfied: false, criteria: [], remainingWork: [{ description: "Wait for checks.", blocksCompletion: true }] } }; + const continuation = { kind: "monitor", summary: "Continue from saved task state.", idempotencyKey: "saved:task:receipt" }; + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("test-turn"); + const tools = new Map(), emitted: any[] = []; + const handler = loadWaitForTool({ tools, emitted, validate: validatePrpStructuredRunResult, callIdNamespace: "rgeneration1", toolUseAdmission: admission }); + const commands = loadActualToolCommands(tools); + const bridge = await startRunnerToolBridge(create({ agent: "claude", tools: [] }, undefined, handler, CLAUDE_TOOL_USE_META_KEY)); + const finish = (id: number, toolUseId?: string) => fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, + body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name: "paperclip_finish", arguments: raw, + ...(toolUseId ? { _meta: { [CLAUDE_TOOL_USE_META_KEY]: toolUseId, progressToken: id } } : {}) } }) }) + .then(response => response.json() as Promise); + try { + const missing = await finish(1); + expect(missing.result).toMatchObject({ isError: true, content: [{ text: "Paperclip tool call has no provider tool-use identity" }] }); + expect(emitted).toEqual([]); + admission.announce("test-turn", "toolu_01Finish"); + const response = finish(2, "toolu_01Finish"); + await vi.waitFor(() => expect(emitted.find(event => event.operationId === "get_task_context")).toBeDefined()); + expect(emitted[0].callId).toMatch(/^rgeneration1:continuation:/); + await commands.resolve({ callId: emitted[0].callId, turnId: "test-turn", result: { + run: { id: "test-run" }, activeTask: { executionRunId: "test-run" }, completionContinuation: continuation }, error: null }); + await vi.waitFor(() => expect(tools.has("tool-use:toolu_01Finish")).toBe(true)); + expect(emitted[1]).toMatchObject({ callId: "tool-use:toolu_01Finish", operationId: "paperclip_finish" }); + await commands.resolve({ callId: "tool-use:toolu_01Finish", turnId: "test-turn", result: { accepted: true }, error: null }); + expect((await response).result.isError).not.toBe(true); + } finally { + for (const pending of tools.values()) { pending.cleanup(); pending.reject(new Error("test cleanup")); } + await bridge.close(); + } + }); + it.each([["monitor", true], ["monitor", false], ["same_agent", true], ["same_agent", false]] as const)("resolves an omitted continuation before the production sidecar validator with saved %s authority=%s", async (kind, eligible) => { const raw = { reportedWorkDisposition: "yielded", summary: "The review fix is published.", evidence: [], verification: [], completionClaim: { contractRevision: "1", objectiveSatisfied: false, criteria: [], remainingWork: [{ description: "Wait for checks.", blocksCompletion: true }] } }; @@ -1116,6 +1154,103 @@ describe("qualified ACPX runtime sidecar", () => { } finally { await sidecar.close(); rmSync(root,{recursive:true,force:true}); } }, 15000); + it.each(["claude", "codex"] as const)("binds %s tool calls to the turn that announced their tool use", async agent => { + const root = mkdtempSync(join(tmpdir(), "acpx-tool-use-")); + const loader = join(root, "loader.mjs"), fixture = join(root, "host.mjs"); + const base = new URL("../test-support/acpx-blocked-output-host.mjs", import.meta.url).href; + const script = [ + [{ announce: "toolu_A" }, { call: "announced", toolUseId: "toolu_A" }, { await: "announced" }, + { call: "early", toolUseId: "toolu_B" }, { sleep: 50 }, { announce: "toolu_B" }, { await: "early" }, + { call: "missing" }, { await: "missing" }, + { announce: "toolu_C" }, + { call: "unannounced", toolUseId: "toolu_D" }, { sleep: 20 }], + [{ call: "previous-turn", toolUseId: "toolu_C" }, { call: "reused", toolUseId: "toolu_A" }, { await: "reused" }, + { announce: "toolu_agent" }, { announce: "toolu_child", parentToolUseId: "toolu_agent" }, + { call: "subagent", toolUseId: "toolu_child" }, { await: "subagent" }, { sleep: 20 }], + ]; + writeFileSync(join(root, "script.json"), JSON.stringify(script)); + writeFileSync(fixture, `import { AcpxRuntimeHost as Base } from ${JSON.stringify(base)}; + import { appendFileSync, readFileSync } from "node:fs"; + import { join } from "node:path"; + const root = process.env.PAPERCLIP_TEST_OUTPUT_ROOT; + const script = JSON.parse(readFileSync(join(root, "script.json"), "utf8")); + let turn = 0, rpc = 0; + export class AcpxRuntimeHost extends Base { + static async open(options) { const host = await Base.open(options); Object.setPrototypeOf(host, this.prototype); return host; } + startTurn({ requestId }) { + const handler = this.options.semanticTools.handler, steps = script[turn++], calls = new Map(); + return { requestId, promptStarted: Promise.resolve(), result: Promise.resolve({ status: "completed" }), + events: (async function* () { + for (const step of steps) { + if (step.announce) yield { type: "tool_call", tag: "tool_call", toolCallId: step.announce, title: "paperclip", status: "pending", + ...(step.parentToolUseId ? { _meta: { claudeCode: { parentToolUseId: step.parentToolUseId } } } : {}) }; + if (step.call) calls.set(step.call, handler({ callId: String(++rpc), tool: "call_api", arguments: {}, signal: new AbortController().signal, + ...(step.toolUseId ? { providerToolUseId: step.toolUseId } : {}) }) + .then(() => appendFileSync(join(root, "outcomes"), step.call + ":resolved\\n"), + error => appendFileSync(join(root, "outcomes"), step.call + ":" + error.message + "\\n"))); + if (step.await) await calls.get(step.await); + if (step.sleep) await new Promise(resolve => setTimeout(resolve, step.sleep)); + } + })() }; + } + }`); + writeFileSync(loader, `import { registerHooks } from "node:module"; import { pathToFileURL } from "node:url"; + registerHooks({resolve(specifier,context,next){ + if(context.parentURL?.includes("/acpx-runtime-sidecar.") && specifier.endsWith("/runtime-host.js")) + return {url:pathToFileURL(${JSON.stringify(fixture)}).href,shortCircuit:true}; + return next(specifier,context); + }});`); + const sidecar = new SidecarProcess({ loader, environment: { PAPERCLIP_TEST_OUTPUT_ROOT: root } }); + children.add(sidecar); + const model = agent === "claude" ? "claude-sonnet-5" : "gpt-5.6-sol"; + let id = 0; + const send = async (command: string, params: Record) => { + sidecar.write({ protocolVersion: ACPX_SIDECAR_PROTOCOL_VERSION, id: ++id, command, params }); + const sent = id; + expect(await sidecar.next(frame => frame.id === sent)).toMatchObject({ ok: true }); + }; + const resolveCall = async (turnId: string, callId: string) => { + await sidecar.next(frame => frame.eventType === "runtime.tool_called" && (frame.payload as Record).callId === callId); + await send("tool.resolve", { turnId, callId, result: { ok: true } }); + }; + const outcomes = () => Object.fromEntries(readFileSync(join(root, "outcomes"), "utf8").trim().split("\n") + .map(line => [line.slice(0, line.indexOf(":")), line.slice(line.indexOf(":") + 1)])); + try { + sidecar.write(initializeRequest(++id, agent, model)); + expect(await sidecar.next(frame => frame.id === 1)).toMatchObject({ ok: true }); + await send("session.open", { agent, model, runtimeDirectory: root, workingDirectory: root, + normalizedSessionId: "tool-use-session", permissionMode: "deny-all", systemInstructions: "Test tool-use binding.", tools: [] }); + await send("run.attach", { runId: "tool-use-run", catalogRevision: 1, tools: [] }); + await send("turn.start", { turnId: "turn-1", message: "First turn." }); + if (agent === "claude") { + await resolveCall("turn-1", "tool-use:toolu_A"); + await resolveCall("turn-1", "tool-use:toolu_B"); + } else { + for (const callId of ["1", "2", "3"]) await resolveCall("turn-1", callId); + } + expect(await sidecar.next(frame => frame.eventType === "runtime.turn_terminal")).toMatchObject({ turnId: "turn-1" }); + await send("turn.start", { turnId: "turn-2", message: "Second turn." }); + if (agent === "claude") await resolveCall("turn-2", "tool-use:toolu_child"); + else for (const callId of ["5", "6", "7"]) await resolveCall("turn-2", callId); + expect(await sidecar.next(frame => frame.eventType === "runtime.turn_terminal")).toMatchObject({ turnId: "turn-2" }); + await vi.waitFor(() => expect(Object.keys(outcomes())).toHaveLength(7)); + if (agent === "claude") { + expect(outcomes()).toEqual({ + announced: "resolved", early: "resolved", subagent: "resolved", + missing: "Paperclip tool call has no provider tool-use identity", + unannounced: "Paperclip tool call was not announced in the active turn", + "previous-turn": "Paperclip tool call was not announced in the active turn", + reused: "Paperclip tool call reused a provider tool-use identity", + }); + expect(sidecar.pending(frame => frame.eventType === "runtime.tool_called")).toBe(0); + } else { + expect(outcomes()).toMatchObject({ announced: "resolved", early: "resolved", missing: "resolved", + "previous-turn": "resolved", reused: "resolved", subagent: "resolved", + unannounced: "ACPX turn became terminal" }); + } + } finally { await sidecar.close(); rmSync(root, { recursive: true, force: true }); } + }, 15000); + it("forwards large app-tool arguments intact and refuses only a call over the tool-call limit", async () => { const root = mkdtempSync(join(tmpdir(), "acpx-large-arguments-")); const loader = join(root, "loader.mjs"), fixture = join(root, "host.mjs"); @@ -2065,6 +2200,7 @@ function loadWaitForTool(input: { validate?: typeof validatePrpStructuredRunResult; emit?: (eventType: string, payload: unknown) => boolean; callIdNamespace?: string | null; + toolUseAdmission?: ClaudeToolUseAdmission | null; }): (call: RunnerToolCall) => Promise { const source = readFileSync( fileURLToPath(new URL("./acpx-runtime-sidecar.ts", import.meta.url)), @@ -2077,7 +2213,7 @@ function loadWaitForTool(input: { const factory = new Function( "boundedIdentity", "tools", "turnId", "emit", "PRP_COMPLETION_TOOL_NAME", "PRP_BLOCK_TOOL_NAME", "validatePrpStructuredRunResult", "boundedSidecarValue", "record", "MAX_PENDING_TOOLS", "stringifyAcpxSidecarFrame", - "resolveCompletionContinuation", "runId", "normalizingTools", "randomUUID", "callIdNamespace", "MAX_EVENT_PAYLOAD_BYTES", + "resolveCompletionContinuation", "runId", "normalizingTools", "randomUUID", "callIdNamespace", "toolUseAdmission", "MAX_EVENT_PAYLOAD_BYTES", `return (${functionSource});`, ); return factory( @@ -2100,6 +2236,7 @@ function loadWaitForTool(input: { new Set(), randomUUID, input.callIdNamespace ?? null, + input.toolUseAdmission ?? null, 256 * 1024, ); } diff --git a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts index c0e8e6fd4ef..c488227f01c 100644 --- a/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts +++ b/packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts @@ -93,6 +93,7 @@ import { } from "../drivers/acpx/usage-accounting.js"; import { validatePrpStructuredRunResult } from "../protocol/replay-contract.js"; import type { RunnerToolCall } from "../drivers/runner-tool-bridge.js"; +import { CLAUDE_TOOL_USE_META_KEY, ClaudeToolUseAdmission } from "../drivers/acpx/claude-tool-use-admission.js"; import { acpxBootstrapBlockedError, acpxSidecarErrorCode, @@ -191,6 +192,7 @@ let turnStartedInProcess = false; * this process's ids to keep them distinct from calls earlier in the run. */ let callIdNamespace: string | null = null; +let toolUseAdmission: ClaudeToolUseAdmission | null = null; let activeCopilotEvidence: CopilotToolEvidence | undefined; let sequence = 0; let requestSequence = 0; @@ -306,6 +308,7 @@ async function dispatch( initializedAgent = agent; initializedModel = model; initializedCandidateAdmission = candidateAdmission; + toolUseAdmission = agent === "claude" ? new ClaudeToolUseAdmission() : null; return { protocolVersion: ACPX_SIDECAR_PROTOCOL_VERSION, sidecarPid: process.pid, @@ -371,6 +374,7 @@ async function dispatch( // turn a queued write into a provider-visible failure and retry. // Runner lease expiry, turn cancellation and bridge close own them. timeoutMs: null, + ...(params.agent === "claude" ? { providerToolUseIdMetaKey: CLAUDE_TOOL_USE_META_KEY } : {}), ...(params.agent === "copilot" ? { captureSemanticReceipt: () => activeCopilotEvidence?.captureSemanticReceipt() } : {}), }, onGoalUpdate: (goal) => { @@ -442,6 +446,7 @@ async function dispatch( const activeAgent = openParams!.agent; turnId = currentTurnId; turnStartedInProcess = true; + toolUseAdmission?.beginTurn(currentTurnId); turnControls.begin(currentTurnId); let runtimeTurn: AcpxRuntimeTurn; const extensions = bindAcpxExtensionTurn({ @@ -494,6 +499,7 @@ async function dispatch( }); } catch (error) { turnId = null; + toolUseAdmission?.endTurn(currentTurnId); throw error; } void pumpTurn(currentTurnId, runtimeTurn, activeHost, usageBefore, extensions.drain, activity, toolEvidence, sessionFailure); @@ -735,6 +741,7 @@ async function pumpTurn( ? createClaudeSubagentLineageTracker((id) => stableProviderIdentity(id, "tool")) : null; for await (const event of runtimeTurn.events) { + toolUseAdmission?.observe(currentTurnId, event); toolEvidence?.tool(event); // Claude hook lifecycle rides on session_info_update `_meta`; publish it // as schema-validated display activity rather than a raw status event. @@ -844,16 +851,24 @@ async function pumpTurn( emit("runtime.turn_terminal", terminal, currentTurnId); } -async function waitForTool(call: RunnerToolCall): Promise { +async function waitForTool(call: RunnerToolCall, internal = false): Promise { const activeTurnId = turnId; const activeRunId = runId; if (!activeTurnId || !activeRunId || call.signal.aborted) { throw new Error("ACPX tool call is not bound to an active turn"); } - const providerCallId = boundedIdentity(call.callId, "callId"); - const callId = callIdNamespace === null - ? providerCallId - : boundedIdentity(`${callIdNamespace}:${providerCallId}`, "callId"); + let callId: string; + if (toolUseAdmission && !internal) { + callId = boundedIdentity(await toolUseAdmission.admit(activeTurnId, call.providerToolUseId, call.signal), "callId"); + if (turnId !== activeTurnId || runId !== activeRunId || call.signal.aborted) { + throw new Error("ACPX tool call is not bound to an active turn"); + } + } else { + const providerCallId = boundedIdentity(call.callId, "callId"); + callId = callIdNamespace === null + ? providerCallId + : boundedIdentity(`${callIdNamespace}:${providerCallId}`, "callId"); + } if (tools.has(callId) || normalizingTools.has(callId)) throw new Error("ACPX tool call is duplicated"); const operationId = boundedIdentity(call.tool, "operationId"); if (tools.size + normalizingTools.size >= MAX_PENDING_TOOLS) { @@ -868,7 +883,7 @@ async function waitForTool(call: RunnerToolCall): Promise { try { completionInput = await resolveCompletionContinuation(call.arguments, activeRunId, () => waitForTool({ tool: "get_task_context", callId: `continuation:${randomUUID()}`, arguments: {}, signal: call.signal, - })); + }, true)); } finally { normalizingTools.delete(callId); } @@ -1105,6 +1120,7 @@ function elicitationResponse( } function rejectTurnWaiters(terminalTurnId: string, message: string): void { + toolUseAdmission?.endTurn(terminalTurnId); for (const [requestId, pending] of permissions) { if (pending.turnId !== terminalTurnId || !permissions.delete(requestId)) continue; pending.cleanup(); diff --git a/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts new file mode 100644 index 00000000000..9177861e604 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts @@ -0,0 +1,174 @@ +import { spawn } from "node:child_process"; +import { mkdir, mkdtemp, rm } from "node:fs/promises"; +import { createServer } from "node:http"; +import { createRequire } from "node:module"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { expect, it, vi } from "vitest"; + +import { startRunnerToolBridge } from "../runner-tool-bridge.js"; +import { openCodexAcpxRuntime } from "./acpx-runtime-adapter.js"; +import { CLAUDE_TOOL_USE_META_KEY, ClaudeToolUseAdmission } from "./claude-tool-use-admission.js"; +import type { VerifiedAcpxCommandLease } from "./installation-integrity.js"; +import { resolveQualifiedAcpxProfile } from "./qualified-profiles.js"; +import type { AcpxRuntimePortOpenOptions } from "./runtime-host.js"; + +type Block = { type: string; text?: string; tool_use_id?: string }; +type Message = { role: string; content: string | Block[] }; + +const textOf = (content: string | Block[] | undefined): string => typeof content === "string" ? content + : (content ?? []).map(block => block.text ?? "").join("\n"); + +it("admits each Claude tool call through the real ACP turn stream only for its own turn", async () => { + const root = await mkdtemp(join(tmpdir(), "claude-tool-use-acp-")); + const home = join(root, "home"), cwd = join(root, "workspace"), config = join(home, ".claude"); + await Promise.all([mkdir(config, { recursive: true }), mkdir(cwd)]); + const issued: string[][] = []; + const answered: string[][] = []; + let releaseTurnTwo!: () => void; + const turnTwoGate = new Promise(resolve => { releaseTurnTwo = resolve; }); + const api = createServer(async (request, response) => { + let raw = ""; + for await (const chunk of request) raw += chunk; + if (request.method === "GET") { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ data: [], has_more: false })); + return; + } + if (request.url?.includes("count_tokens")) { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ input_tokens: 1 })); + return; + } + const body = JSON.parse(raw || "{}") as { model?: string; stream?: boolean; messages?: Message[]; tools?: Array<{ name: string }> }; + const model = body.model ?? "claude-sonnet-5"; + if (body.stream !== true) { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ id: "msg_fixture", type: "message", role: "assistant", model, + content: [{ type: "text", text: "OK" }], stop_reason: "end_turn", usage: { input_tokens: 1, output_tokens: 1 } })); + return; + } + const conversation = (body.messages ?? []).filter(message => message.role === "user" || message.role === "assistant"); + const last = conversation.at(-1)?.content; + const results = Array.isArray(last) ? last.filter(block => block.type === "tool_result").map(block => block.tool_use_id!) : []; + const offersProbe = (body.tools ?? []).some(tool => tool.name === "mcp__paperclip__probe"); + const frames: Array> = [{ type: "message_start", message: { id: `msg_${issued.length}_${answered.length}`, type: "message", + role: "assistant", model, content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 1, output_tokens: 0 } } }]; + const text = (value: string) => frames.push({ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }, + { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: value } }, + { type: "content_block_stop", index: 0 }, + { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 1 } }); + if (results.length > 0) { + answered.push(results); + text("Probe complete."); + } else if (offersProbe && /TURN-ONE/.test(textOf(last))) { + const ids = [0, 1].map(index => `toolu_01Acp${issued.length + 1}${index}`); + issued.push(ids); + ids.forEach((id, index) => frames.push( + { type: "content_block_start", index, content_block: { type: "tool_use", id, name: "mcp__paperclip__probe", input: {} } }, + { type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: JSON.stringify({ tag: id }) } }, + { type: "content_block_stop", index })); + frames.push({ type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: 1 } }); + } else { + if (/TURN-TWO/.test(textOf(last))) await turnTwoGate; + text("Nothing to call."); + } + frames.push({ type: "message_stop" }); + response.writeHead(200, { "content-type": "text/event-stream" }); + for (const frame of frames) response.write(`event: ${frame.type}\ndata: ${JSON.stringify(frame)}\n\n`); + response.end(); + }); + await new Promise(resolve => api.listen(0, "127.0.0.1", resolve)); + const address = api.address() as { port: number }; + + const admission = new ClaudeToolUseAdmission(); + let activeTurn = ""; + const dispatched: Array<{ callId: string; tag: unknown }> = []; + const bridge = await startRunnerToolBridge({ + tools: [{ name: "probe", description: "Local fixture probe.", inputSchema: { type: "object", properties: { tag: { type: "string" } } } }], + preserveToolNames: true, + providerToolUseIdMetaKey: CLAUDE_TOOL_USE_META_KEY, + timeoutMs: null, + handler: async call => { + const callId = await admission.admit(activeTurn, call.providerToolUseId, call.signal); + dispatched.push({ callId, tag: (call.arguments as { tag?: unknown }).tag }); + return { ok: true }; + }, + }); + const entry = createRequire(import.meta.url).resolve("@agentclientprotocol/claude-agent-acp/dist/index.js"); + const command: VerifiedAcpxCommandLease = { + spawn: (args, input) => spawn(process.execPath, [entry, ...(args ?? [])], { ...input, detached: true, stdio: ["pipe", "pipe", "pipe"] }), + close: async () => undefined, + }; + const options: AcpxRuntimePortOpenOptions = { + command, + profile: resolveQualifiedAcpxProfile("claude", "claude-sonnet-5"), + cwd, + stateDirectory: join(root, "state"), + providerSessionKey: "claude-tool-use", + permissionMode: "approve-all", + permissionPolicy: { autoApprove: ["read", "write", "execute", "other"], defaultAction: "approve" }, + launchEnvironment: { HOME: home, CLAUDE_CONFIG_DIR: config, PATH: "/usr/bin:/bin", TMPDIR: root, + ANTHROPIC_API_KEY: "local-fixture-only", ANTHROPIC_BASE_URL: `http://127.0.0.1:${address.port}`, + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", DISABLE_TELEMETRY: "1", DISABLE_ERROR_REPORTING: "1", ENABLE_TOOL_SEARCH: "false" }, + credentialFenceFds: [42, 43] as const, + activateCredentialFenceOwner: async () => undefined, + systemInstructions: "Use Paperclip tools.", + mcpServers: [{ name: "paperclip", url: bridge.url, bearerToken: bridge.secret, runnerOwned: true }], + retainFailedAdmissionCleanup: vi.fn(), + } as AcpxRuntimePortOpenOptions; + const runTurn = async (turnId: string, text: string, during?: () => Promise) => { + activeTurn = turnId; + admission.beginTurn(turnId); + const turn = port!.startTurn({ text, requestId: turnId, onPermissionRequest: async () => ({ outcome: "allow_once" }) }); + const pumped = (async () => { + for await (const event of turn.events) { + admission.observe(turnId, event); + } + })(); + await during?.(); + await pumped; + const result = await turn.result; + admission.endTurn(turnId); + return result; + }; + const replay = (id: number, toolUseId: string, tag: string) => fetch(bridge.url, { method: "POST", + headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, + body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", + params: { name: "probe", arguments: { tag }, _meta: { [CLAUDE_TOOL_USE_META_KEY]: toolUseId } } }) }) + .then(response => response.json() as Promise<{ result: { isError?: boolean; content: Array<{ text: string }> } }>); + let port: Awaited> | undefined; + try { + port = await openCodexAcpxRuntime(options, { + awaitProviderOwnership: async () => undefined, + awaitProviderExit: child => new Promise(resolve => child.once("exit", () => resolve())), + }); + expect(await runTurn("turn-1", "TURN-ONE: call the probe tool twice.")).toMatchObject({ status: "completed" }); + expect(issued).toHaveLength(1); + const [first, second] = issued[0]!; + expect(dispatched.map(call => call.callId).sort()).toEqual([`tool-use:${first}`, `tool-use:${second}`].sort()); + expect(dispatched.map(call => call.tag).sort()).toEqual([first, second].sort()); + expect(answered.flat().sort()).toEqual([first, second].sort()); + + const turnTwo = await runTurn("turn-2", "TURN-TWO: do not call tools.", async () => { + const sameArguments = await replay(900, first!, first!); + expect(sameArguments.result.isError).not.toBe(true); + const changedArguments = await replay(901, first!, "replayed"); + expect(changedArguments.result).toMatchObject({ isError: true, content: [{ text: "Duplicate call identity conflict." }] }); + await expect(admission.admit("turn-2", first, new AbortController().signal)).rejects.toThrow("reused a provider tool-use identity"); + releaseTurnTwo(); + }); + expect(turnTwo).toMatchObject({ status: "completed" }); + expect(dispatched).toHaveLength(2); + } finally { + releaseTurnTwo(); + try { await port?.close({ reason: "tool-use admission verified" }); } + finally { + await bridge.close(); + api.closeAllConnections(); + await new Promise(resolve => api.close(() => resolve())); + await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }); + } + } +}, 60_000); diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts new file mode 100644 index 00000000000..3c222a56c25 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.test.ts @@ -0,0 +1,178 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { + CLAUDE_TOOL_USE_META_KEY, + ClaudeToolUseAdmission, + TOOL_USE_ANNOUNCEMENT_WAIT_MS, +} from "./claude-tool-use-admission.js"; + +const live = () => new AbortController().signal; + +afterEach(() => { + vi.useRealTimers(); +}); + +describe("Claude tool-use admission", () => { + it("names the meta key the pinned Claude Code sends", () => { + expect(CLAUDE_TOOL_USE_META_KEY).toBe("claudecode/toolUseId"); + }); + + it("admits a tool use announced in the active turn and derives a stable call id", async () => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", "toolu_01A"); + await expect(admission.admit("turn-1", "toolu_01A", live())).resolves.toBe("tool-use:toolu_01A"); + }); + + it("counts only an opening ACP tool_call event as an announcement", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.observe("turn-1", { type: "tool_call", tag: "tool_call_update", toolCallId: "toolu_update" }); + admission.observe("turn-1", { type: "status", tag: "tool_call", toolCallId: "toolu_status" }); + admission.observe("turn-1", { type: "tool_call", tag: "tool_call", toolCallId: "toolu_open" }); + await expect(admission.admit("turn-1", "toolu_open", live())).resolves.toBe("tool-use:toolu_open"); + for (const id of ["toolu_update", "toolu_status"]) { + const outcome = admission.admit("turn-1", id, live()).catch((error: Error) => error); + await vi.advanceTimersByTimeAsync(TOOL_USE_ANNOUNCEMENT_WAIT_MS); + expect(await outcome).toMatchObject({ message: "Paperclip tool call was not announced in the active turn" }); + } + }); + + it("admits a call that arrives before its announcement within the bound", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + const admitted = admission.admit("turn-1", "toolu_early", live()); + await vi.advanceTimersByTimeAsync(TOOL_USE_ANNOUNCEMENT_WAIT_MS - 1); + admission.announce("turn-1", "toolu_early"); + await expect(admitted).resolves.toBe("tool-use:toolu_early"); + }); + + it("rejects a call whose tool use is never announced once the bound elapses", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + const outcome = admission.admit("turn-1", "toolu_ghost", live()).catch((error: Error) => error); + await vi.advanceTimersByTimeAsync(TOOL_USE_ANNOUNCEMENT_WAIT_MS - 1); + admission.announce("turn-1", "toolu_other"); + await vi.advanceTimersByTimeAsync(1); + expect(await outcome).toMatchObject({ message: "Paperclip tool call was not announced in the active turn" }); + admission.announce("turn-1", "toolu_ghost"); + await expect(admission.admit("turn-1", "toolu_ghost", live())).resolves.toBe("tool-use:toolu_ghost"); + }); + + it("rejects a waiting call as soon as its turn ends", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + const outcome = admission.admit("turn-1", "toolu_late", live()).catch((error: Error) => error); + await vi.advanceTimersByTimeAsync(10); + admission.endTurn("turn-1"); + await vi.advanceTimersByTimeAsync(0); + expect(await outcome).toMatchObject({ message: "Paperclip tool call was not announced in the active turn" }); + expect(vi.getTimerCount()).toBe(0); + }); + + it("rejects a waiting call when the provider cancels it", async () => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + const controller = new AbortController(); + const outcome = admission.admit("turn-1", "toolu_cancelled", controller.signal).catch((error: Error) => error); + controller.abort(); + admission.announce("turn-1", "toolu_cancelled"); + expect(await outcome).toBeInstanceOf(Error); + }); + + it("does not let a later turn admit a tool use announced in an earlier turn", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", "toolu_turn1"); + admission.endTurn("turn-1"); + admission.beginTurn("turn-2"); + const outcome = admission.admit("turn-2", "toolu_turn1", live()).catch((error: Error) => error); + await vi.advanceTimersByTimeAsync(TOOL_USE_ANNOUNCEMENT_WAIT_MS); + expect(await outcome).toMatchObject({ message: "Paperclip tool call was not announced in the active turn" }); + }); + + it("ignores announcements for a turn that is not active", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.announce("turn-1", "toolu_before"); + admission.beginTurn("turn-2"); + admission.announce("turn-1", "toolu_stale"); + for (const id of ["toolu_before", "toolu_stale"]) { + const outcome = admission.admit("turn-2", id, live()).catch((error: Error) => error); + await vi.advanceTimersByTimeAsync(TOOL_USE_ANNOUNCEMENT_WAIT_MS); + expect(await outcome).toBeInstanceOf(Error); + } + }); + + it("refuses a tool use already admitted, in the same turn or a later one", async () => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", "toolu_once"); + await admission.admit("turn-1", "toolu_once", live()); + await expect(admission.admit("turn-1", "toolu_once", live())) + .rejects.toThrow("Paperclip tool call reused a provider tool-use identity"); + admission.endTurn("turn-1"); + admission.beginTurn("turn-2"); + admission.announce("turn-2", "toolu_once"); + await expect(admission.admit("turn-2", "toolu_once", live())) + .rejects.toThrow("Paperclip tool call reused a provider tool-use identity"); + }); + + it("admits only one of two concurrent calls waiting on the same tool use", async () => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + const first = admission.admit("turn-1", "toolu_twin", live()).then(id => id, (error: Error) => error); + const second = admission.admit("turn-1", "toolu_twin", live()).then(id => id, (error: Error) => error); + admission.announce("turn-1", "toolu_twin"); + const outcomes = await Promise.all([first, second]); + expect(outcomes.filter(value => value === "tool-use:toolu_twin")).toHaveLength(1); + expect(outcomes.filter(value => value instanceof Error)).toHaveLength(1); + }); + + it("attributes two turns' live calls by tool use after a cancelled turn", async () => { + vi.useFakeTimers(); + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", "toolu_0001"); + const turnOneCall = admission.admit("turn-1", "toolu_0001", live()); + await expect(turnOneCall).resolves.toBe("tool-use:toolu_0001"); + admission.announce("turn-1", "toolu_0001b"); + admission.endTurn("turn-1"); + admission.beginTurn("turn-2"); + admission.announce("turn-2", "toolu_0002"); + const late = admission.admit("turn-2", "toolu_0001b", live()).catch((error: Error) => error); + await expect(admission.admit("turn-2", "toolu_0002", live())).resolves.toBe("tool-use:toolu_0002"); + await expect(admission.admit("turn-2", "toolu_0001", live())).rejects.toThrow("reused"); + admission.endTurn("turn-2"); + expect(await late).toMatchObject({ message: "Paperclip tool call was not announced in the active turn" }); + }); + + it("admits a subagent's child tool use announced in the active turn", async () => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", "toolu_agent"); + admission.announce("turn-1", "toolu_child"); + await expect(admission.admit("turn-1", "toolu_child", live())).resolves.toBe("tool-use:toolu_child"); + }); + + it.each([undefined, "", "toolu bad", "_toolu", "x".repeat(129)])("rejects a call without a usable tool-use id: %s", async id => { + const admission = new ClaudeToolUseAdmission(); + admission.beginTurn("turn-1"); + admission.announce("turn-1", id); + await expect(admission.admit("turn-1", id, live())) + .rejects.toThrow("Paperclip tool call has no provider tool-use identity"); + }); + + it("rejects a call for a turn that is not active without waiting", async () => { + const admission = new ClaudeToolUseAdmission(); + await expect(admission.admit("turn-1", "toolu_idle", live())).rejects.toThrow("not bound to the active turn"); + admission.beginTurn("turn-2"); + admission.announce("turn-2", "toolu_idle"); + await expect(admission.admit("turn-1", "toolu_idle", live())).rejects.toThrow("not bound to the active turn"); + }); +}); diff --git a/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts new file mode 100644 index 00000000000..85e597e0794 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts @@ -0,0 +1,86 @@ +export const CLAUDE_TOOL_USE_META_KEY = "claudecode/toolUseId"; + +export const TOOL_USE_ANNOUNCEMENT_WAIT_MS = 5_000; + +const MAX_TURN_ANNOUNCEMENTS = 4_096; +const MAX_ADMITTED_TOOL_USES = 8_192; +const TOOL_USE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/; + +export class ClaudeToolUseAdmission { + #turnId: string | null = null; + readonly #announced = new Set(); + readonly #admitted = new Set(); + readonly #waiters = new Set<() => void>(); + readonly #waitMs: number; + + constructor(waitMs = TOOL_USE_ANNOUNCEMENT_WAIT_MS) { + this.#waitMs = waitMs; + } + + beginTurn(turnId: string): void { + this.#turnId = turnId; + this.#announced.clear(); + this.#wake(); + } + + endTurn(turnId: string): void { + if (this.#turnId !== turnId) return; + this.#turnId = null; + this.#announced.clear(); + this.#wake(); + } + + observe(turnId: string, event: { type?: unknown; tag?: unknown; toolCallId?: unknown }): void { + if (event.type === "tool_call" && event.tag === "tool_call") this.announce(turnId, event.toolCallId); + } + + announce(turnId: string, toolCallId: unknown): void { + if (this.#turnId !== turnId || typeof toolCallId !== "string" || !TOOL_USE_ID.test(toolCallId)) return; + if (this.#announced.size >= MAX_TURN_ANNOUNCEMENTS) return; + this.#announced.add(toolCallId); + this.#wake(); + } + + async admit(turnId: string, toolUseId: string | undefined, signal: AbortSignal): Promise { + if (toolUseId === undefined || !TOOL_USE_ID.test(toolUseId)) { + throw new Error("Paperclip tool call has no provider tool-use identity"); + } + if (this.#turnId !== turnId) throw new Error("Paperclip tool call is not bound to the active turn"); + this.#assertUnused(toolUseId); + if (!this.#announced.has(toolUseId)) await this.#awaitAnnouncement(turnId, toolUseId, signal); + if (this.#turnId !== turnId || signal.aborted || !this.#announced.has(toolUseId)) { + throw new Error("Paperclip tool call was not announced in the active turn"); + } + this.#assertUnused(toolUseId); + if (this.#admitted.size >= MAX_ADMITTED_TOOL_USES) throw new Error("Provider tool-use ledger is at capacity"); + this.#admitted.add(toolUseId); + return `tool-use:${toolUseId}`; + } + + #assertUnused(toolUseId: string): void { + if (this.#admitted.has(toolUseId)) throw new Error("Paperclip tool call reused a provider tool-use identity"); + } + + #awaitAnnouncement(turnId: string, toolUseId: string, signal: AbortSignal): Promise { + return new Promise((resolve) => { + const done = () => { + clearTimeout(timer); + signal.removeEventListener("abort", done); + this.#waiters.delete(check); + resolve(); + }; + const check = () => { + if (this.#turnId !== turnId || this.#announced.has(toolUseId)) done(); + }; + const timer = setTimeout(done, this.#waitMs); + timer.unref?.(); + signal.addEventListener("abort", done, { once: true }); + this.#waiters.add(check); + if (signal.aborted) done(); + }); + } + + #wake(): void { + for (const check of [...this.#waiters]) check(); + } +} diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.claude-tool-use.test.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.claude-tool-use.test.ts new file mode 100644 index 00000000000..95f446ef820 --- /dev/null +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.claude-tool-use.test.ts @@ -0,0 +1,93 @@ +import { execFile } from "node:child_process"; +import { createServer } from "node:http"; +import { mkdtemp, mkdir, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { promisify } from "node:util"; +import { claudeCliPath } from "@agentclientprotocol/claude-agent-acp/dist/acp-agent.js"; +import { expect, it } from "vitest"; +import { CLAUDE_TOOL_USE_META_KEY } from "./acpx/claude-tool-use-admission.js"; +import { startRunnerToolBridge } from "./runner-tool-bridge.js"; + +type Block = { type: string; tool_use_id?: string }; +type Message = { role: string; content: string | Block[] }; + +it("names each MCP tool call by the tool use the pinned Claude client received", async () => { + const root = await mkdtemp(join(tmpdir(), "claude-tool-use-id-")); + const config = join(root, "config"), cwd = join(root, "workspace"); + await Promise.all([mkdir(config), mkdir(cwd)]); + const issued: string[] = []; + const api = createServer(async (request, response) => { + let raw = ""; + for await (const chunk of request) raw += chunk; + if (request.method === "GET") { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ data: [], has_more: false })); + return; + } + if (request.url?.includes("count_tokens")) { + response.writeHead(200, { "content-type": "application/json" }); + response.end(JSON.stringify({ input_tokens: 1 })); + return; + } + const body = JSON.parse(raw || "{}") as { messages?: Message[]; tools?: Array<{ name: string }> }; + const conversation = (body.messages ?? []).filter(message => message.role === "user" || message.role === "assistant"); + const last = conversation.at(-1)?.content; + const answered = Array.isArray(last) && last.some(block => block.type === "tool_result"); + const offersProbe = (body.tools ?? []).some(tool => tool.name === "mcp__paperclip__probe"); + const frames: Array> = [{ type: "message_start", message: { id: `msg_${issued.length}`, type: "message", role: "assistant", + model: "claude-sonnet-5", content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 1, output_tokens: 0 } } }]; + if (answered || !offersProbe) { + frames.push({ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }, + { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Local fixture complete." } }, + { type: "content_block_stop", index: 0 }, + { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 1 } }); + } else { + for (const index of [0, 1]) { + const id = `toolu_01Fixture${issued.length + 1}`; + issued.push(id); + frames.push({ type: "content_block_start", index, content_block: { type: "tool_use", id, name: "mcp__paperclip__probe", input: {} } }, + { type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: JSON.stringify({ tag: id }) } }, + { type: "content_block_stop", index }); + } + frames.push({ type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: 1 } }); + } + frames.push({ type: "message_stop" }); + response.writeHead(200, { "content-type": "text/event-stream" }); + for (const frame of frames) response.write(`event: ${frame.type}\ndata: ${JSON.stringify(frame)}\n\n`); + response.end(); + }); + const received: Array = []; + const bridge = await startRunnerToolBridge({ + tools: [{ name: "probe", description: "Local fixture probe.", inputSchema: { type: "object", properties: { tag: { type: "string" } } } }], + preserveToolNames: true, + providerToolUseIdMetaKey: CLAUDE_TOOL_USE_META_KEY, + handler: async ({ providerToolUseId }) => { + received.push(providerToolUseId); + return { ok: true }; + }, + }); + try { + await new Promise(resolve => api.listen(0, "127.0.0.1", resolve)); + const address = api.address() as { port: number }; + const mcpConfig = { mcpServers: { paperclip: { type: "http", url: bridge.url, headers: { Authorization: `Bearer ${bridge.secret}` } } } }; + await promisify(execFile)(await claudeCliPath(), [ + "--bare", "--print", "--model", "claude-sonnet-5", "--strict-mcp-config", "--mcp-config", JSON.stringify(mcpConfig), + "--setting-sources", "", "--permission-mode", "dontAsk", "--allowedTools", "mcp__paperclip__probe", + "--no-session-persistence", "--tools", "", "--max-turns", "2", + "Call the probe tool, then report the result.", + ], { cwd, timeout: 20_000, env: { + PATH: process.env.PATH, TMPDIR: root, CLAUDE_CONFIG_DIR: config, + ANTHROPIC_API_KEY: "local-fixture-only", ANTHROPIC_BASE_URL: `http://127.0.0.1:${address.port}`, + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", DISABLE_TELEMETRY: "1", DISABLE_ERROR_REPORTING: "1", ENABLE_TOOL_SEARCH: "false", + } }); + expect(issued).toHaveLength(2); + expect(received).toHaveLength(issued.length); + expect([...received].sort()).toEqual([...issued].sort()); + } finally { + api.closeAllConnections(); + await new Promise(resolve => api.close(() => resolve())); + await bridge.close(); + await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }); + } +}, 30_000); 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 7545f159579..44855fad482 100644 --- a/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.test.ts @@ -15,6 +15,7 @@ import { canonicalRunnerToolName, startRunnerToolBridge, type RunnerToolBridge, + type RunnerToolCall, } from "./runner-tool-bridge.js"; const bridges: RunnerToolBridge[] = []; @@ -542,6 +543,107 @@ function tool(name: string): Readonly> { return { name, inputSchema: { type: "object" } }; } +describe("provider tool-use identity", () => { + const META_KEY = "claudecode/toolUseId"; + const call = (id: string | number, args: Record, meta?: Record) => ({ + id, method: "tools/call", params: { name: "documents.read", arguments: args, ...(meta === undefined ? {} : { _meta: meta }) }, + }); + + it("carries the provider tool-use id to the handler only when the caller names its meta key", async () => { + const handler = vi.fn(async (_call: RunnerToolCall) => ({ ok: true })); + const opted = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + const plain = await startRunnerToolBridge({ tools: [tool("documents.read")], handler }); + bridges.push(opted, plain); + await rpc(opted, call(2, { n: 1 }, { [META_KEY]: "toolu_01Abc", progressToken: 2 })); + await rpc(plain, call(2, { n: 1 }, { [META_KEY]: "toolu_01Abc" })); + expect(handler.mock.calls.map(([value]) => value.providerToolUseId)) + .toEqual(["toolu_01Abc", undefined]); + expect(handler.mock.calls.map(([value]) => value.callId)).toEqual(["2", "2"]); + }); + + it("passes no id when the provider omits it and refuses a malformed one before dispatch", async () => { + const handler = vi.fn(async (_call: RunnerToolCall) => ({ ok: true })); + const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + bridges.push(bridge); + await rpc(bridge, call(1, { n: 1 })); + await rpc(bridge, call(2, { n: 2 }, { progressToken: 2 })); + expect(handler.mock.calls.map(([value]) => value.providerToolUseId)) + .toEqual([undefined, undefined]); + for (const [index, value] of [7, "", "x".repeat(129), "toolu 01", "toolu_01\n", "_toolu", { id: "toolu_01" }].entries()) { + expect(await (await rpc(bridge, call(10 + index, { n: 3 }, { [META_KEY]: value }))).json()).toMatchObject({ + result: { isError: true, content: [{ text: "Invalid provider tool-use identity." }] }, + }); + } + expect(handler).toHaveBeenCalledTimes(2); + }); + + it("replays a retried tool use under a new request id and refuses it with different arguments", async () => { + let finish!: (value: unknown) => void; + const handler = vi.fn(() => new Promise(resolve => { finish = resolve; })); + const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + bridges.push(bridge); + const first = rpc(bridge, call(2, { n: 1 }, { [META_KEY]: "toolu_A" })); + await vi.waitFor(() => expect(handler).toHaveBeenCalledOnce()); + const retry = rpc(bridge, call(9, { n: 1 }, { [META_KEY]: "toolu_A" })); + expect(await (await rpc(bridge, call(10, { n: 2 }, { [META_KEY]: "toolu_A" }))).json()).toMatchObject({ + result: { isError: true, content: [{ text: "Duplicate call identity conflict." }] }, + }); + finish({ value: 1 }); + expect(await (await first).json()).toMatchObject({ id: 2, result: { content: [{ text: '{"value":1}' }] } }); + expect(await (await retry).json()).toMatchObject({ id: 9, result: { content: [{ text: '{"value":1}' }] } }); + expect(await (await rpc(bridge, call(2, { n: 1 }, { [META_KEY]: "toolu_A" }))).json()) + .toMatchObject({ result: { content: [{ text: '{"value":1}' }] } }); + expect(handler).toHaveBeenCalledOnce(); + }); + + it("dispatches distinct tool uses that reuse a request id, as two turns' calls on one session do", async () => { + const handler = vi.fn(async ({ providerToolUseId }: { providerToolUseId?: string }) => ({ providerToolUseId })); + const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + bridges.push(bridge); + expect(await (await rpc(bridge, call(2, { n: 1 }, { [META_KEY]: "toolu_turn1" }))).json()) + .toMatchObject({ result: { content: [{ text: '{"providerToolUseId":"toolu_turn1"}' }] } }); + expect(await (await rpc(bridge, call(2, { n: 2 }, { [META_KEY]: "toolu_turn2" }))).json()) + .toMatchObject({ result: { content: [{ text: '{"providerToolUseId":"toolu_turn2"}' }] } }); + expect(handler).toHaveBeenCalledTimes(2); + }); + + it("cancels a tool-use keyed call through its request id", async () => { + let signal: AbortSignal | undefined; + const handler = vi.fn((value: { signal: AbortSignal }) => { signal = value.signal; return new Promise(() => {}); }); + const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + bridges.push(bridge); + const pending = rpc(bridge, call(4, { n: 1 }, { [META_KEY]: "toolu_cancel" })); + await vi.waitFor(() => expect(handler).toHaveBeenCalledOnce()); + expect((await rpc(bridge, { method: "notifications/cancelled", params: { requestId: 4 } })).status).toBe(202); + expect(signal?.aborted).toBe(true); + expect(await (await pending).json()).toMatchObject({ result: { isError: true, content: [{ text: "Paperclip tool call cancelled" }] } }); + }); + + it("cancels only the call of the MCP session that sent the cancel when two sessions reuse a request id", async () => { + const signals = new Map(); + const handler = vi.fn((value: { signal: AbortSignal; providerToolUseId?: string }) => { + signals.set(value.providerToolUseId!, value.signal); + return new Promise(() => {}); + }); + const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], providerToolUseIdMetaKey: META_KEY, handler }); + bridges.push(bridge); + const send = (session: string, body: Record) => fetch(bridge.url, { method: "POST", + headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json", "Mcp-Session-Id": session }, + body: JSON.stringify({ jsonrpc: "2.0", ...body }) }); + const first = send("session-a", call(7, { n: 1 }, { [META_KEY]: "toolu_first" })); + await vi.waitFor(() => expect(handler).toHaveBeenCalledTimes(1)); + const second = send("session-b", call(7, { n: 2 }, { [META_KEY]: "toolu_second" })); + await vi.waitFor(() => expect(handler).toHaveBeenCalledTimes(2)); + expect((await send("session-a", { method: "notifications/cancelled", params: { requestId: 7 } })).status).toBe(202); + expect(signals.get("toolu_first")?.aborted).toBe(true); + expect(signals.get("toolu_second")?.aborted).toBe(false); + expect(await (await first).json()).toMatchObject({ result: { isError: true, content: [{ text: "Paperclip tool call cancelled" }] } }); + expect((await send("session-b", { method: "notifications/cancelled", params: { requestId: 7 } })).status).toBe(202); + expect(signals.get("toolu_second")?.aborted).toBe(true); + await second; + }); +}); + describe("Copilot semantic receipt opt-in", () => { const rawFinish = { reportedWorkDisposition: "done", summary: "The task is complete.", evidence: [], verification: [], completionClaim: { contractRevision: "1", objectiveSatisfied: true, criteria: [], remainingWork: [] } }; diff --git a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts index 56f007549a9..a049b866094 100644 --- a/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts +++ b/packages/paperclip-runner/src/drivers/runner-tool-bridge.ts @@ -36,6 +36,7 @@ export interface RunnerToolCall { callId: string; arguments: unknown; signal: AbortSignal; + providerToolUseId?: string; /** Internal, invocation-owned evidence. Snapshot before forwarding; commit only * after that exact normalized input is forwarded. Never supplied by the model. */ captureNormalizedInput?: (input: unknown) => (() => void); @@ -46,6 +47,7 @@ export interface RunnerToolBridgeOptions { /** Claude-only: avoid tool search for task naming and terminal disposition. */ preloadClaudeTaskTools?: boolean; preserveToolNames?: boolean; + providerToolUseIdMetaKey?: string; /** Runner-owned operations that are callable but never model-visible. */ privateTools?: readonly Readonly>[]; handler(call: RunnerToolCall): Promise; @@ -91,6 +93,7 @@ const DEFAULT_MAX_BODY_BYTES = 1_048_576; const DEFAULT_REQUEST_BODY_TIMEOUT_MS = 30_000; const MAX_CALLS = 2_048; const MAX_RESULT_CHUNK_BYTES = 64 * 1024; +const PROVIDER_TOOL_USE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/; const RESERVED_TOOLS: readonly RunnerToolDefinition[] = [ { name: PRP_COMPLETION_TOOL_NAME, @@ -153,6 +156,8 @@ export async function startRunnerToolBridge( rejections: new RepeatedToolInputRejectionGuard(), calls, controllers, + requestCalls: new Map(), + providerToolUseIdMetaKey: options.providerToolUseIdMetaKey, sessionScope: options.sessionScope, scopeToken: options.scopeToken, sessions: new Map(), @@ -243,6 +248,8 @@ async function handleRequest( rejections: RepeatedToolInputRejectionGuard; calls: Map; controllers: Map; + requestCalls: Map; + providerToolUseIdMetaKey: string | undefined; handler: RunnerToolBridgeOptions["handler"]; captureSemanticReceipt: RunnerToolBridgeOptions["captureSemanticReceipt"]; timeoutMs: number | null; @@ -301,7 +308,7 @@ async function handleRequest( if (!scope) { response.statusCode = 403; response.end(); return; } if (context.activeScope !== scope) { for (const controller of context.controllers.values()) controller.abort(); - context.sessions.clear(); context.calls.clear(); context.controllers.clear(); + context.sessions.clear(); context.calls.clear(); context.controllers.clear(); context.requestCalls.clear(); context.activeScope = scope; } if (method !== "initialize") { @@ -316,7 +323,8 @@ async function handleRequest( const params = isRecord(message.params) ? message.params : {}; const requestId = params.requestId; if (typeof requestId === "string" || typeof requestId === "number") { - context.controllers.get(sessionKey + rpcIdKey(requestId))?.abort(); + const requestKey = sessionKey + rpcIdKey(requestId); + context.controllers.get(context.requestCalls.get(mcpSessionKey(request) + requestKey) ?? requestKey)?.abort(); } response.statusCode = 202; response.end(); @@ -370,8 +378,21 @@ async function handleRequest( ); return; } + let providerToolUseId: string | undefined; + if (context.providerToolUseIdMetaKey !== undefined) { + const supplied = isRecord(params._meta) ? params._meta[context.providerToolUseIdMetaKey] : undefined; + if (supplied !== undefined) { + if (typeof supplied !== "string" || !PROVIDER_TOOL_USE_ID.test(supplied)) { + writeToolError(response, id, "Invalid provider tool-use identity."); + return; + } + providerToolUseId = supplied; + } + } const callId = context.sessionScope ? sessionKey + rpcIdKey(id) : String(id); - const callKey = sessionKey + rpcIdKey(id); + 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) @@ -448,6 +469,7 @@ async function handleRequest( callId, arguments: structuredClone(args), signal: controller!.signal, + ...(providerToolUseId === undefined ? {} : { providerToolUseId }), ...(context.captureSemanticReceipt && (tool === PRP_COMPLETION_TOOL_NAME || tool === PRP_BLOCK_TOOL_NAME) ? { captureNormalizedInput } : {}), }), @@ -468,14 +490,24 @@ async function handleRequest( .finally(() => context.controllers.delete(callKey)) .catch(() => undefined); } + if (callKey !== requestKey) context.requestCalls.set(cancelKey, callKey); try { const result = await execution; writeRpc(response, id, result); } catch (error) { writeToolError(response, id, safeError(error)); + } finally { + if (callKey !== requestKey && context.requestCalls.get(cancelKey) === callKey) { + context.requestCalls.delete(cancelKey); + } } } +function mcpSessionKey(request: IncomingMessage): string { + const session = request.headers["mcp-session-id"]; + return typeof session === "string" ? `${session}\u0000` : ""; +} + function normalizeTools( input: readonly Readonly>[], visibility: "public" | "private",