mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
fix(acpx): admit a Claude tool call only for a tool use its turn announced (#21278)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude Code through the ACPX sidecar. Claude calls Paperclip tools through a Runner-owned MCP endpoint, the tool bridge. > - The bridge identifies a call by its JSON-RPC request id. That id does not say which turn sent the call. The sidecar binds a call to the turn that is active when the call arrives. > - Because of this, the Runner stops and starts the Claude process at each turn boundary. A late call from an earlier turn then cannot run in a later turn. This restart also stops all background work that Claude started. > - Claude Code already sends the missing identity. Each MCP `tools/call` has `_meta["claudecode/toolUseId"]`. It is the id of the ACP `tool_call` that the provider announces first, inside one turn. > - This pull request uses that id. The sidecar admits a Claude tool call only if the active turn announced its tool use. > - The benefit is that a call from an earlier turn is refused by its identity. This is the first step to keep the Claude process alive between turns. This pull request does not change the restart. ## Linked Issues or Issue Description No public issue exists. The issue is described here. Refs #19912 (the design for turn-scoped ACPX MCP authority), #12419 (the restart at turn start) and #20190 (the restart at turn end). This pull request is the bottom of a stack. #21274 is merged, so the base branch is `master`. It uses no code from #21274. The stack order lets a later pull request remove the direct gateway path after both. **What existing behavior does this improve?** How the Runner decides which turn a Claude tool call belongs to. **Subsystem affected** Paperclip Runner: the tool bridge and the ACPX sidecar, for the Claude provider only. **Current behavior** - The bridge keys a call by the JSON-RPC request id (`runner-tool-bridge.ts`). - The sidecar gives the call to the active turn (`waitForTool` in `acpx-runtime-sidecar.ts`). - After `session/cancel`, Claude Code does not stop an MCP request that is in flight. A test run showed two calls from two turns live at the same time on one MCP session. Request ids cannot tell them apart. **Proposed behavior** - The bridge can read a provider tool-use id from `params._meta` and give it to the handler. It keys replays by that id. - For Claude, the sidecar admits a call only when the turn event stream of the active turn contains the ACP `tool_call` with the same id, and no earlier call used that id. - The announcement and the call use different channels. If the call arrives first, the sidecar waits for the announcement for a maximum of 5 seconds. The wait stops when the turn ends or the call is cancelled. - A call with no id, an id from an earlier turn, an id that was never announced, or an id that was used before gets a tool error. There is no fallback. - The call id that the sidecar sends to runnerd is `tool-use:<id>` for Claude. **Reason and benefit** - A late call from an earlier turn cannot run in a later turn. The identity of the call prevents this, not only the process restart. - A later change can stop the restart between turns. ## What Changed - `packages/paperclip-runner/src/drivers/runner-tool-bridge.ts` - New option `providerToolUseIdMetaKey`. Without it the bridge does not change. - With it, the bridge reads `params._meta[key]`. It refuses a value that is not a bounded string. It gives a valid value to the handler as `providerToolUseId`. - The replay key is the tool-use id. A retry with a new request id replays the first result. The same id with different arguments is refused. - `notifications/cancelled` still finds the call by its request id. - `packages/paperclip-runner/src/drivers/acpx/claude-tool-use-admission.ts` (new): `ClaudeToolUseAdmission`. - `observe` records an id only from an event with `type === "tool_call"` and `tag === "tool_call"`. A `tool_call_update` does not count, so a late update about an old tool use cannot admit it. - `admit` applies the rule above. An id is used when it is admitted. Limits: 4,096 announcements for each turn and 8,192 admitted ids. At a limit, new calls are refused. - `packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts` - The sidecar creates the admission object only for `agent === "claude"` and sets the bridge option only for Claude. - `pumpTurn` gives each turn event to `observe`. `waitForTool` calls `admit` and then checks the turn and run again. - The internal `get_task_context` call for a completion continuation does not go through admission. - The Claude call id does not use the per-process namespace, because a tool-use id is unique. - No change to Rust, the sidecar contract, the `claude-agent-acp` patch, the server, or restart, park and turn lifecycle code. Other ACPX agents and Cursor Cloud use the same code path as before. Why 5 seconds: the measured time between the announcement and the call is 1.1 ms to 14.7 ms. The limit must also include queue and event-loop delay. 5 seconds is far above that, and a call that cannot be attributed still gets a fast answer. ## Verification Commands, from `packages/paperclip-runner`: - `npx vitest run src/drivers/acpx/acpx-runtime-adapter.claude-tool-use.test.ts src/drivers/acpx/claude-tool-use-admission.test.ts src/drivers/runner-tool-bridge.test.ts src/drivers/runner-tool-bridge.claude-tool-use.test.ts src/drivers/runner-tool-bridge.claude-schema.test.ts src/cli/acpx-runtime-sidecar.test.ts src/drivers/acpx/acpx-runtime-adapter.test.ts src/drivers/cursor-cloud/cursor-cloud-driver.test.ts`: `8 passed (8)` files, `384 passed` tests. - `npx tsc --noEmit -p tsconfig.json`: no errors. New tests: - **Real ACP runtime** (`acpx-runtime-adapter.claude-tool-use.test.ts`). It uses the real `openCodexAcpxRuntime`, ACPX 0.22, the pinned and patched `claude-agent-acp`, the pinned Claude Code client and a real tool bridge, against a local fake Anthropic API. - Turn 1: two parallel tool uses are admitted as `tool-use:<id>`. The model receives both results. The turn completes. - Turn 2 in the same session: a replay of a turn 1 id returns the cached result and does not dispatch again. The same id with different arguments is refused. `admit` refuses the old id. - In five runs each call arrived 6.9 ms to 13.2 ms after its announcement. No call waited. - **Qualification** (`runner-tool-bridge.claude-tool-use.test.ts`). The pinned Claude Code client sends `_meta["claudecode/toolUseId"]` on each `tools/call`, with the id that the API issued. This test must pass before a Claude Code version change. - **Admission unit tests** (19): announced then called, called then announced, never announced, turn end during the wait, cancel, an id from the previous turn, reuse, two concurrent calls with one id, two turns with live calls, a subagent call, a bad id. - **Sidecar process tests** (2), with a fake host, for Claude and for Codex. The Codex run shows no change. - **Bridge unit tests** (5). Mutation checks: - Change the announcement predicate so that it matches nothing: the real ACP test and one unit test fail. - Remove the bridge option in the real ACP test: the test fails. - Count only `tool_call_update`: the unit test "counts only an opening ACP tool_call event as an announcement" fails. Live run with a real Claude account, not in CI: the real ACP runtime (ACPX 0.22, the patched `claude-agent-acp`, the pinned Claude Code client), a real tool bridge, and the real Anthropic API with model `claude-sonnet-5-5`, on the code at the top of this stack. In three sessions, 8 Paperclip tool calls were admitted and none was refused. This includes calls in a prompt turn, in a cycle that Claude started itself, and in a later turn of the same process. Each call arrived 0.8 s to 1.7 s after its announcement, so no call waited for a late announcement. Not run: a turn through the real sidecar process with the real host. That needs a qualified provider installation, the runtime sandbox and the provider lifetime lease. Not run: the Linux builds of the pinned client and a test under load. Not run: `pnpm verify` and the full suite. CI supplies that coverage. ## Risks - **This changes each Paperclip tool call that Claude makes.** If the announcement does not reach the turn event stream in production, the sidecar refuses the call after 5 seconds. The real ACP test covers the stream of ACPX 0.22 with the pinned provider. It does not cover the real sidecar host. - **The 5 second limit is not tested under load.** A slow host can delay the announcement. The call is then refused, and Claude sees a tool error. - **A Claude Code version that stops sending the id breaks all Claude tool calls.** The qualification test finds this before the version changes. - **The admitted-id ledger is in sidecar memory.** Today the sidecar restarts at each turn boundary, so the ledger is small. The limit of 8,192 ids refuses new calls when it is full. - **Subagent calls and calls from a cycle that Claude starts itself** are covered by unit tests and fake-host tests, not by the real ACP stream. - **An admitted call that is in flight when its turn ends** is refused by the existing turn cleanup. Claude Code can leave the HTTP request open. The bridge stops it only on its own cancel or close, as before. > 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 - Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the change, reviewed the diff, asked for the real ACP runtime test, and ran the verification and a mutation check again. - Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with tool use (shell, file edits, local test runs), wrote the change and the tests. ## 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 - [ ] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] 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 Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
1 parent
89f486cdab
commit
7866e9ef05
8 files changed
+833
-15
No files matched your search
@@ -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<void>(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<any> | 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<string, any>(), 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<ToolCallResponseBody>);
|
||||
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<string, unknown>) => {
|
||||
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<string, unknown>).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<unknown> {
|
||||
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<string>(),
|
||||
randomUUID,
|
||||
input.callIdNamespace ?? null,
|
||||
input.toolUseAdmission ?? null,
|
||||
256 * 1024,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -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<AcpRuntimeEventShape>((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<unknown> {
|
||||
async function waitForTool(call: RunnerToolCall, internal = false): Promise<unknown> {
|
||||
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<unknown> {
|
||||
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();
|
||||
|
||||
+174
@@ -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<void>(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<Record<string, unknown>> = [{ 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<void>(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<void>) => {
|
||||
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<ReturnType<typeof openCodexAcpxRuntime>> | undefined;
|
||||
try {
|
||||
port = await openCodexAcpxRuntime(options, {
|
||||
awaitProviderOwnership: async () => undefined,
|
||||
awaitProviderExit: child => new Promise<void>(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<void>(resolve => api.close(() => resolve()));
|
||||
await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
|
||||
}
|
||||
}
|
||||
}, 60_000);
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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<string>();
|
||||
readonly #admitted = new Set<string>();
|
||||
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<string> {
|
||||
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<void> {
|
||||
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();
|
||||
}
|
||||
}
|
||||
@@ -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<Record<string, unknown>> = [{ 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<string | undefined> = [];
|
||||
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<void>(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<void>(resolve => api.close(() => resolve()));
|
||||
await bridge.close();
|
||||
await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
|
||||
}
|
||||
}, 30_000);
|
||||
@@ -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<Record<string, unknown>> {
|
||||
return { name, inputSchema: { type: "object" } };
|
||||
}
|
||||
|
||||
describe("provider tool-use identity", () => {
|
||||
const META_KEY = "claudecode/toolUseId";
|
||||
const call = (id: string | number, args: Record<string, unknown>, meta?: Record<string, unknown>) => ({
|
||||
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<string, AbortSignal>();
|
||||
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<string, unknown>) => 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: [] } };
|
||||
|
||||
@@ -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<Record<string, unknown>>[];
|
||||
handler(call: RunnerToolCall): Promise<unknown>;
|
||||
@@ -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<string, string>(),
|
||||
providerToolUseIdMetaKey: options.providerToolUseIdMetaKey,
|
||||
sessionScope: options.sessionScope,
|
||||
scopeToken: options.scopeToken,
|
||||
sessions: new Map<string, string>(),
|
||||
@@ -243,6 +248,8 @@ async function handleRequest(
|
||||
rejections: RepeatedToolInputRejectionGuard;
|
||||
calls: Map<string, AdmittedCall>;
|
||||
controllers: Map<string, AbortController>;
|
||||
requestCalls: Map<string, string>;
|
||||
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<Record<string, unknown>>[],
|
||||
visibility: "public" | "private",
|
||||
|
||||
Reference in new issue
Block a user