chore(runner): integrate pending v10 correlation for qualification only

Preserve both reviewed source and historical qualification evidence. CI-only branch; do not merge.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-09-30 22:14:15 -05:00
commit a06fa49483
39 files changed
+1471 -98

No files matched your search

@@ -1,6 +1,35 @@
# Copilot 1.0.88 rich ACP capability audit
Current source candidate (2026-09-30): **Copilot profile v9 is unqualified**.
Current source candidate (2026-10-01): **Copilot profile v10 is unqualified**.
Admitted Paperclip MCP calls append a bounded `paperclip.semantic_tool_receipt.v1`
text block after the original result blocks. It records the operation, call-ID
hash, canonical argument hash, result hash and transport outcome. An invocation
callback bound to the active turn emits matching durable evidence. Native tool
output alone is not authority: the projector requires that callback, exact
arguments and result, and one native lifecycle. It rejects foreign, late,
duplicate and conflicting receipts. Tool names and titles cannot grant a match.
`returned` does not mean accepted; a returned `accepted:false` remains a rejection.
The native reader accepts at most 256 KiB of the complete `rawOutput`, including
its repeated text fields. Large and chunked bridge results still carry a receipt,
but output above that bound has no native correlation evidence. Error results
retain `isError`; deterministic tests cover errors, while the actual pinned
ARM64 executable has only been checked with a small two-block success response
and a local mock model. The captured pending/completed ACP frames are retained
in `src/drivers/acpx/fixtures/copilot-1.0.88-mcp-receipt-captured.json`, with
executable/capture hashes and sanitization recorded alongside. A regression
replays those frames through the production projector with the separately
owned receipt, plus missing-authority, altered-input/result, missing-content
and duplicate-terminal negatives. This is not paid or cross-platform qualification.
Native executable and distribution bytes are unchanged. The profile binds the
receipt, bridge and projector sources plus the complete permission-policy import
closure; retained v9 sessions are incompatible. Fresh packs and local/Daytona
qualification remain required. Completion feedback also preserves an explicitly
requested final-response format instead of overriding it with a summary request.
Historical source candidate (2026-09-30): **Copilot profile v9 is unqualified**.
Historical source candidate (2026-09-30): **Copilot profile v9 is unqualified**.
Typed edit permission callbacks now put a single bounded workspace-relative target
in the first canonical prompt (`Change file: path`). The same pure projector is
used by both runner paths and the bounded diagnostic notice. It checks `path`,
@@ -8,6 +37,40 @@ used by both runner paths and the bounded diagnostic notice. It checks `path`,
contents, diffs, commands, or arbitrary raw input. This is display context, not a
filesystem authorization or symlink-containment guarantee.
If the target is missing, outside the workspace, conflicting, malformed, too
large, contains control/direction-format characters, or would be redacted, the
request offers only the provider's one-time denial (when present) and cancellation.
Forged once/session grants are rejected. Raw `kind: edit` is required; titles do
not infer operation type. Non-edit permissions retain their existing behavior.
Default/full-auto selection is unchanged: callbacks handled by Paperclip receive
this check before any permission-mode fallback; no new automatic grant is added.
The existing transport policy still applies before permission handling.
The declaration binds the context projector, permission adapter, workspace path
validator, semantic redaction policy, and generated tool-operation classifier.
A recursive value-import test requires every non-builtin policy dependency to
remain in this source hash set; type-only imports do not affect execution.
The candidate v9 digest was refreshed before live admission to close this
transitive policy binding. No retained v8 evidence is regraded. Copilot's
native executable, patched inner distribution, and shared ACPX patch are unchanged;
the sidecar assets and runner's embedded admission digest change. Older profile
identities cannot be admitted as v9 or reused as matching warm sessions. Fresh
runtime packs/images and exact-revision local/Daytona qualification are pending.
Earlier denial cases establish their own no-write behavior; their generic
`Create file` card did not prove complete decision context. Deterministic adapter,
sidecar and direct-driver tests cover safe and denied context; no new live claim
or native USD/accounting capability is implied.
Historical v8 source candidate (2026-09-30): **Copilot profile v8 is unqualified**.
Its native executable, owned mapper and native distribution closures are unchanged
from v7, but its declaration binds the full shared ACPX patch. The patch's additive
Cursor metadata persistence changes those bytes, so v8 has a distinct command
digest and rejects v7 sessions. Copilot gains no usage or cost capability from this
change. Retained v7 paid cases below remain exact historical evidence, not v8
qualification. Fresh pack/image admission and the required exact-runtime local
and Daytona qualification remain outstanding.
If the target is missing, outside the workspace, conflicting, malformed, too
large, contains control/direction-format characters, or would be redacted, the
request offers only the provider's one-time denial (when present) and cancellation.
+29 -1
View File
@@ -1,6 +1,34 @@
# Cursor ACP capability inventory
Current qualification checkpoint (2026-09-30): **Cursor profile v9 remains unqualified.** Draft PR #14724 at `3adee6f3fc652d5f5ee40b2061a16cea0c7341f5` passes Apex 5/5 and all 51 check runs plus one context; one unchanged-head failed-job retry is recorded. It fixes future eval-notice preservation but does not regrade the retained strict protocol-accounting failure or establish native USD. The verified fixed $25 account-cycle cap resets October 28 and applies to account on-demand fees, not per-cell costs. The separate 15-test helper proposal is unintegrated and grants no launch authority. Profile v9 binds usage-v4 and three native closures; counters remain partial with unverified semantics. Local and Daytona qualification remain pending.
Current source candidate (2026-10-01): **Cursor profile v10 is unqualified**.
Native tool IDs containing C0, C1 or DEL control characters now use the same
bounded hash in permission details, passive evidence and the sidecar tool event.
Blank permission IDs are rejected because ACPX drops blank tool-event identity.
Other admitted IDs stay unchanged at this boundary; distinct IDs stay distinct.
Canonical tool execution then applies the existing Rust opaque-ID conversion.
For example, `tool/1` remains the native permission/evidence key while its
execution ID is the deterministic opaque hash. Lifecycle readers explicitly
convert between these keys; they must not compare them directly. Both-order
bridge tests cover this distinction, including 161-character IDs. The original ACP request and option identity
remain intact for response delivery. The declaration binds the identity helper,
permission adapter and evidence projector. Retained v9 sessions are incompatible.
The native distribution and its usage limits are unchanged. Deterministic tests
cover both permission/tool arrival orders and an unresolved real ACPX callback;
fresh local and Daytona qualification is still required.
Historical source candidate (2026-09-30): **Cursor profile v9 is unqualified**.
Its declaration binds `paperclip-cursor-usage-v4`, all three newly verified native
closures and the shared ACPX patch that persists bounded diagnostic observations.
Every native counter receipt remains partial with unverified semantics; it cannot
satisfy token or dollar accounting. The exact model remains unpriced until a
verified rate is available. Prior v7 source, builds and paid observations below
are historical and do not qualify v9. Old v7/v8 sessions must be reopened.
The v9 collector marks missing, invalid or reused child run ordinals as
`child_run_attribution_unverified`. The offline proof executes the pinned
vendor child creation and reuse methods on all three platforms; child counter
aggregation semantics remain unverified.
Historical qualification checkpoint (2026-09-30): **Cursor profile v9 remains unqualified.** Draft PR #14724 at `3adee6f3fc652d5f5ee40b2061a16cea0c7341f5` passes Apex 5/5 and all 51 check runs plus one context; one unchanged-head failed-job retry is recorded. It fixes future eval-notice preservation but does not regrade the retained strict protocol-accounting failure or establish native USD. The verified fixed $25 account-cycle cap resets October 28 and applies to account on-demand fees, not per-cell costs. The separate 15-test helper proposal is unintegrated and grants no launch authority. Profile v9 binds usage-v4 and three native closures; counters remain partial with unverified semantics. Local and Daytona qualification remain pending.
A separate native-question attempt ended without a captured
`cursor/ask_question` callback, and the model reported that AskQuestion was
@@ -1,5 +1,39 @@
# Rich ACP integration and qualification report
Current source checkpoint (2026-10-01): **Cursor v10, Copilot v10 and Pi v10
remain unqualified**. Cursor now shares the bounded native tool-ID mapping
across sidecar activity and permissions, then deterministically joins that key
to the canonical opaque execution ID. Copilot correlates native tool results with
authenticated, turn-bound semantic receipts instead of display names. Both new
profile identities reject v9 warm sessions. Their native distribution bytes
are unchanged; new sidecar assets, runner admission digests and fresh local/Daytona
qualification are required. The [Cursor](runner-cursor-capabilities.md) and
[Copilot](runner-copilot-capabilities.md) inventories describe the new contracts,
the Copilot 256 KiB output limit and the credential-free native proof scope.
Pi remains blocked on a verifiable OpenRouter spending cap. Prior paid failures
and case-specific passes remain historical; none is regraded by these fixes.
The controller now dispatches bridged requests in durable notification order.
It consumes earlier activity before presenting a request, while a pending human
answer does not prevent later activity from streaming. A genuine permission-first
provider sequence remains permission-first.
Historical source checkpoint (2026-09-30): **Cursor v9, Copilot v8 and Pi v10
remain unqualified**. All three declarations bind shared ACPX patch SHA-256
`bd5393058a218040d217fa85449d59a6f30507de54cd645bf0ef21422823f85e`.
Cursor additionally binds newly materialized `paperclip-cursor-usage-v4` closures;
Copilot and Pi native distribution bytes are unchanged. The new identities reject
retained 7/7/9 sessions, plus Cursor v8 sessions. Claude, Codex and Grok profile declarations stay unchanged.
The metadata is observation-only: native counters always remain partial, absent
fields stay absent, and no token totals or dollar costs are inferred. A supported
schema does not prove native counter aggregation semantics. No new paid pass,
build, publication or production qualification is claimed for these identities.
External eval definitions for 8/8/10 merged in [#35](https://github.com/paperclipai/paperclip-evals/pull/35)
as `25303cf84953985b961b95f89aff0bdb864b2d65`, from head
`b4ef1aa1296f8897714325d189e5a6f51dad9e01`: 136 deterministic tests,
21 validated cells, passing CI and Apex 5/5. Models, pricing and graders are
unchanged; this adds no paid proof. Those definitions remain the historical
Cursor v8 checkpoint and require a separate reviewed Cursor v9 update.
Current checkpoint (2026-09-30): **Cursor v9, Copilot v8 and Pi v10 remain unqualified.** The frozen runtime is `5c69b69ef2aeab8d8a367b25a8d894cc5308befa`; controller candidate is `a8df2064d68f40fbf4dec670c4b8478c4b1b1b3f`. All profiles bind shared ACPX patch SHA-256 `bd5393058a218040d217fa85449d59a6f30507de54cd645bf0ef21422823f85e`. No profile is promoted and no prior grade is changed.
Current-profile protocol eval definitions merged in [paperclip-evals #36](https://github.com/paperclipai/paperclip-evals/pull/36) as `d987357461933baca0d4c10cc081f40e7eae5c1b`: 136 deterministic tests and 21 validated cells. These definitions do not supply paid qualification evidence.
@@ -215,7 +215,7 @@ impl AcpxProviderDescriptor {
"2026.09.26-dd393fe",
None,
None,
"sha256:a76ad26878a3b3328154901563cbda857e53583e4e01787f35a797992ef76162",
"sha256:1df2a15b93bc3a14fa47fa3315344ba023fe2412048047cdc6f32096a6336564",
),
"copilot" => (
self.model.as_str(),
@@ -223,7 +223,7 @@ impl AcpxProviderDescriptor {
"1.0.88",
None,
None,
"sha256:98936d763497bd6f0e5605f52831a344f456357de58c457e440e69a1a468a2f4",
"sha256:c6741d7e49cd1af4ecad9e07181ef96305bde48b56dce2958547f2f066666231",
),
"grok" => (
"grok-4.7",
@@ -2803,7 +2803,7 @@ mod tests {
"cursor",
"cursor-agent",
"2026.09.26-dd393fe",
"sha256:a76ad26878a3b3328154901563cbda857e53583e4e01787f35a797992ef76162",
"sha256:1df2a15b93bc3a14fa47fa3315344ba023fe2412048047cdc6f32096a6336564",
None,
None,
"explicit-model",
@@ -2812,7 +2812,7 @@ mod tests {
"copilot",
"@github/copilot",
"1.0.88",
"sha256:98936d763497bd6f0e5605f52831a344f456357de58c457e440e69a1a468a2f4",
"sha256:c6741d7e49cd1af4ecad9e07181ef96305bde48b56dce2958547f2f066666231",
None,
None,
"explicit-model",
@@ -2843,6 +2843,19 @@ mod tests {
}
let valid: AcpxProviderDescriptor = serde_json::from_value(value.clone()).unwrap();
valid.validate(&context()).unwrap();
if matches!(agent, "cursor" | "copilot") {
let mut previous_v9 = value.clone();
previous_v9["commandDigest"] = json!(match agent {
"cursor" =>
"sha256:a76ad26878a3b3328154901563cbda857e53583e4e01787f35a797992ef76162",
"copilot" =>
"sha256:98936d763497bd6f0e5605f52831a344f456357de58c457e440e69a1a468a2f4",
_ => unreachable!(),
});
let previous_v9: AcpxProviderDescriptor =
serde_json::from_value(previous_v9).unwrap();
assert!(previous_v9.validate(&context()).is_err());
}
if agent == "cursor" {
let mut previous_v8 = value.clone();
previous_v8["commandDigest"] = json!(
@@ -7,7 +7,7 @@ import { COPILOT_VERSION, materializePinnedCopilotBinary, resolveCopilotDistribu
const MAX_ARCHIVE_BYTES = 128 * 1024 * 1024;
const MAX_EXPANDED_BYTES = 384 * 1024 * 1024;
const PROFILE_DIGEST = "sha256:98936d763497bd6f0e5605f52831a344f456357de58c457e440e69a1a468a2f4";
const PROFILE_DIGEST = "sha256:c6741d7e49cd1af4ecad9e07181ef96305bde48b56dce2958547f2f066666231";
/** Build-time only; outputRoot is the exact runner-owned platform asset directory. */
export async function buildPinnedCopilotDistribution({ outputRoot, platform = process.platform, architecture = process.arch }, { fetchImpl = fetch } = {}) {
@@ -28,7 +28,7 @@ export async function materializeCandidateProviderPack({ provider, outputRoot })
if (provider === "cursor") {
const result = await materializePinnedCursorDistribution({ destination: outputRoot });
return { version: result.version,
profileDigest: "sha256:a76ad26878a3b3328154901563cbda857e53583e4e01787f35a797992ef76162",
profileDigest: "sha256:1df2a15b93bc3a14fa47fa3315344ba023fe2412048047cdc6f32096a6336564",
closureDigest: `sha256:${result.closureSha256}` };
}
throw new Error(`The ${provider} candidate distribution builder is not included in this source revision`);
@@ -559,7 +559,9 @@ describe("native backend factory", () => {
it.each([
["cursor", "../../test/fixtures/cursor-acp/profile-v7-identity.json"],
["cursor", "../../test/fixtures/cursor-acp/profile-v9-identity.json"],
["copilot", "../../test/fixtures/copilot-profile-v7-identity.json"],
["copilot", "../../test/fixtures/copilot-profile-v9-identity.json"],
["pi", "../../test-fixtures/pi-acp/profile-v9-identity.json"],
] as const)("rejects the exact historical %s identity before runtime startup", (agent, path) => {
const historical = JSON.parse(readFileSync(new URL(path, import.meta.url), "utf8"));
@@ -1,6 +1,8 @@
import { appendSemanticToolReceipt } from "../drivers/semantic-tool-receipt.js";
import { acpxUsageEstimateNotice, persistedAcpxTurnUsage, persistedCursorUsageNotice } from "../drivers/acpx/usage-accounting.js";
import { stripTypeScriptTypes } from "node:module";
import { cursorPlanToolIdentity } from "../drivers/acpx/cursor-plan-tool-identity.js";
import { cursorPlanToolIdentity, cursorToolIdentity } from "../drivers/acpx/cursor-plan-tool-identity.js";
import { createHash } from "node:crypto";
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
@@ -96,6 +98,60 @@ describe("qualified ACPX runtime sidecar", () => {
expect(diagnostics).toEqual([]);
});
it.each(["tool-first", "permission-first"])("uses the same Cursor identity in actual sidecar tool and pending permission paths: %s", async order => {
const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8");
const identityStart = source.indexOf("function stableProviderIdentity(");
const stableIdentity = new Function("createHash", "cursorToolIdentity", `${stripTypeScriptTypes(source.slice(identityStart, source.indexOf("\nfunction canonicalJson", identityStart)))}; return stableProviderIdentity;`)(createHash, cursorToolIdentity);
const boundStart = source.indexOf("function boundRuntimeEventForNormalization(");
const bound = new Function("boundedOptionalText", "stableProviderIdentity", "safeAcpxLocations", "openParams", "safeOutput",
`${stripTypeScriptTypes(source.slice(boundStart, source.indexOf("\nfunction sanitizeRuntimeEvent", boundStart)))}; return boundRuntimeEventForNormalization;`)(
(value: unknown, fallback: string, max: number) => typeof value === "string" ? value.slice(0, max) : fallback,
stableIdentity, () => [], null, () => ({ output: null, outputBytes: 0, outputTruncated: false, outputDigest: null }),
);
const start = source.indexOf(" const { signal } = context;", source.indexOf("async function waitForPermission"));
const end = source.indexOf("\nasync function waitForInput", start);
const observedIds: string[] = [];
for (const rawId of ["native\u0000tool", "native\u007ftool", "native\u0085tool", "tool/1", "x".repeat(161), "safe-tool-1"]) {
const permissions = new Map<string, any>(); const emitted: any[] = []; const notices: any[] = [];
const evidence = createCursorToolEvidence({ sessionId: "session", turnId: "turn-1", workingDirectory: "/workspace", active: () => true,
emit: event => { validateAcpxRichEvent(event); notices.push(event); },
});
const wait = new Function("permissions", "normalizeAcpxPermission", "emit", `
let turnId="turn-1", requestSequence=0; const MAX_PENDING_INPUTS=512, openParams={agent:"cursor"};
const stableRequestId=()=>"request-1", requireAcpxResponseDelivery=c=>c.responseDelivery;
return async function(activeTurnId, agent, request, context, toolEvidence) { ${source.slice(start, end)}
`)(permissions, normalizeAcpxPermission, (_event: string, payload: unknown) => emitted.push(payload));
const origin = { type: "tool_call", tag: "tool_call", toolCallId: rawId, kind: "execute", status: "pending", rawInput: { command: "printf private-command" } };
// The sidecar emits this bounded runtime event; Rust applies the opaque
// execution-ID transform later. The direct TS driver normalizer is not
// this boundary and has a different fallback policy.
const activity = bound(origin);
const native = { sessionId: "session", inferredKind: "execute", raw: { sessionId: "session", toolCall: { toolCallId: rawId, kind: "execute" },
options: [{ kind: "reject_once", optionId: "native-original-denial", name: "Deny" }],
} };
const before = structuredClone(native);
const abort = new AbortController();
if (order === "tool-first") evidence.tool(origin);
const pending = wait("turn-1", "cursor", native, { signal: abort.signal, responseDelivery: Promise.resolve() }, evidence);
if (order === "permission-first") { expect(notices).toEqual([]); evidence.tool(origin); }
const projectedId = emitted[0].toolCallId;
observedIds.push(projectedId);
expect(projectedId).toBe(activity.toolCallId);
expect(notices.map(event => Object.fromEntries(event.payload.details.map((field: any) => [field.name, field.value])))).toEqual([
expect.objectContaining({ stage: "tool", toolCallId: projectedId }),
expect.objectContaining({ stage: "permission_requested", toolCallId: projectedId, requestId: "request-1" }),
]);
const held = permissions.get("request-1")!;
const decision = held.normalized.resolve({ action: "decline" });
held.cleanup(); permissions.delete("request-1"); held.settle(decision);
await expect(pending).resolves.toEqual({ outcome: "reject_once" });
expect(native).toEqual(before);
expect(native.raw.toolCall.toolCallId).toBe(rawId);
expect(JSON.stringify([activity, emitted, notices])).not.toContain("private-command");
}
expect(new Set(observedIds).size).toBe(6);
expect(observedIds.at(-1)).toBe("safe-tool-1");
});
it("emits the native plan tool identity from the actual sidecar input boundary", async () => {
const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8");
const start = source.indexOf("async function waitForExtensionInput(");
@@ -123,10 +179,10 @@ describe("qualified ACPX runtime sidecar", () => {
const emitted: unknown[] = [];
const create = new Function("createCopilotToolEvidence", "createCursorToolEvidence", "validateAcpxRichEvent", "emit", "agent", `
const activeHost = { identity: () => ({ backendSessionId: "session" }) };
let host = activeHost, turnId = "turn";
let host = activeHost, turnId = "turn", activeCopilotEvidence;
const currentTurnId = "turn", openParams = { agent, workingDirectory: "/workspace" };
const diagnostic = () => {};
${source.slice(start, end).replaceAll("openParams!", "openParams")}
${stripTypeScriptTypes(source.slice(start, end))}
return { evidence: toolEvidence, retire: () => { turnId = null; } };
`)(createCopilotToolEvidence, createCursorToolEvidence, validateAcpxRichEvent, (...args: unknown[]) => emitted.push(args), agent);
const tool = { type: "tool_call", tag: "tool_call", toolCallId: "tool", kind: "execute", status: "pending", rawInput: { command: "printf private-value" } };
@@ -141,6 +197,25 @@ describe("qualified ACPX runtime sidecar", () => {
expect(emitted).toHaveLength(agent === "pi" ? 0 : 1);
});
it("captures the actual sidecar bridge's Copilot receipt callback before turn replacement", () => {
const source = readFileSync(new URL("./acpx-runtime-sidecar.ts", import.meta.url), "utf8");
const start = source.indexOf(" semanticTools: {");
const end = source.indexOf(" onGoalUpdate:", start);
expect(start).toBeGreaterThan(0); expect(end).toBeGreaterThan(start);
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 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_v1", 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();
});
it("passes only validated Pi native boundaries and history through the real text sanitizer", () => {
const source = readFileSync(fileURLToPath(new URL("./acpx-runtime-sidecar.ts", import.meta.url)), "utf8");
const start = source.indexOf(' if (event.type === "text_delta") {', source.indexOf("function sanitizeRuntimeEvent"));
@@ -1,5 +1,5 @@
#!/usr/bin/env node
import { cursorPlanToolIdentity } from "../drivers/acpx/cursor-plan-tool-identity.js";
import { cursorPlanToolIdentity, cursorToolIdentity } from "../drivers/acpx/cursor-plan-tool-identity.js";
import { createHash } from "node:crypto";
import { createInterface } from "node:readline";
import { deliverAcpxResponse, requireAcpxResponseDelivery } from "../drivers/acpx/response-delivery.js";
@@ -152,6 +152,7 @@ let failedAdmissionCleanup: Promise<void> | null = null;
let openParams: AcpxSidecarOpenParams | null = null;
let runId: string | null = null;
let turnId: string | null = null;
let activeCopilotEvidence: CopilotToolEvidence | undefined;
let sequence = 0;
let requestSequence = 0;
let closing = false;
@@ -300,6 +301,7 @@ async function dispatch(
semanticTools: {
tools: params.tools,
handler: waitForTool,
...(params.agent === "copilot" ? { captureSemanticReceipt: () => activeCopilotEvidence?.captureSemanticReceipt() } : {}),
},
onGoalUpdate: (goal) => {
// Admission can emit a snapshot before the verified host is assigned.
@@ -383,6 +385,7 @@ async function dispatch(
emit: event => { validateAcpxRichEvent(event); emit("runtime.rich_event", { ...event }, currentTurnId); },
unavailable: () => diagnostic(`${openParams!.agent}_evidence_unavailable`, "ACP tool evidence is incomplete; permission and terminal outcomes are unchanged."),
});
activeCopilotEvidence = toolEvidence && "captureSemanticReceipt" in toolEvidence ? toolEvidence as CopilotToolEvidence : undefined;
let usageBefore: unknown;
try {
usageBefore = await readSidecarHostStatusWithin(activeHost);
@@ -1435,6 +1438,9 @@ function stableRequestId(
}
function stableProviderIdentity(value: string, kind: string): string {
// Keep native Cursor permission/evidence IDs identical to tool activity.
// This helper implements the same existing transform for all tool events.
if (kind === "tool") return cursorToolIdentity(value);
if (Buffer.byteLength(value) <= 240 && !/[\u0000-\u001f\u007f]/.test(value)) {
return value;
}
@@ -9,6 +9,15 @@ function request(kinds = ["allow_once", "allow_always", "reject_once"]): AcpPerm
} } as AcpPermissionRequest;
}
describe("ACP permission normalization", () => {
it.each([undefined, "codex", "claude", "pi", "copilot"])("preserves existing %s native identity behavior", provider => {
const native = request(); native.raw.toolCall.toolCallId = "native\u0000tool";
expect(normalizeAcpxPermission(native, { provider }).toolCallId).toBe("native\u0000tool");
});
it.each([undefined, null, "", " ", "x".repeat(241)])("rejects missing or oversized Cursor identities without deriving one from other fields", toolCallId => {
const native = request();
Object.assign(native.raw.toolCall, { toolCallId, itemId: "fallback", title: "safe-tool" });
expect(() => normalizeAcpxPermission(native, { provider: "cursor" })).toThrow("tool identity");
});
it("keeps requests answerable when a provider omits its operation title", () => {
for (const title of [undefined, "", " "]) {
const value = request();
@@ -1,5 +1,6 @@
import type { AcpPermissionDecision, AcpPermissionRequest } from "acpx/runtime";
import type { HarnessRuntimeRequestResolution } from "../../contracts/harness-driver.js";
import { cursorToolIdentity } from "./cursor-plan-tool-identity.js";
import { safeCopilotEditTarget } from "./copilot-permission-context.js";
@@ -32,7 +33,8 @@ export function normalizeAcpxPermission(request: AcpPermissionRequest, options:
byKind.set(option.kind, { optionId: option.optionId, name: option.name });
}
const call = raw.toolCall;
if (!call || typeof call.toolCallId !== "string" || !call.toolCallId || call.toolCallId.length > 240) {
if (!call || typeof call.toolCallId !== "string" || !call.toolCallId || call.toolCallId.length > 240
|| (options.provider === "cursor" && !call.toolCallId.trim())) {
throw new Error("ACP permission request omitted its tool identity");
}
const needsEditContext = options.provider === "copilot" && call.kind === "edit";
@@ -57,7 +59,9 @@ export function normalizeAcpxPermission(request: AcpPermissionRequest, options:
: typeof call.title === "string" && call.title.trim()
? call.title.slice(0, 4_000) : "Approve provider operation",
kind: request.inferredKind ?? "other",
toolCallId: call.toolCallId,
// Display/durable identity must match the tool-event boundary. Leave the
// original request intact for ACPX's exact native response correlation.
toolCallId: options.provider === "cursor" ? cursorToolIdentity(call.toolCallId) : call.toolCallId,
choices,
resolve(resolution) {
const outcome = bindings.get(resolution.action as AcpxPermissionAction);
@@ -1,5 +1,7 @@
import { appendSemanticToolReceipt } from "../semantic-tool-receipt.js";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { cursorToolIdentity } from "./cursor-plan-tool-identity.js";
import { describe, expect, it, vi } from "vitest";
import type { AcpRuntimeEvent } from "acpx/runtime";
@@ -24,6 +26,31 @@ import type {
import type { AcpxRecoveryWorkspaceLease } from "./runtime-sandbox.js";
describe("Codex ACPX harness driver", () => {
it.each(["copilot", "cursor", "pi", "codex"] as const)("scopes optional semantic receipts to the actual %s invocation turn", async agent => {
const fixture = driverFixture({ agent, model: "explicit-test-model", providerPolicy: { readOnly: true } }, { runtimeEvents: [] });
const session = await fixture.driver.openSession({ runId: "run-receipt", normalizedSessionId: "session-1", workingDirectory: "/workspace" });
const first = await session.startTurn({ message: { role: "user", text: "First" } });
const capture = fixture.hostOptions!.semanticTools!.captureSemanticReceipt;
expect(typeof capture).toBe(agent === "copilot" ? "function" : "undefined");
const oldCallback = capture?.();
const bound = appendSemanticToolReceipt({ tool: "get_task_context", callId: "1", arguments: {} }, { content: [{ type: "text", text: "{}" }] });
oldCallback?.(bound.receipt);
fixture.finishTurn({ status: "completed" });
const firstEvents = await collectUntil(session.events(), "turn.completed");
const receipts = firstEvents.filter(e => e.eventType === "provider.notice.recorded" && e.payload.category === "paperclip_semantic_tool_receipt_v1");
expect(receipts).toHaveLength(agent === "copilot" ? 1 : 0);
if (agent === "copilot") expect(receipts[0]).toMatchObject({ runId: "run-receipt", turnId: first.turnId, payload: { provenance: { sessionId: "backend-1", turnId: first.turnId } } });
const transcript = JSON.parse(JSON.stringify(await session.transcript!()));
for (const event of transcript.events) validatePrpEvent(event);
expect(transcript.events.filter((e: PrpEvent) => e.payload.category === "paperclip_semantic_tool_receipt_v1")).toEqual(receipts);
await session.startTurn({ message: { role: "user", text: "Second" } });
oldCallback?.(bound.receipt);
fixture.finishTurn({ status: "completed" });
const secondEvents = await collectUntil(session.events(), "turn.completed");
expect(secondEvents.filter(e => e.payload.category === "paperclip_semantic_tool_receipt_v1")).toEqual([]);
await session.close({ reason: "receipt turn scope verified" });
});
it.each(["cursor", "copilot"] as const)("emits partial Cursor metadata only for admitted Cursor, preserving %s settlement", async agent => {
const fixture = driverFixture({ agent, model: "explicit-test-model", providerPolicy: { readOnly: true } }, { runtimeEvents: [] });
const session = await fixture.driver.openSession({ runId: "run-native-usage", normalizedSessionId: "session-1", workingDirectory: "/workspace" });
@@ -1724,28 +1751,31 @@ describe("Codex ACPX harness driver", () => {
await session.close({ reason: "receipt checked" });
});
it.each(["written", "failed"] as const)("binds Cursor denial evidence to its original tool and response write: %s", async outcome => {
it.each(["cursor-tool", "native\u0000tool", "native\u007ftool"].flatMap(toolCallId => ["written", "failed"].map(outcome => ({ toolCallId, outcome }))))("binds Cursor denial evidence to its original tool and response write: $outcome/$toolCallId", async ({ outcome, toolCallId }) => {
const command = "printf 'sensitive-value' > /workspace/denied.txt";
const fixture = driverFixture({ agent: "cursor", model: "explicit-test-model", providerPolicy: { readOnly: false } }, {
runtimeEvents: [{ type: "tool_call", tag: "tool_call", toolCallId: "cursor-tool", title: "Run command", kind: "execute", status: "pending", rawInput: { command } }],
runtimeEvents: [{ type: "tool_call", tag: "tool_call", toolCallId, title: "Run command", kind: "execute", status: "pending", rawInput: { command } }],
});
const session = await fixture.driver.openSession({ runId: "run-cursor-receipt", normalizedSessionId: "session-1", workingDirectory: "/workspace" });
const origin = collectUntil(session.events(), "provider.notice.recorded");
const origin = collectUntil(session.events(), "tool.execution.started");
const { turnId } = await session.startTurn({ message: { text: "Request the command." } });
const originEvents = await origin;
const created = collectUntil(session.events(), "runtime_request.created");
const callback = fixture.host.startTurn.mock.calls[0]![0].onPermissionRequest!;
const receipt = deferred<void>();
const providerResponse = callback({ inferredKind: "execute", raw: {
sessionId: "backend-1", toolCall: { toolCallId: "cursor-tool", title: "Run command", kind: "execute" },
sessionId: "backend-1", toolCall: { toolCallId, title: "Run command", kind: "execute" },
options: [{ optionId: "deny", kind: "reject_once", name: "Deny" }],
} } as Parameters<typeof callback>[0], { signal: new AbortController().signal, responseDelivery: receipt.promise });
const requested = await created;
const request = session.pendingRuntimeRequests!()[0]!;
const projectedId = cursorToolIdentity(toolCallId);
expect(request.details).toMatchObject({ toolCallId: projectedId });
expect(originEvents.find(event => event.eventType === "tool.execution.started")!.payload.executionId).toBe(projectedId);
const evidence = (events: PrpEvent[]) => events.filter(event => event.eventType === "provider.notice.recorded" && event.payload.category === "cursor_tool_evidence_v1");
const fields = (event: PrpEvent) => Object.fromEntries((event.payload.details as Array<{ name: string; value: string }>).map(field => [field.name, field.value]));
const commandSha256 = `sha256:${createHash("sha256").update(command).digest("hex")}`;
expect(evidence(requested).map(fields)).toEqual([expect.objectContaining({ stage: "permission_requested", toolCallId: "cursor-tool", requestId: request.requestId, commandSha256, declineOffered: "true" })]);
expect(evidence(requested).map(fields)).toEqual([expect.objectContaining({ stage: "permission_requested", toolCallId: projectedId, requestId: request.requestId, commandSha256, declineOffered: "true" })]);
const settled = collectUntil(session.events(), outcome === "written" ? "runtime_request.resolved" : "runtime_request.expired");
let acknowledged = false;
const resolution = session.resolveRuntimeRequest!({ requestId: request.requestId, turnId, resolution: { action: "decline" } }).then(() => { acknowledged = true; });
@@ -472,6 +472,7 @@ export class CodexAcpxDriver implements HarnessDriver {
: {}),
...(input.signal === undefined ? {} : { signal: input.signal }),
semanticTools: {
...(this.#options.agent === "copilot" ? { captureSemanticReceipt: () => session?.captureSemanticReceipt() } : {}),
tools: this.#options.dynamicTools ?? [],
handler: (call) => {
if (!session) {
@@ -754,6 +755,7 @@ class CodexAcpxSession implements HarnessSession {
>;
#sourceSequence = 0;
#activeTurnId: string | null = null;
#copilotToolEvidence: CopilotToolEvidence | undefined;
#semanticResult: PrpStructuredRunResult | null = null;
#semanticFingerprint: string | null = null;
#semanticCallId: string | null = null;
@@ -913,6 +915,7 @@ class CodexAcpxSession implements HarnessSession {
if (!this.#emit(event.eventType, event.payload, { turnId, itemId: event.itemId })) throw new Error("ACP tool activity could not be retained");
},
});
this.#copilotToolEvidence = toolEvidence && "captureSemanticReceipt" in toolEvidence ? toolEvidence as CopilotToolEvidence : undefined;
let turn: AcpxRuntimeTurn;
const usageBefore = await readUsageStatus(this.#host);
try {
@@ -1109,6 +1112,10 @@ class CodexAcpxSession implements HarnessSession {
return { result: "handed_off", cleanup };
}
captureSemanticReceipt() {
return this.#copilotToolEvidence?.captureSemanticReceipt();
}
async dispatchTool(call: RunnerToolCall): Promise<unknown> {
this.#assertOpen();
if (this.#pendingTerminal) {
@@ -16,6 +16,13 @@ const PERMISSION_POLICY_SOURCES = [
["safe-locations.ts", "permissionLocationsSourceSha256"],
["../../semantic-tools/redaction.ts", "permissionRedactionSourceSha256"],
["generated-sidecar-contract.ts", "permissionClassifierSourceSha256"],
["cursor-plan-tool-identity.ts", "permissionIdentitySourceSha256"],
] as const;
const SEMANTIC_RECEIPT_SOURCES = [
["../semantic-tool-receipt.ts", "semanticReceiptSourceSha256"],
["../runner-tool-bridge.ts", "semanticBridgeSourceSha256"],
["copilot-tool-evidence.ts", "toolEvidenceSourceSha256"],
] as const;
// Walk executable imports, not just the projector's immediate dependencies.
@@ -44,11 +51,12 @@ async function permissionPolicyClosure(extraClassifierImport = false): Promise<S
vi.mock("./installation-integrity.js", () => ({ verifyNativeAcpxInstallation: vi.fn() }));
describe("Copilot build-owned installation", () => {
it("admits the current v9 declaration and binds its source policy/patch hashes", () => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/copilot-profile-v9-identity.json", import.meta.url), "utf8"));
it("admits the current v10 declaration and binds its source policy, receipts and patch hashes", () => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/copilot-profile-v10-identity.json", import.meta.url), "utf8"));
expect(identity.declaration.systemInstructionDelivery).toBe(COPILOT_SYSTEM_INSTRUCTION_DELIVERY);
expect(identity.declaration.sharedRuntimeContract).toBe("paperclip.acpx-runtime-contract.v1");
expect(identity.declaration.permissionContextContract).toBe(COPILOT_PERMISSION_CONTEXT_CONTRACT);
expect(identity.declaration.semanticToolReceiptContract).toBe("paperclip.semantic_tool_receipt.v1");
expect(identity.declaration.messageIdentityContract).toBe("copilot-native-message-id-v1");
expect(identity.declaration.ownedDistributionDelivery).toBe("COPILOT_CLI_DIST_DIR:lease-owned-guarded-inner-distribution:v1");
const inventory = JSON.parse(readFileSync(new URL("../../../test/fixtures/copilot-message-identity-distributions-1.0.88.json", import.meta.url), "utf8"));
@@ -58,7 +66,7 @@ describe("Copilot build-owned installation", () => {
expect(QUALIFIED_ACPX_PROFILES.copilot.commandDigest).toBe(identity.commandDigest);
const sorted = Object.fromEntries(Object.entries(identity.declaration).sort(([a], [b]) => a.localeCompare(b)));
expect(`sha256:${createHash("sha256").update(JSON.stringify(sorted)).digest("hex")}`).toBe(identity.commandDigest);
for (const [relative, field] of [...PERMISSION_POLICY_SOURCES, ["copilot-policy.ts", "policySha256"], ["../../../scripts/materialize-copilot-binary.mjs", "distributionSourceSha256"], ["../../../scripts/copilot-inner-distribution.mjs", "innerDistributionSourceSha256"], ["../../../../../patches/acpx@0.13.1.patch", "acpxPatchSha256"]]) {
for (const [relative, field] of [...PERMISSION_POLICY_SOURCES, ...SEMANTIC_RECEIPT_SOURCES, ["copilot-policy.ts", "policySha256"], ["../../../scripts/materialize-copilot-binary.mjs", "distributionSourceSha256"], ["../../../scripts/copilot-inner-distribution.mjs", "innerDistributionSourceSha256"], ["../../../../../patches/acpx@0.13.1.patch", "acpxPatchSha256"]]) {
expect(createHash("sha256").update(readFileSync(new URL(relative!, import.meta.url))).digest("hex")).toBe(identity.declaration[field!]);
}
expect(readFileSync(new URL("../../../scripts/build-copilot-distribution.mjs", import.meta.url), "utf8")).toContain(identity.commandDigest);
@@ -72,8 +80,8 @@ describe("Copilot build-owned installation", () => {
const bound = new Set(PERMISSION_POLICY_SOURCES.map(([path]) => new URL(path, import.meta.url).href));
expect([...closure].filter(path => !bound.has(path))).toEqual(["negative-control:unbound-policy"]);
});
it.each(PERMISSION_POLICY_SOURCES)("changing %s changes the candidate identity", (_path, field) => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/copilot-profile-v9-identity.json", import.meta.url), "utf8"));
it.each([...PERMISSION_POLICY_SOURCES, ...SEMANTIC_RECEIPT_SOURCES])("changing %s changes the candidate identity", (_path, field) => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/copilot-profile-v10-identity.json", import.meta.url), "utf8"));
identity.declaration[field] = "0".repeat(64);
const sorted = Object.fromEntries(Object.entries(identity.declaration).sort(([a], [b]) => a.localeCompare(b)));
expect(`sha256:${createHash("sha256").update(JSON.stringify(sorted)).digest("hex")}`).not.toBe(identity.commandDigest);
@@ -114,7 +122,7 @@ describe("Copilot build-owned installation", () => {
});
it("rejects changed profile identities before native file access", async () => {
vi.mocked(verifyNativeAcpxInstallation).mockClear();
for (const override of [{ agentServerVersion: "latest" }, { commandDigest: "sha256:untrusted" }, { commandDigest: "sha256:ed39259990cb0efda48d6105d2fa3599aac76873eb75cd80b4d0b179ce0579a6" }, { agent: "cursor" }, { agentProfileVersion: 1 }, { agentProfileVersion: 2 }, { agentProfileVersion: 3 }, { agentProfileVersion: 4 }, { agentProfileVersion: 5 }, { agentProfileVersion: 6 }, { agentProfileVersion: 7 }, { agentProfileVersion: 8 }]) {
for (const override of [{ agentServerVersion: "latest" }, { commandDigest: "sha256:untrusted" }, { commandDigest: "sha256:ed39259990cb0efda48d6105d2fa3599aac76873eb75cd80b4d0b179ce0579a6" }, { agent: "cursor" }, { agentProfileVersion: 1 }, { agentProfileVersion: 2 }, { agentProfileVersion: 3 }, { agentProfileVersion: 4 }, { agentProfileVersion: 5 }, { agentProfileVersion: 6 }, { agentProfileVersion: 7 }, { agentProfileVersion: 8 }, { agentProfileVersion: 9 }]) {
await expect(verifyCopilotInstallation({ ...QUALIFIED_ACPX_PROFILES.copilot, ...override } as never)).rejects.toThrow("exact pinned");
}
expect(verifyNativeAcpxInstallation).not.toHaveBeenCalled();
@@ -1,3 +1,4 @@
import { appendSemanticToolReceipt } from "../semantic-tool-receipt.js";
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { describe, expect, it, vi } from "vitest";
@@ -6,9 +7,9 @@ import type { CanonicalProviderEvent } from "../../provider-events.js";
import { createCopilotToolEvidence } from "./copilot-tool-evidence.js";
const fixture = JSON.parse(readFileSync(new URL("./fixtures/copilot-tool-evidence.json", import.meta.url), "utf8"));
const details = (e: CanonicalProviderEvent) => Object.fromEntries((e.payload.details as Array<{ name: string; value: string }>).map(d => [d.name, d.value]));
function harness(sessionId = "session") {
function harness(sessionId = "session", turnId = "turn") {
const events: CanonicalProviderEvent[] = []; let active = true;
const projector = createCopilotToolEvidence({ sessionId, turnId: "turn", workingDirectory: "/fixture/workspace", active: () => active,
const projector = createCopilotToolEvidence({ sessionId, turnId, workingDirectory: "/fixture/workspace", active: () => active,
emit: event => { validateAcpxRichEvent(event); events.push(event); } });
return { projector, events, stop: () => { active = false; } };
}
@@ -120,3 +121,88 @@ describe("Copilot active-turn tool evidence", () => {
for (let n = 0; n < 2200; n++) h.projector.tool(update("t0", "")); expect(h.events).toHaveLength(2048);
});
});
describe("Copilot authoritative semantic receipt correlation", () => {
const args = { summary: "PRIVATE", completionClaim: { objectiveSatisfied: true } };
const make = (operation = "paperclip_finish", isError = false) => appendSemanticToolReceipt(
{ tool: operation, callId: "3", arguments: args }, { content: [{ type: "text", text: '{"accepted":false}' }], ...(isError ? { isError } : {}) });
const terminal = (id: string, content: unknown, status = "completed") => ({ type: "tool_call", tag: "tool_call_update", toolCallId: id, status, rawOutput: { contents: content } });
it.each(["paperclip_finish", "report_progress", "get_task_context"])("correlates %s with trusted callback, not native display name", operation => {
const h = harness(); const bound = make(operation);
h.projector.tool({ ...tool("native", args, "other"), title: "unrelated display" });
h.projector.captureSemanticReceipt()!(bound.receipt);
h.projector.tool(terminal("native", bound.result.content));
const authoritative = h.events.find(e => e.payload.category === "paperclip_semantic_tool_receipt_v1")!;
expect(details(authoritative)).toMatchObject({ operationId: operation, callIdentitySha256: bound.receipt.callIdentitySha256, outcome: "returned" });
expect(authoritative.payload.provenance).toMatchObject({ method: "paperclip/semantic_tool_result", sessionId: "session", turnId: "turn" });
expect(details(h.events.at(-1)!)).toMatchObject({ semanticOperationId: operation, semanticOutcome: "returned", semanticResultSha256: bound.receipt.resultSha256 });
expect(JSON.stringify(h.events)).not.toMatch(/PRIVATE|accepted|completionClaim/);
});
it.each(["untrusted", "different-input", "different-result", "foreign-session", "foreign-turn", "duplicate-native", "duplicate-authority", "early-terminal", "wrong-status"])("rejects %s authority", scenario => {
const h = harness(), other = harness(scenario === "foreign-turn" ? "session" : "foreign", scenario === "foreign-turn" ? "other-turn" : "turn"); const bound = make();
h.projector.tool({ ...tool("native", scenario === "different-input" ? {} : args, "other"), title: "paperclip_finish" });
if (scenario === "early-terminal") h.projector.tool(terminal("native", bound.result.content));
if (scenario === "foreign-session" || scenario === "foreign-turn") other.projector.captureSemanticReceipt()!(bound.receipt);
else if (scenario !== "untrusted") h.projector.captureSemanticReceipt()!(bound.receipt);
if (scenario === "duplicate-authority") h.projector.captureSemanticReceipt()!(bound.receipt);
if (scenario === "duplicate-native") {
h.projector.tool(terminal("native", bound.result.content));
h.projector.tool(tool("second", args, "other"));
}
const output = structuredClone(bound.result.content);
if (scenario === "different-result") output[0]!.text = "changed";
h.projector.tool(terminal(scenario === "duplicate-native" ? "second" : "native", output, scenario === "wrong-status" ? "failed" : "completed"));
expect(details(h.events.at(-1)!)).not.toHaveProperty("semanticOperationId");
if (scenario === "duplicate-native") expect(h.events.map(details)).toContainEqual(expect.objectContaining({ reason: "semantic_receipt_conflict" }));
});
it("preserves admitted errors and fences late captured callbacks instead of rebinding", () => {
const h = harness(); const bound = make("get_task_context", true);
const captured = h.projector.captureSemanticReceipt()!;
h.projector.tool(tool("native", args, "other")); captured(bound.receipt);
h.projector.tool(terminal("native", bound.result.content, "failed"));
expect(details(h.events.at(-1)!)).toMatchObject({ semanticOutcome: "error", status: "failed" });
const count = h.events.length; h.stop(); captured(bound.receipt);
expect(h.events).toHaveLength(count);
const next = harness(); next.projector.tool(tool("native", args, "other")); next.projector.tool(terminal("native", bound.result.content, "failed"));
expect(details(next.events.at(-1)!)).not.toHaveProperty("semanticOperationId");
});
});
describe("captured Copilot 1.0.88 native MCP receipt carrier", () => {
const bytes = readFileSync(new URL("./fixtures/copilot-1.0.88-mcp-receipt-captured.json", import.meta.url));
const captured = JSON.parse(bytes.toString());
const provenance = JSON.parse(readFileSync(new URL("./fixtures/copilot-1.0.88-mcp-receipt-captured.provenance.json", import.meta.url), "utf8"));
const nativeEvent = (frame: any) => ({ ...frame.params.update, type: "tool_call", tag: frame.params.update.sessionUpdate });
it("replays native frames with the separately owned receipt and preserves rejection content", () => {
expect(createHash("sha256").update(bytes).digest("hex")).toBe(provenance.fixtureSha256);
expect(provenance).toMatchObject({ nativeVersion: "1.0.88", paidProviderCalls: 0, qualification: false });
expect(captured.pending.params.sessionId).toBe(captured.completed.params.sessionId);
const h = harness(captured.pending.params.sessionId);
h.projector.tool(nativeEvent(captured.pending));
h.projector.captureSemanticReceipt()!(captured.authoritativeReceipt);
h.projector.tool(nativeEvent(captured.completed));
const output = captured.completed.params.update.rawOutput;
expect(output.content).toBe(output.contents.map((block: { text: string }) => block.text).join(""));
expect(output.detailedContent).toBe(output.content);
expect(JSON.parse(output.contents[0].text)).toMatchObject({ accepted: false });
expect(details(h.events.at(-1)!)).toMatchObject({ stage: "tool", status: "completed",
semanticOperationId: captured.authoritativeReceipt.operationId,
semanticCallIdentitySha256: captured.authoritativeReceipt.callIdentitySha256,
semanticInputSha256: captured.authoritativeReceipt.inputSha256,
semanticResultSha256: captured.authoritativeReceipt.resultSha256, semanticOutcome: "returned" });
expect(JSON.stringify(h.events)).not.toContain("known-small-result");
});
it.each(["missing-authority", "altered-block", "different-input", "missing-contents", "duplicate-terminal"])("does not trust captured native output alone: %s", scenario => {
const value = structuredClone(captured), h = harness(value.pending.params.sessionId);
if (scenario === "different-input") value.pending.params.update.rawInput = { changed: true };
if (scenario === "altered-block") value.completed.params.update.rawOutput.contents[0].text = '{"accepted":true}';
if (scenario === "missing-contents") delete value.completed.params.update.rawOutput.contents;
h.projector.tool(nativeEvent(value.pending));
if (scenario !== "missing-authority") h.projector.captureSemanticReceipt()!(value.authoritativeReceipt);
h.projector.tool(nativeEvent(value.completed));
if (scenario === "duplicate-terminal") h.projector.tool(nativeEvent(value.completed));
expect(details(h.events.at(-1)!)).not.toHaveProperty("semanticOperationId");
if (scenario === "duplicate-terminal") expect(details(h.events.at(-1)!)).toMatchObject({ stage: "evidence_incomplete", reason: "reused_semantic_lifecycle" });
});
});
@@ -1,3 +1,4 @@
import { parseSemanticToolReceipt, readNativeSemanticReceipt, sameSemanticReceipt, semanticInputSha256, type SemanticToolReceipt } from "../semantic-tool-receipt.js";
import { updateSingleReadEvidence, type SingleReadEvidence } from "./single-read-evidence.js";
import { createHash } from "node:crypto";
import { redactPaperclipSemanticValue } from "../../semantic-tools/redaction.js";
@@ -7,7 +8,7 @@ import { safeCopilotEditTarget } from "./copilot-permission-context.js";
const LIMIT = 256;
const CATEGORY = "copilot_tool_evidence_v1";
type Fields = Record<string, string | number | boolean>;
interface Tool { kind?: string; input?: string; fields: Fields; invalid?: boolean; read?: SingleReadEvidence }
interface Tool { kind?: string; input?: string; fields: Fields; invalid?: boolean; semanticInput?: string; semanticReceipt?: SemanticToolReceipt; read?: SingleReadEvidence }
const record = (v: unknown): Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : {};
const identity = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 240 && !/[\u0000-\u001f\u007f]/u.test(v);
const shellIdentity = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z0-9_.-]{1,80}$/u.test(v);
@@ -27,6 +28,8 @@ export function createCopilotToolEvidence(binding: {
const tools = new Map<string, Tool>();
const shells = new Map<string, string | null>();
const permissionTools = new Set<string>();
const semanticReceipts = new Map<string, SemanticToolReceipt | null>();
const matchedReceipts = new Map<string, string>();
let sequence = 0;
let incomplete = false;
let broken = false;
@@ -40,7 +43,7 @@ export function createCopilotToolEvidence(binding: {
return;
}
}
function notice(stage: string, toolCallId: string, fields: Fields, method = "session/update") {
function notice(stage: string, toolCallId: string | undefined, fields: Fields, method = "session/update", category = CATEGORY) {
if (!binding.active() || !identity(binding.sessionId) || !identity(binding.turnId)) return;
if (sequence >= 2048) {
if (incomplete) return;
@@ -49,8 +52,8 @@ export function createCopilotToolEvidence(binding: {
const itemId = `copilot-evidence-${digest(`${binding.sessionId}:${binding.turnId}`).slice(0, 24)}-${++sequence}`;
binding.emit({ eventType: "provider.notice.recorded", itemId, payload: redactPaperclipSemanticValue({
schema: "paperclip.provider.notice.v1", noticeId: itemId, severity: "info",
category: CATEGORY, scope: "turn", recoverable: true, userActionable: false,
summary: stage === "evidence_incomplete" ? "Some Copilot activity details are unavailable."
category, scope: "turn", recoverable: true, userActionable: false,
summary: stage === "semantic_result" ? "Paperclip returned a semantic tool result." : stage === "evidence_incomplete" ? "Some Copilot activity details are unavailable."
: stage === "permission_requested" ? "Copilot requested permission."
: stage === "permission_delivered" ? (fields.outcome === "reject_once" ? "Copilot received your denial." : "Copilot received your permission decision.")
: fields.shellState === "started" ? (fields.detach === false ? "Copilot started an attached command." : "Copilot started a background command.")
@@ -58,7 +61,7 @@ export function createCopilotToolEvidence(binding: {
: fields.operation === "edit" ? `Copilot file operation: ${fields.status}.`
: `Copilot tool operation: ${fields.status}.`,
provenance: { method, eventType: stage, sessionId: binding.sessionId, turnId: binding.turnId },
details: Object.entries({ stage, toolCallId, ...fields }).map(([name, value]) => ({ name, value: String(value) })),
details: Object.entries({ stage, ...(toolCallId === undefined ? {} : { toolCallId }), ...fields }).map(([name, value]) => ({ name, value: String(value) })),
}) as Record<string, unknown> });
}
function inputFields(call: Record<string, unknown>): Fields {
@@ -93,12 +96,18 @@ export function createCopilotToolEvidence(binding: {
state = { fields: {} }; tools.set(id, state);
} else if (call.tag === "tool_call") { state.invalid = true; notice("evidence_incomplete", id, { reason: "reused_tool_origin" }); }
if (state.invalid) return;
if (state.semanticReceipt) { state.invalid = true; notice("evidence_incomplete", id, { reason: "reused_semantic_lifecycle" }); return; }
if (typeof call.kind === "string") {
if (state.kind && state.kind !== call.kind) { state.invalid = true; notice("evidence_incomplete", id, { reason: "changed_tool_kind" }); return; }
state.kind = call.kind;
}
if (state.kind === "read") state.read = updateSingleReadEvidence(state.read, call, binding.workingDirectory);
if (call.rawInput !== undefined) {
// Retain only a bounded digest of the native arguments, never their text.
let inputDigest: string | undefined;
try { if (Buffer.byteLength(JSON.stringify(call.rawInput)) <= 1024 * 1024) inputDigest = semanticInputSha256(call.rawInput); } catch { /* Malformed input cannot correlate. */ }
if (state.semanticInput && inputDigest !== state.semanticInput) { state.invalid = true; notice("evidence_incomplete", id, { reason: "changed_tool_input" }); return; }
state.semanticInput = inputDigest;
const fields = inputFields({ ...call, kind: state.kind });
const fingerprint = JSON.stringify(fields);
if (state.input && state.input !== fingerprint) { state.invalid = true; notice("evidence_incomplete", id, { reason: "changed_tool_input" }); return; }
@@ -127,6 +136,27 @@ export function createCopilotToolEvidence(binding: {
}
}
}
if (call.rawOutput !== undefined) {
const candidate = readNativeSemanticReceipt(call.rawOutput);
if (candidate) {
const authoritative = semanticReceipts.get(candidate.callIdentitySha256);
const previous = matchedReceipts.get(candidate.callIdentitySha256);
if ((status !== "completed" && status !== "failed") || !authoritative
|| !sameSemanticReceipt(authoritative, candidate) || state.semanticInput !== candidate.inputSha256
|| (status === "failed") !== (candidate.outcome === "error") || previous !== undefined) {
state.invalid = true;
notice("evidence_incomplete", id, { reason: "semantic_receipt_conflict" });
return;
}
matchedReceipts.set(candidate.callIdentitySha256, id);
state.semanticReceipt = candidate;
fields.semanticOperationId = candidate.operationId;
fields.semanticCallIdentitySha256 = candidate.callIdentitySha256;
fields.semanticInputSha256 = candidate.inputSha256;
fields.semanticResultSha256 = candidate.resultSha256;
fields.semanticOutcome = candidate.outcome;
}
}
notice("tool", id, fields);
},
permission(request: unknown, requestId: string, offeredActions: readonly string[]) {
@@ -148,6 +178,21 @@ export function createCopilotToolEvidence(binding: {
},
};
return {
captureSemanticReceipt(): ((receipt: SemanticToolReceipt) => void) | undefined {
if (!binding.active()) return undefined;
// This closure belongs to this turn, even if a successor becomes active.
return receipt => { safely(() => {
if (!binding.active()) return;
const parsed = parseSemanticToolReceipt(receipt);
if (!parsed || semanticReceipts.size >= LIMIT || semanticReceipts.has(parsed.callIdentitySha256)) {
if (parsed && semanticReceipts.has(parsed.callIdentitySha256)) semanticReceipts.set(parsed.callIdentitySha256, null);
notice("evidence_incomplete", "semantic", { reason: "ambiguous_semantic_receipt" });
return;
}
semanticReceipts.set(parsed.callIdentitySha256, parsed);
notice("semantic_result", undefined, { ...parsed }, "paperclip/semantic_tool_result", "paperclip_semantic_tool_receipt_v1");
}); };
},
tool: (event: unknown) => { safely(() => projection.tool(event)); },
permission: (request: unknown, requestId: string, offeredActions: readonly string[]) => safely(() => projection.permission(request, requestId, offeredActions)),
};
@@ -22,7 +22,7 @@ it("matches build materializer pins and launches only package-owned complete dis
it("rejects profile substitutions before reading any native distribution", async () => {
const base = { ...QUALIFIED_ACPX_PROFILES.cursor, qualificationModel: "explicit", reportedModelId: "explicit" };
for (const profile of [QUALIFIED_ACPX_PROFILES.cursor, { ...base, agentServerVersion: "latest" }, { ...base, commandDigest: "forged" }, { ...base, reportedModelId: "different" }, { ...base, agentProfileVersion: 7 as const }, { ...base, agentProfileVersion: 8 as const }]) {
for (const profile of [QUALIFIED_ACPX_PROFILES.cursor, { ...base, agentServerVersion: "latest" }, { ...base, commandDigest: "forged" }, { ...base, reportedModelId: "different" }, { ...base, agentProfileVersion: 7 as const }, { ...base, agentProfileVersion: 8 as const }, { ...base, agentProfileVersion: 9 as const }]) {
await expect(verifyCursorInstallation(profile)).rejects.toThrow("exact pinned profile");
}
});
@@ -0,0 +1,101 @@
import { spawn, type ChildProcess } from "node:child_process";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createAcpRuntime, createAgentRegistry, createRuntimeStore, type AcpPermissionRequest } from "acpx/runtime";
import { expect, it } from "vitest";
import { normalizeAcpxPermission } from "./acp-permission-adapter.js";
import { cursorToolIdentity } from "./cursor-plan-tool-identity.js";
import { createCursorToolEvidence } from "./cursor-tool-evidence.js";
import { validateAcpxRichEvent } from "./profile-extensions.js";
const rawIds = ["native\u0000tool", "native\u007ftool", "native\u0085tool", "tool/1", "x".repeat(161), "safe-tool-1"];
// Synthetic protocol fixture, not a claim about the unretained paid wire bytes.
// Native permission deliberately omits rawInput, matching pinned Cursor's shape.
const peer = String.raw`
const ids=['native\u0000tool','native\u007ftool','native\u0085tool','tool/1','x'.repeat(161),'safe-tool-1'];
const send=x=>process.stdout.write(JSON.stringify({jsonrpc:'2.0',...x})+'\n');
let promptId, index=0;
function next() {
if(index===ids.length) { send({id:promptId,result:{stopReason:'end_turn'}}); return; }
const tool={method:'session/update',params:{sessionId:'native',update:{sessionUpdate:'tool_call',toolCallId:ids[index],kind:'execute',title:'Run command',status:'pending',rawInput:{command:'printf fixture-'+index}}}};
const permission={id:index,method:'session/request_permission',params:{sessionId:'native',toolCall:{toolCallId:ids[index],kind:'execute',title:'Run command',status:'pending'},options:[{kind:'reject_once',optionId:'native-denial-'+index,name:'Deny'}]}};
for(const frame of process.env.ORDER==='tool-first'?[tool,permission]:[permission,tool])send(frame);
}
require('node:readline').createInterface({input:process.stdin}).on('line',line=>{
const m=JSON.parse(line);
if(m.method==='initialize')send({id:m.id,result:{protocolVersion:1,agentCapabilities:{},authMethods:[]}});
else if(m.method==='session/new')send({id:m.id,result:{sessionId:'native'}});
else if(m.method==='session/prompt'){promptId=m.id;next();}
else if(m.id===index&&!m.method){
if(m.result?.outcome?.outcome!=='selected'||m.result.outcome.optionId!=='native-denial-'+index){process.exitCode=2;process.stdin.destroy();return;}
index++;next();
}
});`;
it.each(["tool-first", "permission-first"])("real ACPX streams Cursor tool origins while native permission callbacks remain held: %s", async order => {
const cwd = await mkdtemp(join(tmpdir(), "cursor-permission-identity-"));
const children: ChildProcess[] = [];
const pending: Array<{ request: AcpPermissionRequest; before: AcpPermissionRequest; release(): void; delivery: Promise<void> | undefined }> = [];
const replies: unknown[] = [];
const fields: Array<Record<string, string>> = [];
let promptSettled = false;
const evidence = createCursorToolEvidence({ sessionId: "native", turnId: "turn", workingDirectory: cwd, active: () => true,
emit: event => { validateAcpxRichEvent(event); fields.push(Object.fromEntries((event.payload.details as Array<{ name: string; value: string }>).map(field => [field.name, field.value]))); },
});
const runtime = createAcpRuntime({ cwd, agentRegistry: createAgentRegistry({ overrides: { cursor: "fixture" } }), sessionStore: createRuntimeStore({ stateDir: join(cwd, "state") }), permissionMode: "approve-reads", authPolicy: "skip",
spawnAgent: () => { const child = spawn(process.execPath, ["-e", peer], { cwd, env: { ORDER: order }, stdio: ["pipe", "pipe", "pipe"] }); children.push(child); return child; },
onAcpMessage: (direction, value) => {
const message = value as { id?: number; result?: { outcome?: unknown } };
if (direction === "outbound" && message.result?.outcome) replies.push(structuredClone(message));
},
onPermissionRequest: async (request, context) => {
const before = structuredClone(request);
const normalized = normalizeAcpxPermission(request, { provider: "cursor" });
const delivered = evidence.permission(request, `request-${pending.length}`, normalized.choices.map(choice => choice.key));
const gate = Promise.withResolvers<void>();
pending.push({ request, before, release: gate.resolve, delivery: context.responseDelivery });
await gate.promise;
const decision = normalized.resolve({ action: "decline" });
// Delivery is observed outside this callback; waiting here would deadlock
// the ACP response writer that must receive the callback result first.
void context.responseDelivery?.then(() => delivered?.(decision.outcome));
return decision;
},
});
let handle: Awaited<ReturnType<typeof runtime.ensureSession>> | undefined;
let drain: Promise<void> | undefined;
try {
handle = await runtime.ensureSession({ sessionKey: "identity-fixture", agent: "cursor", mode: "persistent", cwd });
const turn = runtime.startTurn({ handle, text: "fixture", mode: "prompt", requestId: "turn", timeoutMs: 5_000 });
void turn.result.then(() => { promptSettled = true; });
drain = (async () => { for await (const event of turn.events) evidence.tool(event); })();
for (const [index, rawId] of rawIds.entries()) {
await expect.poll(() => fields.some(row => row.stage === "permission_requested" && row.requestId === `request-${index}`), { timeout: 2_000 }).toBe(true);
expect(promptSettled).toBe(false);
expect(replies).toHaveLength(index);
const held = pending[index]!;
expect(held.request.raw.toolCall.toolCallId).toBe(rawId);
const projectedId = cursorToolIdentity(rawId);
const related = fields.filter(row => row.toolCallId === projectedId);
expect(related.map(row => row.stage)).toEqual(["tool", "permission_requested"]);
expect(related[1]).toMatchObject({ requestId: `request-${index}`, declineOffered: "true", commandSha256: related[0]!.commandSha256 });
expect(held.request).toEqual(held.before);
held.release();
await held.delivery;
expect(replies[index]).toEqual({ jsonrpc: "2.0", id: index, result: { outcome: { outcome: "selected", optionId: `native-denial-${index}` } } });
}
await expect(turn.result).resolves.toMatchObject({ status: "completed" });
await drain;
expect(new Set(fields.map(row => row.toolCallId)).size).toBe(rawIds.length);
expect(fields.some(row => row.stage === "evidence_incomplete")).toBe(false);
} finally {
pending.forEach(value => value.release());
if (handle) await runtime.close({ handle, reason: "fixture complete" });
for (const child of children) if (child.exitCode === null && child.signalCode === null) {
const exited = new Promise(resolve => child.once("exit", resolve)); child.kill("SIGKILL"); await exited;
}
await drain;
await rm(cwd, { recursive: true, force: true });
}
}, 10_000);
@@ -2,8 +2,8 @@ import { createHash } from "node:crypto";
import type { AcpxExtensionInput } from "./profile-extensions.js";
// Match the sidecar's provider identity boundary before Rust's opaque tool ID.
function boundedToolIdentity(value: string): string {
if (Buffer.byteLength(value) <= 240 && !/[\u0000-\u001f\u007f]/.test(value)) return value;
export function cursorToolIdentity(value: string): string {
if (Buffer.byteLength(value) <= 240 && !/[\u0000-\u001f\u007f-\u009f]/.test(value)) return value;
return `acpx-tool-${createHash("sha256").update("paperclip.acpx.provider-identity.v1\0tool\0").update(value).digest("hex")}`;
}
@@ -12,12 +12,12 @@ export function cursorPlanToolIdentity(agent: string | null | undefined, input:
if (agent !== "cursor" || input.method !== "cursor/create_plan") return undefined;
const value = input.details?.toolCallId;
if (typeof value !== "string" || !value.trim() || value.length > 1_000) throw new Error("Cursor plan omitted its bounded tool identity");
return boundedToolIdentity(value);
return cursorToolIdentity(value);
}
/** Direct-driver counterpart of Rust acpx_opaque_item_id(..., "tool"). */
export function cursorToolExecutionId(value: string): string {
const bounded = boundedToolIdentity(value);
const bounded = cursorToolIdentity(value);
if (/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/.test(bounded)) return bounded;
return `acpx-tool-${createHash("sha256").update("paperclip.acpx.opaque-item.v1\0tool\0").update(bounded).digest("hex")}`;
}
@@ -1,6 +1,8 @@
import { expect, it } from "vitest";
import { validateAcpxRichEvent } from "./profile-extensions.js";
import { createCursorToolEvidence } from "./cursor-tool-evidence.js";
import { cursorToolIdentity } from "./cursor-plan-tool-identity.js";
import { normalizeAcpxPermission } from "./acp-permission-adapter.js";
const initial = { type: "tool_call", tag: "tool_call", toolCallId: "tool", kind: "execute", status: "pending", rawInput: { command: "printf 'secret-canary' > '/fixture/denied.txt'" } };
const request = { raw: { sessionId: "session", toolCall: { toolCallId: "tool", kind: "execute" } } };
@@ -23,6 +25,52 @@ it("waits for the original iterator event when permission arrives before the que
const s = setup(); const delivered = s.p.permission(request, "request", ["decline"]); expect(s.events).toHaveLength(0);
s.p.tool(initial); delivered!("reject_once"); expect(s.fields().map(x => x.stage)).toEqual(["tool", "permission_requested", "permission_delivered"]);
});
it.each(["tool-first", "permission-first"])("correlates opaque C0/C1/DEL native identities in %s order without changing native requests", order => {
const s = setup();
const rawIds = ["native\u0000tool", "native\u007ftool", "native\u0085tool", "tool/1", "x".repeat(161), "safe-tool-1"];
const expectedIds = rawIds.map(cursorToolIdentity);
expect(new Set(expectedIds).size).toBe(rawIds.length);
expect(expectedIds.slice(0, 3).every(value => /^acpx-tool-[a-f0-9]{64}$/.test(value))).toBe(true);
expect(expectedIds.at(-1)).toBe("safe-tool-1");
for (const [index, toolCallId] of rawIds.entries()) {
const native = { sessionId: "session", inferredKind: "execute" as const, raw: {
sessionId: "session", toolCall: { toolCallId, kind: "execute" },
options: [{ kind: "reject_once" as const, optionId: `native-denial-${index}`, name: "Deny" }],
} };
const before = structuredClone(native);
const normalized = normalizeAcpxPermission(native, { provider: "cursor" });
expect(normalized.toolCallId).toBe(expectedIds[index]);
if (order === "tool-first") s.p.tool({ ...initial, toolCallId });
const delivered = s.p.permission(native, `request-${index}`, normalized.choices.map(choice => choice.key));
if (order === "permission-first") {
expect(s.fields().filter(row => row.toolCallId === expectedIds[index])).toEqual([]);
s.p.tool({ ...initial, toolCallId });
}
const rows = () => s.fields().filter(row => row.toolCallId === expectedIds[index]);
expect(rows().map(row => row.stage)).toEqual(["tool", "permission_requested"]);
expect(rows()[1]).toMatchObject({ requestId: `request-${index}`, declineOffered: "true", operation: "execute", commandSha256: rows()[0].commandSha256 });
const response = normalized.resolve({ action: "decline" });
expect(response).toEqual({ outcome: "reject_once" });
delivered!(response.outcome);
expect(rows().map(row => row.stage)).toEqual(["tool", "permission_requested", "permission_delivered"]);
expect(native).toEqual(before);
expect(native.raw.toolCall.toolCallId).toBe(toolCallId);
}
expect(s.unavailable()).toBe(false);
expect(JSON.stringify(s.events)).not.toContain("secret-canary");
expect(JSON.stringify(s.events)).not.toContain("native\\u0000tool");
});
it("never associates different opaque native IDs through a matching title or command", () => {
const s = setup();
s.p.tool({ ...initial, toolCallId: "native\u0000tool", title: "same title" });
const delivered = s.p.permission({ raw: { sessionId: "session", toolCall: {
toolCallId: "native\u007ftool", title: "same title", kind: "execute", rawInput: initial.rawInput,
} } }, "request", ["decline"]);
delivered!("reject_once");
expect(s.fields().map(row => row.stage)).toEqual(["tool"]);
expect(s.fields()[0].toolCallId).toBe(cursorToolIdentity("native\u0000tool"));
});
it("cannot invent origin from permission or a terminal delta", () => {
const s = setup(); const delivered = s.p.permission(request, "request", ["decline"]); delivered!("reject_once");
s.p.tool({ type: "tool_call", tag: "tool_call_update", toolCallId: "tool", kind: "execute", status: "failed", rawInput: initial.rawInput }); expect(s.events).toHaveLength(0);
@@ -62,7 +110,7 @@ it("rejects commands missing from their original frame and bounded oversized inp
});
it.each([
["invalid_permission_tool_identity", { raw: { ...request.raw, toolCall: { ...request.raw.toolCall, toolCallId: "private-argument\ncanary" } } }, "request"],
["invalid_permission_tool_identity", { raw: { ...request.raw, toolCall: { ...request.raw.toolCall, toolCallId: "" } } }, "request"],
["invalid_request_identity", request, "private-request\ncanary"],
["invalid_permission_kind", { raw: { ...request.raw, toolCall: { ...request.raw.toolCall, kind: "private-kind\ncanary" } } }, "request"],
] as const)("distinguishes %s without retaining malformed provider input", (reason, nativeRequest, requestId) => {
@@ -2,9 +2,13 @@ import { updateSingleReadEvidence, type SingleReadEvidence } from "./single-read
import { createHash } from "node:crypto";
import { redactPaperclipSemanticValue } from "../../semantic-tools/redaction.js";
import type { CanonicalProviderEvent } from "../../provider-events.js";
import { cursorToolIdentity } from "./cursor-plan-tool-identity.js";
const rec = (v: unknown): Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : {};
const id = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 240 && !/[\u0000-\u001f\u007f]/u.test(v);
// ACP tool identities are opaque provider strings. Apply the existing bounded
// tool identity transform rather than rejecting IDs accepted by the ACP SDK.
const nativeToolId = (v: unknown): string | undefined => typeof v === "string" && v.length > 0 && v.length <= 240 ? cursorToolIdentity(v) : undefined;
const digest = (s: string) => createHash("sha256").update(s).digest("hex");
type Fields = Record<string, string | boolean>;
type Tool = { kind?: string; commandSha256?: string; read?: SingleReadEvidence };
@@ -72,8 +76,9 @@ export function createCursorToolEvidence(binding: {
return {
tool(event: unknown) { safely(() => {
if (!binding.active()) return;
const call = rec(event); if (call.type !== "tool_call" || !id(call.toolCallId)) return;
const toolId = call.toolCallId; let state = tools.get(toolId);
const call = rec(event); if (call.type !== "tool_call") return;
const toolId = nativeToolId(call.toolCallId); if (toolId === undefined) return;
let state = tools.get(toolId);
if (!state) {
if (call.tag !== "tool_call") return;
if (tools.size >= 256) throw new ProjectionFailure("tool_limit");
@@ -102,9 +107,9 @@ export function createCursorToolEvidence(binding: {
if (!binding.active()) return;
const raw = rec(rec(request).raw), call = rec(raw.toolCall);
if (raw.sessionId !== binding.sessionId) throw new ProjectionFailure("permission_session_mismatch");
if (!id(call.toolCallId)) throw new ProjectionFailure("invalid_permission_tool_identity");
const toolId = nativeToolId(call.toolCallId);
if (toolId === undefined) throw new ProjectionFailure("invalid_permission_tool_identity");
if (!id(requestId)) throw new ProjectionFailure("invalid_request_identity");
const toolId = call.toolCallId;
if (permissions.has(toolId) || permissions.size >= 256) throw new ProjectionFailure("ambiguous_permission");
if (call.kind !== undefined && (!id(call.kind) || call.kind.length > 64)) throw new ProjectionFailure("invalid_permission_kind");
const state: Permission = { requestId, kind: call.kind as string | undefined, hasInput: call.rawInput !== undefined, commandSha256: command(call), declineOffered: offeredActions.includes("decline") };
@@ -0,0 +1,60 @@
{
"pending": {
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "captured-fixture-session",
"update": {
"sessionUpdate": "tool_call",
"toolCallId": "fixture-tool",
"title": "receipt-receipt_fixture",
"kind": "other",
"status": "pending",
"rawInput": {}
}
}
},
"completed": {
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "captured-fixture-session",
"update": {
"sessionUpdate": "tool_call_update",
"toolCallId": "fixture-tool",
"status": "completed",
"content": [
{
"type": "content",
"content": {
"type": "text",
"text": "{\"fixture\":\"known-small-result\",\"accepted\":false}{\"schema\":\"paperclip.semantic_tool_receipt.v1\",\"operationId\":\"receipt_fixture\",\"callIdentitySha256\":\"8880622e75a82af5d9b588823af9d706f2bf3a04dce96ee9aab2fa4a91c55508\",\"inputSha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\",\"resultSha256\":\"b325c663fc4bb7617a745373367ca8cbc7a3445f1b2fdb3a2a151da39f73553c\",\"outcome\":\"returned\"}"
}
}
],
"rawOutput": {
"content": "{\"fixture\":\"known-small-result\",\"accepted\":false}{\"schema\":\"paperclip.semantic_tool_receipt.v1\",\"operationId\":\"receipt_fixture\",\"callIdentitySha256\":\"8880622e75a82af5d9b588823af9d706f2bf3a04dce96ee9aab2fa4a91c55508\",\"inputSha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\",\"resultSha256\":\"b325c663fc4bb7617a745373367ca8cbc7a3445f1b2fdb3a2a151da39f73553c\",\"outcome\":\"returned\"}",
"detailedContent": "{\"fixture\":\"known-small-result\",\"accepted\":false}{\"schema\":\"paperclip.semantic_tool_receipt.v1\",\"operationId\":\"receipt_fixture\",\"callIdentitySha256\":\"8880622e75a82af5d9b588823af9d706f2bf3a04dce96ee9aab2fa4a91c55508\",\"inputSha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\",\"resultSha256\":\"b325c663fc4bb7617a745373367ca8cbc7a3445f1b2fdb3a2a151da39f73553c\",\"outcome\":\"returned\"}",
"contents": [
{
"type": "text",
"text": "{\"fixture\":\"known-small-result\",\"accepted\":false}"
},
{
"type": "text",
"text": "{\"schema\":\"paperclip.semantic_tool_receipt.v1\",\"operationId\":\"receipt_fixture\",\"callIdentitySha256\":\"8880622e75a82af5d9b588823af9d706f2bf3a04dce96ee9aab2fa4a91c55508\",\"inputSha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\",\"resultSha256\":\"b325c663fc4bb7617a745373367ca8cbc7a3445f1b2fdb3a2a151da39f73553c\",\"outcome\":\"returned\"}"
}
]
}
}
}
},
"authoritativeReceipt": {
"schema": "paperclip.semantic_tool_receipt.v1",
"operationId": "receipt_fixture",
"callIdentitySha256": "8880622e75a82af5d9b588823af9d706f2bf3a04dce96ee9aab2fa4a91c55508",
"inputSha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
"resultSha256": "b325c663fc4bb7617a745373367ca8cbc7a3445f1b2fdb3a2a151da39f73553c",
"outcome": "returned"
}
}
@@ -0,0 +1,49 @@
{
"schema": "paperclip.native-mcp-capture-provenance.v1",
"nativeVersion": "1.0.88",
"nativeExecutableSha256": "a9ff8babb10b7e443182ae96a8bc50a9c826ef1c773e1344c396eb5bf7f512c3",
"platform": "darwin-arm64",
"sourceCommit": "cd2bd6f755a7685320766a71093320d7221172e9",
"captureKind": "real pinned native executable with deterministic loopback model and MCP server",
"paidProviderCalls": 0,
"credentialReads": false,
"qualification": false,
"scope": "One small successful two-text-block MCP result, original accepted=false; not native proof for every size/error encoding.",
"wireIndices": [
9,
11
],
"sanitization": [
"Replaced only params.sessionId in each selected frame with captured-fixture-session.",
"Excluded all other wire frames and model/configuration discovery.",
"Selected update objects and rawOutput preserved exactly.",
"authoritativeReceipt copied from owned fixture carrier.json; it is not an authority inferred from native output."
],
"originalEvidence": [
{
"name": "stdout.json",
"sha256": "95deeefff204b8e8db9c46b882cdea6fbe9b5c0de68efb56b4e9359cd0987208"
},
{
"name": "carrier.json",
"sha256": "c4f4fc333dfbc5efe33b46435a88c3c8ceff74237083e6eb03ad16bb8e783807"
},
{
"name": "carrier-proof.json",
"sha256": "4ed85f32732c2995506e4ffd23e85f79f26388aac6d8f47efefb5258c7b71da5"
},
{
"name": "execution-plan.json",
"sha256": "ae4435b5ed2c23a27e2d9c47efe599e3720b800a66e4f9ef56886428f21ee998"
},
{
"name": "probe.py",
"sha256": "264d39c1f6c36dadcd343b406a9f3ec851b29a55208c08cc3f6e26640ebeadd7"
},
{
"name": "HANDOFF.json",
"sha256": "e9859debd7274b42f5e58c28cc025bb2e3a090bb583e71ad460f2f482f6c3dae"
}
],
"fixtureSha256": "4af7345f219463813b382e4c6863003f9f957e147a96dc9c197b97ecd3e20cfb"
}
@@ -63,12 +63,13 @@ describe("qualified ACPX profiles", () => {
});
});
it("binds Cursor v9 to inspectable native instructions, closures and exact ACPX guard patch", () => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/cursor-acp/profile-v9-identity.json", import.meta.url), "utf8"));
it("binds Cursor v10 to native instructions, tool identity, closures and the exact ACPX guard patch", () => {
const identity = JSON.parse(readFileSync(new URL("../../../test/fixtures/cursor-acp/profile-v10-identity.json", import.meta.url), "utf8"));
const distribution = JSON.parse(readFileSync(new URL("../../../cursor-distributions.json", import.meta.url), "utf8"));
expect(identity.declaration.distribution).toEqual(distribution);
expect(identity.declaration.sharedRuntimeContract).toBe("paperclip.acpx-runtime-contract.v1");
expect(identity.declaration.nativePlanToolIdentity).toBe("request-item-id-bound-lifecycle-v1");
expect(identity.declaration.nativePermissionToolIdentity).toBe("opaque-native-tool-id-sha256-v1");
expect(identity.declaration.sessionModeAdmission).toBe("native-config-ack-recovery-bound-v1");
expect(identity.declaration.sessionModes).toEqual(["agent", "plan", "ask"]);
expect(identity.declaration.defaultSessionMode).toBe("agent");
@@ -77,4 +78,11 @@ it("binds Cursor v9 to inspectable native instructions, closures and exact ACPX
expect(identity.commandDigest).toBe(`sha256:${createHash("sha256").update(JSON.stringify(identity.declaration)).digest("hex")}`);
const patch = readFileSync(new URL("../../../../../patches/acpx@0.13.1.patch", import.meta.url));
expect(identity.declaration.acpxPatchSha256).toBe(createHash("sha256").update(patch).digest("hex"));
for (const [path, field] of [
["cursor-plan-tool-identity.ts", "toolIdentitySourceSha256"],
["acp-permission-adapter.ts", "permissionAdapterSourceSha256"],
["cursor-tool-evidence.ts", "toolEvidenceSourceSha256"],
]) {
expect(identity.declaration[field!]).toBe(createHash("sha256").update(readFileSync(new URL(path!, import.meta.url))).digest("hex"));
}
});
@@ -61,10 +61,10 @@ export const QUALIFIED_ACPX_PROFILES: Readonly<
},
cursor: {
driverKind: ACPX_DRIVER_KIND, protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION,
acpxVersion: QUALIFIED_ACPX_VERSION, agent: "cursor", agentProfileVersion: 9,
acpxVersion: QUALIFIED_ACPX_VERSION, agent: "cursor", agentProfileVersion: 10,
agentServerPackage: "cursor-agent", agentServerVersion: "2026.09.26-dd393fe",
agentRuntimePackage: null, agentRuntimeVersion: null,
commandDigest: "sha256:a76ad26878a3b3328154901563cbda857e53583e4e01787f35a797992ef76162",
commandDigest: "sha256:1df2a15b93bc3a14fa47fa3315344ba023fe2412048047cdc6f32096a6336564",
// Authenticated discovery has not established a qualification model. Never
// turn this empty declaration into a default; callers must select an ID.
qualificationModel: "", reportedModelId: "", permissionPolicy: "interactive",
@@ -72,10 +72,10 @@ export const QUALIFIED_ACPX_PROFILES: Readonly<
},
copilot: {
driverKind: ACPX_DRIVER_KIND, protocolVersion: ACPX_DRIVER_PROTOCOL_VERSION,
acpxVersion: QUALIFIED_ACPX_VERSION, agent: "copilot", agentProfileVersion: 9,
acpxVersion: QUALIFIED_ACPX_VERSION, agent: "copilot", agentProfileVersion: 10,
agentServerPackage: "@github/copilot", agentServerVersion: "1.0.88",
agentRuntimePackage: null, agentRuntimeVersion: null,
commandDigest: "sha256:98936d763497bd6f0e5605f52831a344f456357de58c457e440e69a1a468a2f4",
commandDigest: "sha256:c6741d7e49cd1af4ecad9e07181ef96305bde48b56dce2958547f2f066666231",
// Authenticated discovery has not established a qualification model. Never
// turn this empty declaration into a default; callers must select an ID.
qualificationModel: "", reportedModelId: "", permissionPolicy: "interactive",
@@ -29,7 +29,10 @@ describe("ACPX recovery identity", () => {
it.each([
["cursor", "../../../test/fixtures/cursor-acp/profile-v7-identity.json"],
["cursor", "../../../test/fixtures/cursor-acp/profile-v8-identity.json"],
["cursor", "../../../test/fixtures/cursor-acp/profile-v9-identity.json"],
["copilot", "../../../test/fixtures/copilot-profile-v7-identity.json"],
["copilot", "../../../test/fixtures/copilot-profile-v8-identity.json"],
["copilot", "../../../test/fixtures/copilot-profile-v9-identity.json"],
["pi", "../../../test-fixtures/pi-acp/profile-v9-identity.json"],
] as const)("rejects retained %s sessions after the execution identity changes", async (agent, path) => {
const fixture = await recoveryFixture();
@@ -1,3 +1,7 @@
import { createCopilotToolEvidence } from "./copilot-tool-evidence.js";
import { readNativeSemanticReceipt, type SemanticToolResult } from "../semantic-tool-receipt.js";
import { validateAcpxRichEvent } from "./profile-extensions.js";
import type { CanonicalProviderEvent } from "../../provider-events.js";
import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -736,6 +740,30 @@ describe("ACPX runtime host", () => {
expect(fixture.commandClose).toHaveBeenCalledOnce();
});
it("forwards semantic receipt capture through the real runtime host and authenticated bridge", async () => {
const fixture = await hostFixture();
const events: CanonicalProviderEvent[] = [];
const evidence = createCopilotToolEvidence({ sessionId: "backend-1", turnId: "turn-1", workingDirectory: fixture.options.workingDirectory,
active: () => true, emit: event => { validateAcpxRichEvent(event); events.push(JSON.parse(JSON.stringify(event))); } });
let bridge: AcpxRuntimePortOpenOptions["mcpServers"][number] | undefined;
const host = await AcpxRuntimeHost.open({ ...fixture.options, agent: "copilot", model: "gpt-5.6-sol",
permissionMode: "deny-all", environment: { COPILOT_GITHUB_TOKEN: "fixture-not-a-real-credential" },
semanticTools: { tools: [{ name: "get_task_context", inputSchema: { type: "object", properties: {}, additionalProperties: false } }],
handler: async () => ({ accepted: false }), captureSemanticReceipt: () => evidence.captureSemanticReceipt() },
}, fixture.dependencies({ openRuntime: async options => { bridge = options.mcpServers[0]; return runtimePort(); } }));
try {
const response = await fetch(bridge!.url, { method: "POST", headers: { Authorization: `Bearer ${bridge!.bearerToken}`, "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "get_task_context", arguments: {} } }) });
const body = await response.json() as { result: SemanticToolResult };
const receipt = readNativeSemanticReceipt({ contents: body.result.content });
expect(receipt).not.toBeNull();
expect(events).toHaveLength(1);
expect(events[0]!.payload).toMatchObject({ category: "paperclip_semantic_tool_receipt_v1", provenance: { sessionId: "backend-1", turnId: "turn-1" },
details: expect.arrayContaining([{ name: "callIdentitySha256", value: receipt!.callIdentitySha256 }, { name: "resultSha256", value: receipt!.resultSha256 }]) });
} finally { await host.close({ reason: "receipt forwarding verified" }); }
await expect(fetch(bridge!.url)).rejects.toThrow();
});
it("owns an authenticated semantic bridge without persisting its secret", async () => {
const fixture = await hostFixture();
const handler = vi.fn(async ({ tool }) => ({ tool, ok: true }));
@@ -1,3 +1,4 @@
import { readNativeSemanticReceipt, type SemanticToolReceipt, type SemanticToolResult } from "./semantic-tool-receipt.js";
import { connect } from "node:net";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -465,3 +466,44 @@ describe("runner semantic MCP bridge", () => {
function tool(name: string): Readonly<Record<string, unknown>> {
return { name, inputSchema: { type: "object" } };
}
describe("Copilot semantic receipt opt-in", () => {
it.each(["small", "chunked", "tagged", "error"])("preserves %s result encoding and captures scope before dispatch", async encoding => {
const receipts: SemanticToolReceipt[] = [];
let resolve!: (value: unknown) => void;
let reject!: (error: Error) => void;
const pending = new Promise((yes, no) => { resolve = yes; reject = no; });
const capture = vi.fn(() => (receipt: SemanticToolReceipt) => receipts.push(receipt));
const handler = vi.fn(() => pending);
const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], handler, captureSemanticReceipt: capture });
bridges.push(bridge);
const request = { id: 3, method: "tools/call", params: { name: "documents.read", arguments: {} } };
const response = rpc(bridge, request);
await vi.waitFor(() => expect(handler).toHaveBeenCalledTimes(1));
expect(capture).toHaveBeenCalledTimes(1);
if (encoding === "error") reject(new Error("bounded failure"));
else resolve(encoding === "chunked" ? "x".repeat(70000) : encoding === "tagged" ? { bigint: 1n } : { accepted: false });
const body = await (await response).json() as { result: SemanticToolResult };
expect(receipts).toHaveLength(1);
expect(readNativeSemanticReceipt({ contents: body.result.content })).toEqual(receipts[0]);
expect(body.result.isError === true).toBe(encoding === "error");
if (encoding === "small") expect(JSON.parse(body.result.content[0].text)).toEqual({ accepted: false });
if (encoding === "error") expect(body.result.content[0].text).toBe("bounded failure");
if (encoding === "chunked") expect(body.result.content.length).toBeGreaterThan(2);
const replay = await (await rpc(bridge, request)).json();
expect(replay).toEqual(body);
expect(receipts).toHaveLength(1);
expect(handler).toHaveBeenCalledTimes(1);
});
it("does not receipt unauthorized/unadmitted calls or let diagnostic errors change results", async () => {
const capture = vi.fn(() => () => { throw new Error("diagnostic only"); });
const bridge = await startRunnerToolBridge({ tools: [tool("documents.read")], handler: async () => ({ ok: true }), captureSemanticReceipt: capture });
bridges.push(bridge);
await rpc(bridge, { id: 1, method: "tools/call", params: { name: "documents.read" } }, "wrong");
await rpc(bridge, { id: 2, method: "tools/call", params: { name: "unknown" } });
expect(capture).not.toHaveBeenCalled();
const body = await (await rpc(bridge, { id: 3, method: "tools/call", params: { name: "documents.read" } })).json() as { result: SemanticToolResult };
expect(JSON.parse(body.result.content[0].text)).toEqual({ ok: true });
expect(readNativeSemanticReceipt({ contents: body.result.content })).not.toBeNull();
});
});
@@ -1,4 +1,5 @@
import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
import { appendSemanticToolReceipt, semanticCanonicalJson as canonicalJson, type SemanticToolReceipt } from "./semantic-tool-receipt.js";
import {
createServer,
type IncomingMessage,
@@ -33,6 +34,8 @@ export interface RunnerToolBridgeOptions {
/** Runner-owned operations that are callable but never model-visible. */
privateTools?: readonly Readonly<Record<string, unknown>>[];
handler(call: RunnerToolCall): Promise<unknown>;
/** Copilot-only opt-in; capture the active invocation scope before dispatch. */
captureSemanticReceipt?: () => ((receipt: SemanticToolReceipt) => void) | undefined;
timeoutMs?: number;
privateToolTimeoutMs?: number;
maxBodyBytes?: number;
@@ -58,6 +61,7 @@ interface RunnerToolTextContent {
}
interface RunnerToolCallResult {
isError?: boolean;
content: RunnerToolTextContent[];
}
@@ -121,6 +125,7 @@ export async function startRunnerToolBridge(
calls,
controllers,
handler: options.handler,
captureSemanticReceipt: options.captureSemanticReceipt,
timeoutMs: positiveBoundedInteger(
options.timeoutMs,
DEFAULT_TIMEOUT_MS,
@@ -190,6 +195,7 @@ async function handleRequest(
calls: Map<string, AdmittedCall>;
controllers: Map<string, AbortController>;
handler: RunnerToolBridgeOptions["handler"];
captureSemanticReceipt: RunnerToolBridgeOptions["captureSemanticReceipt"];
timeoutMs: number;
privateToolTimeoutMs: number;
privateToolNames: ReadonlySet<string>;
@@ -319,6 +325,16 @@ async function handleRequest(
}
}
const controller = existing === undefined ? new AbortController() : undefined;
let observeReceipt: ((receipt: SemanticToolReceipt) => void) | undefined;
if (!existing) { try { observeReceipt = context.captureSemanticReceipt?.(); } catch { /* Optional evidence cannot prevent dispatch. */ } }
const withReceipt = (result: RunnerToolCallResult): RunnerToolCallResult => {
if (!context.captureSemanticReceipt) return result;
try {
const bound = appendSemanticToolReceipt({ tool, callId, arguments: args }, result);
try { observeReceipt?.(bound.receipt); } catch { /* Evidence cannot change the tool outcome. */ }
return bound.result;
} catch { return result; }
};
const execution: Promise<RunnerToolCallResult> =
existing?.promise ??
withCancellationAndTimeout(
@@ -336,7 +352,10 @@ async function handleRequest(
context.privateToolNames.has(tool)
? context.privateToolTimeoutMs
: context.timeoutMs,
);
).then(withReceipt, error => {
if (!context.captureSemanticReceipt) throw error;
return withReceipt({ isError: true, content: [{ type: "text", text: safeError(error) }] });
});
if (!existing) {
context.calls.set(callKey, { fingerprint, promise: execution });
context.controllers.set(callKey, controller!);
@@ -811,16 +830,6 @@ function taggedObjectType(value: object): string {
: "Object";
}
function canonicalJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
if (isRecord(value)) {
return `{${Object.keys(value)
.sort()
.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
.join(",")}}`;
}
return JSON.stringify(value) ?? "undefined";
}
function isJsonContentType(value: string | undefined): boolean {
return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
@@ -0,0 +1,46 @@
import { describe, expect, it } from "vitest";
import { appendSemanticToolReceipt, parseSemanticToolReceipt, readNativeSemanticReceipt, semanticInputSha256 } from "./semantic-tool-receipt.js";
const call = { tool: "paperclip_finish", callId: "3", arguments: { revision: "current", summary: "private" } };
const original = { content: [{ type: "text" as const, text: '{"accepted":false}' }] };
describe("bounded semantic receipt carrier", () => {
it("preserves existing content and transport-vs-semantic acceptance", () => {
const { result, receipt } = appendSemanticToolReceipt(call, original);
expect(result.content.slice(0, -1)).toEqual(original.content);
expect(receipt.outcome).toBe("returned");
expect(JSON.stringify(receipt)).not.toContain("private");
expect(readNativeSemanticReceipt({ contents: result.content })).toEqual(receipt);
expect(semanticInputSha256({ a: 1, b: 2 })).toBe(semanticInputSha256({ b: 2, a: 1 }));
});
it("preserves error content without converting error into returned acceptance", () => {
const { result, receipt } = appendSemanticToolReceipt(call, { ...original, isError: true });
expect(result.isError).toBe(true);
expect(receipt.outcome).toBe("error");
expect(readNativeSemanticReceipt({ contents: result.content })).toEqual(receipt);
});
it.each(["unknown", "malformed", "oversized", "modified", "duplicate", "missing", "type", "reordered"])("rejects %s native carrier", kind => {
const { result } = appendSemanticToolReceipt(call, original);
const blocks = structuredClone(result.content);
const receipt = JSON.parse(blocks.at(-1)!.text);
if (kind === "unknown") blocks.at(-1)!.text = JSON.stringify({ ...receipt, extra: "private" });
if (kind === "malformed") blocks.at(-1)!.text = "{";
if (kind === "oversized") blocks.at(-1)!.text = "x".repeat(2049);
if (kind === "modified") blocks[0]!.text = "different";
if (kind === "duplicate") blocks.unshift(blocks.at(-1)!);
if (kind === "missing") blocks.pop();
if (kind === "type") Object.assign(blocks[0]!, { type: "image" });
if (kind === "reordered") blocks.reverse();
expect(readNativeSemanticReceipt({ contents: blocks })).toBeNull();
});
it("bounds the whole repeated native output while still serializing large-result receipts", () => {
const bound = appendSemanticToolReceipt(call, { content: [{ type: "text", text: "x".repeat(90_000) }] });
expect(readNativeSemanticReceipt({ contents: bound.result.content })).toEqual(bound.receipt);
expect(readNativeSemanticReceipt({ contents: bound.result.content, content: "x".repeat(90_000), detailedContent: "x".repeat(90_000) })).toBeNull();
expect(bound.result.content.at(-1)!.text.length).toBeLessThan(2048);
});
it("rejects unknown fields and unsafe identities without truncation", () => {
const { receipt } = appendSemanticToolReceipt(call, original);
expect(parseSemanticToolReceipt({ ...receipt, operationId: "bad\nname" })).toBeNull();
expect(parseSemanticToolReceipt({ ...receipt, inputSha256: "a".repeat(65) })).toBeNull();
expect(parseSemanticToolReceipt({ ...receipt, outcome: "accepted" })).toBeNull();
});
});
@@ -0,0 +1,71 @@
import { createHash } from "node:crypto";
export const SEMANTIC_RECEIPT_SCHEMA = "paperclip.semantic_tool_receipt.v1";
export const MAX_SEMANTIC_RECEIPT_BYTES = 2048;
const MAX_NATIVE_BYTES = 256 * 1024;
export interface SemanticToolReceipt {
schema: typeof SEMANTIC_RECEIPT_SCHEMA;
operationId: string;
callIdentitySha256: string;
inputSha256: string;
resultSha256: string;
/** Transport outcome only: a returned value may explicitly reject a request. */
outcome: "returned" | "error";
}
export interface SemanticToolResult {
content: Array<{ type: "text"; text: string }>;
isError?: boolean;
}
const hash = (value: string) => createHash("sha256").update(value).digest("hex");
const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
/** Same canonical JSON used by the bridge's admitted-call fingerprint. */
export function semanticCanonicalJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(semanticCanonicalJson).join(",")}]`;
if (object(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${semanticCanonicalJson(value[key])}`).join(",")}}`;
return JSON.stringify(value) ?? "undefined";
}
export const semanticInputSha256 = (value: unknown): string => hash(semanticCanonicalJson(value));
export function parseSemanticToolReceipt(value: unknown): SemanticToolReceipt | null {
if (!object(value) || Object.keys(value).sort().join(",") !== "callIdentitySha256,inputSha256,operationId,outcome,resultSha256,schema"
|| value.schema !== SEMANTIC_RECEIPT_SCHEMA
|| typeof value.operationId !== "string" || !/^[A-Za-z0-9_.:-]{1,256}$/.test(value.operationId)
|| ![value.callIdentitySha256, value.inputSha256, value.resultSha256].every(v => typeof v === "string" && /^[a-f0-9]{64}$/.test(v))
|| (value.outcome !== "returned" && value.outcome !== "error")
|| Buffer.byteLength(JSON.stringify(value)) > MAX_SEMANTIC_RECEIPT_BYTES) return null;
return { schema: SEMANTIC_RECEIPT_SCHEMA, operationId: value.operationId,
callIdentitySha256: value.callIdentitySha256 as string, inputSha256: value.inputSha256 as string,
resultSha256: value.resultSha256 as string, outcome: value.outcome };
}
function resultDigest(result: SemanticToolResult): string {
return semanticInputSha256({ content: result.content, isError: result.isError === true });
}
/** Append, never rewrite, the original admitted result encoding and content. */
export function appendSemanticToolReceipt(call: { tool: string; callId: string; arguments: unknown }, result: SemanticToolResult) {
const receipt = parseSemanticToolReceipt({ schema: SEMANTIC_RECEIPT_SCHEMA, operationId: call.tool,
callIdentitySha256: hash(call.callId), inputSha256: semanticInputSha256(call.arguments),
resultSha256: resultDigest(result), outcome: result.isError ? "error" : "returned" });
if (!receipt) throw new Error("Invalid semantic receipt identity");
return { receipt, result: { ...result, content: [...result.content, { type: "text" as const, text: JSON.stringify(receipt) }] } };
}
/**
* A native echo is only a candidate. Authority comes from the invocation callback.
* The 256 KiB bound applies to the WHOLE native rawOutput, including repeated
* content/detailedContent. Larger results still receive bridge receipts, but
* intentionally provide no native correlation evidence; never truncate to match.
*/
export function readNativeSemanticReceipt(raw: unknown): SemanticToolReceipt | null {
try {
if (!object(raw) || Buffer.byteLength(JSON.stringify(raw)) > MAX_NATIVE_BYTES || !Array.isArray(raw.contents)
|| raw.contents.length < 2 || raw.contents.length > 128) return null;
const blocks = raw.contents;
if (!blocks.every(b => object(b) && Object.keys(b).sort().join(",") === "text,type" && b.type === "text" && typeof b.text === "string")) return null;
const last = blocks.at(-1) as { text: string };
if (Buffer.byteLength(last.text) > MAX_SEMANTIC_RECEIPT_BYTES) return null;
const receipt = parseSemanticToolReceipt(JSON.parse(last.text));
if (!receipt) return null;
const original = blocks.slice(0, -1) as SemanticToolResult["content"];
if (original.some(b => { try { return parseSemanticToolReceipt(JSON.parse(b.text)) !== null; } catch { return false; } })) return null;
return resultDigest({ content: original, isError: receipt.outcome === "error" }) === receipt.resultSha256 ? receipt : null;
} catch { return null; }
}
export const sameSemanticReceipt = (a: SemanticToolReceipt, b: SemanticToolReceipt): boolean => semanticCanonicalJson(a) === semanticCanonicalJson(b);
@@ -0,0 +1,117 @@
import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, vi } from "vitest";
import type { DurableRecoveryCommittedEvent, DurableRecoveryIdentity } from "../contracts/durable-recovery.js";
import type { CodexSessionState } from "../drivers/codex/codex-session-state.js";
import type { HarnessRuntimeRequest } from "../contracts/harness-driver.js";
// Replace only the PRP peer and process boundary. The production transport,
// event pump, registered handler, and request emission below all run unchanged.
const peer = vi.hoisted(() => ({ current: null as TestPeer | null }));
interface TestPeer {
store: { state: { identity: DurableRecoveryIdentity; committedEvents: DurableRecoveryCommittedEvent[]; commands: Array<Record<string, unknown>> } };
emit(type: string, payload: Record<string, unknown>): void;
}
vi.mock("../control-plane/durable-prp-control-plane.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("../control-plane/durable-prp-control-plane.js")>();
return {
...actual,
spawnRunner: vi.fn(() => ({ child: { exitCode: null }, completion: new Promise(() => {}) })),
DurablePrpControlPlane: class implements TestPeer {
store: TestPeer["store"];
connectUrl = "ws://fixture.invalid";
constructor(options: { identity: DurableRecoveryIdentity }) {
this.store = { state: { identity: options.identity, committedEvents: [], commands: [] } };
peer.current = this;
}
async start() {}
async stop() {}
disconnectActiveRunner() {}
persistRunAttachTemplate() {}
issueBootstrapTicket() { return {}; }
getCommand(id: string) { return this.store.state.commands.find(c => c.commandId === id); }
queueCommand(type: string, payload: Record<string, unknown>, id = type) {
this.store.state.commands.push({ type, commandId: id, status: "completed", result: { result: { providerTurnId: payload.turnId } } });
if (type === "session.open") this.emit("session.started", {
threadId: "thread-1", sessionId: "provider-session-1",
runtimeIdentity: { executionKind: "remote_service" },
});
if (type === "turn.start") this.emit("turn.started", { providerTurnId: payload.turnId });
}
emit(eventType: string, payload: Record<string, unknown>) {
const sourceSeq = this.store.state.committedEvents.length + 1;
this.store.state.committedEvents.push({
eventType, sourceSeq, sourceEventId: `fixture:${sourceSeq}`,
priority: 0, deliveryCount: 1, logicalEffectCount: 1,
envelope: { turnId: this.store.state.identity.turnId, payload: { payload } },
});
}
},
};
});
import { createCapabilityRunnerdCodexTransport } from "./runnerd-codex-transport.js";
import { handleServerRequest } from "../drivers/codex/codex-session-server-requests.js";
describe("permission events through the actual transport handler", () => {
it.each([
{ name: "native ID distinct from opaque item", details: { toolCallId: "native-edit-7" }, expected: "native-edit-7" },
{ name: "absent native ID", details: {}, expected: undefined },
{ name: "malformed native ID", details: { toolCallId: { forged: "opaque-item-7" } }, expected: undefined },
])("emits retained control-plane details for $name", async ({ details, expected }) => {
const root = mkdtempSync(join(tmpdir(), "permission-forwarding-"));
const binary = join(root, "unexecuted-runner");
writeFileSync(binary, "not executable: process boundary is mocked");
const bundle = createCapabilityRunnerdCodexTransport({
runnerBinary: binary, stateDirectory: root,
sourceCodexHome: join(root, "absent-source-home"),
environment: { HOME: root, PATH: "/usr/bin:/bin" },
});
const emitted: HarnessRuntimeRequest[] = [];
const pending = new Map();
const state = {
sourceSequence: 0, runnerInstanceId: "fixture-runner", runId: "fixture-run",
opened: { threadId: "thread-1" }, activeTurnId: "", terminal: false, protocolFailed: false,
pendingRuntimeRequestMap: pending, transport: bundle.transport,
failProtocol: vi.fn((code: string) => { throw new Error(code); }),
emit(type: string, payload: { request?: HarnessRuntimeRequest }) {
this.sourceSequence++;
if (type === "runtime_request.created") {
emitted.push(structuredClone(payload.request!));
writeFileSync(join(root, "emitted-requests.json"), JSON.stringify(emitted));
}
},
};
const handled = vi.fn(request => handleServerRequest(state as unknown as CodexSessionState, request));
bundle.transport.setServerRequestHandler(handled);
let drain: Promise<void> | undefined;
try {
await bundle.transport.request("initialize", {});
await bundle.transport.request("thread/start", { cwd: root });
const start = await bundle.transport.request("turn/start", { input: [{ type: "text", text: "Fixture" }] });
state.activeTurnId = (start.turn as { id: string }).id;
// The real harness consumes notifications before dispatching a bridged
// request at its position in the durable event stream.
drain = (async () => { for await (const _notification of bundle.transport.notifications()) { /* Consume the fixture's turn start. */ } })();
peer.current!.emit("runtime_request.created", { request: {
requestId: "permission-7", type: "permission", requestKind: "permission_approval",
itemId: "opaque-item-7", prompt: "Change file: result.txt", details,
choices: [{ key: "decline", label: "Deny" }],
origin: { adapter: "acpx-runtime-sidecar", provider: "copilot", method: "session/request_permission" },
} });
await vi.waitFor(() => expect(emitted).toHaveLength(1), { timeout: 1_000, interval: 5 });
expect(handled).toHaveBeenCalledTimes(1);
const retained = JSON.parse(readFileSync(join(root, "emitted-requests.json"), "utf8"))[0];
expect(retained).toMatchObject({ requestId: "permission-7", itemId: "opaque-item-7", requestKind: "permission_approval", turnId: state.activeTurnId });
if (expected === undefined) expect(retained.details).not.toHaveProperty("toolCallId");
else expect(retained.details.toolCallId).toBe(expected);
expect(retained.details.choices).toEqual([{ key: "decline", label: "Deny" }]);
expect(state.failProtocol).not.toHaveBeenCalled();
} finally {
for (const entry of pending.values()) entry.settle({ outcome: "cancel" });
await bundle.detachControllerForRestart();
await drain;
rmSync(root, { recursive: true, force: true });
}
});
});
@@ -0,0 +1,221 @@
import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, vi } from "vitest";
import type { DurableRecoveryCommittedEvent, DurableRecoveryIdentity } from "../contracts/durable-recovery.js";
// Replace only the PRP peer and process boundary. The production transport,
// event pump, registered handler, and request emission below all run unchanged.
const peer = vi.hoisted(() => ({ current: null as TestPeer | null }));
interface TestPeer {
store: { state: { identity: DurableRecoveryIdentity; committedEvents: DurableRecoveryCommittedEvent[]; commands: Array<Record<string, unknown>> } };
emit(type: string, payload: Record<string, unknown>): void;
}
vi.mock("../control-plane/durable-prp-control-plane.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("../control-plane/durable-prp-control-plane.js")>();
return {
...actual,
spawnRunner: vi.fn(() => ({ child: { exitCode: null }, completion: new Promise(() => {}) })),
DurablePrpControlPlane: class implements TestPeer {
store: TestPeer["store"];
connectUrl = "ws://fixture.invalid";
constructor(options: { identity: DurableRecoveryIdentity }) {
this.store = { state: { identity: options.identity, committedEvents: [], commands: [] } };
peer.current = this;
}
async start() {}
async stop() {}
disconnectActiveRunner() {}
persistRunAttachTemplate() {}
issueBootstrapTicket() { return {}; }
getCommand(id: string) { return this.store.state.commands.find(c => c.commandId === id); }
queueCommand(type: string, payload: Record<string, unknown>, id = type) {
this.store.state.commands.push({ type, commandId: id, status: "completed", result: { result: { providerTurnId: payload.turnId } } });
if (type === "session.open") this.emit("session.started", {
threadId: "thread-1", sessionId: "provider-session-1",
runtimeIdentity: { executionKind: "remote_service" },
});
if (type === "turn.start") this.emit("turn.started", { providerTurnId: payload.turnId });
}
emit(eventType: string, payload: Record<string, unknown>) {
const sourceSeq = this.store.state.committedEvents.length + 1;
this.store.state.committedEvents.push({
eventType, sourceSeq, sourceEventId: `fixture:${sourceSeq}`,
priority: 0, deliveryCount: 1, logicalEffectCount: 1,
envelope: { turnId: this.store.state.identity.turnId, payload: { payload } },
});
}
},
};
});
import { cursorToolIdentity, cursorToolExecutionId } from "../drivers/acpx/cursor-plan-tool-identity.js";
import { normalizeAcpxPermission } from "../drivers/acpx/acp-permission-adapter.js";
import { createCapabilityRunnerdCodexTransport } from "./runnerd-codex-transport.js";
import { makeDriver, WORKSPACE } from "../drivers/codex/codex-app-server-driver.test-support.js";
import type { PrpEvent } from "../protocol/replay-contract.js";
describe("permission and tool order through the actual transport and harness", () => {
it.each(["tool-first", "permission-first"].flatMap(order => ["native-tool-7", "native\u0080tool", "native\u0085tool", "native\u009ftool", "tool/1", "x".repeat(161)].map(rawId => ({ order, rawId }))))("preserves committed batch order and native identity with an unanswered permission: $order $rawId", async ({ order, rawId }) => {
const toolCallId = cursorToolIdentity(rawId);
const executionId = cursorToolExecutionId(rawId);
const normalized = normalizeAcpxPermission({ sessionId: "provider-session-1", inferredKind: "execute", raw: {
sessionId: "provider-session-1", toolCall: { toolCallId: rawId, kind: "execute" },
options: [{ kind: "reject_once", optionId: "original-native-denial", name: "Deny" }],
} }, { provider: "cursor" });
expect(normalized.toolCallId).toBe(toolCallId);
const root = mkdtempSync(join(tmpdir(), "permission-ordering-"));
const binary = join(root, "unexecuted-runner");
writeFileSync(binary, "not executable: process boundary is mocked");
const bundle = createCapabilityRunnerdCodexTransport({
runnerBinary: binary, stateDirectory: root,
sourceCodexHome: join(root, "absent-source-home"),
environment: { HOME: root, PATH: "/usr/bin:/bin" },
});
const driver = makeDriver([], { transportFactory: () => bundle.transport });
const seen: PrpEvent[] = [];
let session: Awaited<ReturnType<typeof driver.openSession>> | undefined;
let drain: Promise<void> | undefined;
try {
session = await driver.openSession({ runId: "ordering-run", normalizedSessionId: "ordering-session", workingDirectory: WORKSPACE });
const { turnId } = await session.startTurn({ message: { role: "user", text: "Fixture" } });
drain = (async () => { for await (const event of session!.events()) {
seen.push(event);
if (seen.some(e => e.eventType === "runtime_request.created") && seen.some(e => e.eventType === "tool.execution.started")) break;
} })();
const tool = () => peer.current!.emit("tool.execution.started", {
schema: "paperclip.tool.execution.v1", executionId, transport: "builtin", namespace: null,
name: "Run command", operation: "execute", target: null, status: "running", readOnly: false,
inputUpdated: true, output: null, outputBytes: 0, outputTruncated: false, outputDigest: null,
durationMs: null, exitCode: null, progress: [],
});
const permission = () => peer.current!.emit("runtime_request.created", { request: {
requestId: "permission-7", type: "permission", requestKind: "permission_approval",
itemId: "opaque-item-7", prompt: "Run command", details: { toolCallId: normalized.toolCallId },
choices: [{ key: "decline", label: "Deny" }, { key: "cancel", label: "Cancel" }],
origin: { adapter: "acpx-runtime-sidecar", provider: "cursor", method: "session/request_permission" },
} });
// Both durable events exist before the production pump's next tick.
// Keep the permission unanswered while the independent tool pump drains.
if (order === "tool-first") { tool(); permission(); } else { permission(); tool(); }
await vi.waitFor(() => expect(seen.filter(e => ["tool.execution.started", "runtime_request.created"].includes(e.eventType))).toHaveLength(2), { timeout: 1_000, interval: 5 });
const nativeOrder = peer.current!.store.state.committedEvents.filter(e => ["tool.execution.started", "runtime_request.created"].includes(e.eventType)).map(e => e.eventType);
const projectedOrder = seen.filter(e => ["tool.execution.started", "runtime_request.created"].includes(e.eventType)).map(e => e.eventType);
expect(session.pendingRuntimeRequests!()).toMatchObject([{ requestId: "permission-7", turnId, status: "pending", details: { toolCallId } }]);
expect(projectedOrder).toEqual(nativeOrder);
// Permission details retain bounded native identity; activity retains
// Rust's opaque execution ID. Their deterministic join is intentional.
expect(seen.find(e => e.eventType === "tool.execution.started")?.payload).toMatchObject({ executionId });
if (rawId === "tool/1" || rawId.length === 161) expect(executionId).not.toBe(toolCallId);
} finally {
// This test owns no actual process or database. Retire the mocked peer
// and its controller timer without inventing a provider terminal event.
await bundle.detachControllerForRestart();
await drain;
rmSync(root, { recursive: true, force: true });
}
});
});
async function bareTransport() {
const root = mkdtempSync(join(tmpdir(), "permission-queue-lifecycle-"));
const binary = join(root, "unexecuted-runner");
writeFileSync(binary, "not executable: process boundary is mocked");
const bundle = createCapabilityRunnerdCodexTransport({ runnerBinary: binary, stateDirectory: root,
sourceCodexHome: join(root, "absent-source-home"), environment: { HOME: root, PATH: "/usr/bin:/bin" },
});
await bundle.transport.request("initialize", {});
await bundle.transport.request("thread/start", { cwd: root });
await bundle.transport.request("turn/start", { input: [{ type: "text", text: "Fixture" }] });
const iterator = bundle.transport.notifications()[Symbol.asyncIterator]();
expect((await iterator.next()).value?.method).toBe("turn/started");
const emitPermission = (requestId = "permission-7", prompt = "Run command") => peer.current!.emit("runtime_request.created", { request: {
requestId, type: "permission", requestKind: "permission_approval", itemId: requestId, prompt,
choices: [{ key: "cancel", label: "Cancel" }], details: { toolCallId: "tool-7" },
origin: { adapter: "acpx-runtime-sidecar", provider: "cursor", method: "session/request_permission" },
} });
const emitMarker = () => peer.current!.emit("item.delta", { kind: "agentMessage", text: "marker" });
return { bundle, iterator, emitPermission, emitMarker, async close() { await bundle.detachControllerForRestart(); rmSync(root, { recursive: true, force: true }); } };
}
it("discards a queued permission on close before the notification consumer asks for next", async () => {
const fixture = await bareTransport(); const handler = vi.fn(async () => ({}));
fixture.bundle.transport.setServerRequestHandler(handler);
try {
fixture.emitMarker(); fixture.emitPermission();
expect((await fixture.iterator.next()).value?.method).toBe("item/agentMessage/delta");
expect(handler).not.toHaveBeenCalled();
await fixture.bundle.detachControllerForRestart();
await expect(fixture.iterator.next()).resolves.toMatchObject({ done: true });
expect(handler).not.toHaveBeenCalled();
} finally { await fixture.close(); }
});
it("does not dispatch an expired durable request when its consumer resumes", async () => {
const fixture = await bareTransport(); const handler = vi.fn(async () => ({}));
fixture.bundle.transport.setServerRequestHandler(handler);
try {
fixture.emitPermission();
peer.current!.emit("runtime_request.expired", { requestId: "permission-7" });
fixture.emitMarker();
expect((await fixture.iterator.next()).value?.method).toBe("item/agentMessage/delta");
expect(handler).not.toHaveBeenCalled();
} finally { await fixture.close(); }
});
it("does not dispatch queued approval callbacks into a replacement turn", async () => {
const fixture = await bareTransport(); const handler = vi.fn(async () => ({}));
fixture.bundle.transport.setServerRequestHandler(handler);
try {
fixture.emitMarker(); fixture.emitPermission();
expect((await fixture.iterator.next()).value?.method).toBe("item/agentMessage/delta");
await fixture.bundle.transport.request("turn/start", { input: [{ type: "text", text: "Next turn" }] });
expect((await fixture.iterator.next()).value?.method).toBe("turn/started");
expect(handler).not.toHaveBeenCalled();
} finally { await fixture.close(); }
});
it.each(["throw", "reject"])("closes the queue and wakes its consumer on handler %s", async failure => {
const fixture = await bareTransport();
const handler = vi.fn(() => { if (failure === "throw") throw new Error("fixture handler failed"); return Promise.reject(new Error("fixture handler failed")); });
fixture.bundle.transport.setServerRequestHandler(handler);
try {
fixture.emitPermission();
await expect(fixture.iterator.next()).rejects.toThrow("fixture handler failed");
expect(handler).toHaveBeenCalledTimes(1);
await expect(fixture.iterator.next()).rejects.toThrow("fixture handler failed");
} finally { await fixture.close(); }
});
it.each(["count", "bytes"])("bounds queued permission callback %s without a consumer", async bound => {
const fixture = await bareTransport(); const handler = vi.fn(async () => ({}));
fixture.bundle.transport.setServerRequestHandler(handler);
try {
if (bound === "count") for (let i = 0; i < 2049; i++) fixture.emitPermission(`permission-${i}`);
else fixture.emitPermission("oversized", "x".repeat(4 * 1024 * 1024));
// next waits until the actual event pump reaches the closed queue limit.
await expect(fixture.iterator.next()).rejects.toThrow("notification queue bound exceeded");
expect(handler).not.toHaveBeenCalled();
} finally { await fixture.close(); }
});
it("wakes an idle notification consumer during controller shutdown", async () => {
const fixture = await bareTransport();
try {
const pending = fixture.iterator.next();
await fixture.bundle.detachControllerForRestart();
await expect(pending).resolves.toMatchObject({ done: true });
} finally { await fixture.close(); }
});
it("does not transfer a queued request to a newly registered handler", async () => {
const fixture = await bareTransport(); const original = vi.fn(async () => ({})), replacement = vi.fn(async () => ({}));
fixture.bundle.transport.setServerRequestHandler(original);
try {
fixture.emitMarker(); fixture.emitPermission(); fixture.emitMarker();
expect((await fixture.iterator.next()).value?.method).toBe("item/agentMessage/delta");
fixture.bundle.transport.setServerRequestHandler(replacement);
expect((await fixture.iterator.next()).value?.method).toBe("item/agentMessage/delta");
expect(original).not.toHaveBeenCalled(); expect(replacement).not.toHaveBeenCalled();
} finally { await fixture.close(); }
});
@@ -1488,32 +1488,37 @@ export function resolveRunnerdSessionIdentity(input: unknown): {
};
}
type NotificationQueueEntry =
| { kind: "notification"; value: CodexRpcNotification; bytes: number }
| { kind: "control"; dispatch(): void; bytes: number };
class NotificationQueue implements AsyncIterable<CodexRpcNotification> {
#values: Array<{ value: CodexRpcNotification; bytes: number }> = [];
#waiters: Array<{
resolve: (value: IteratorResult<CodexRpcNotification>) => void;
reject: (error: Error) => void;
}> = [];
#values: NotificationQueueEntry[] = [];
#waiters: Array<() => void> = [];
#bytes = 0;
#closed = false;
#error: Error | null = null;
push(value: CodexRpcNotification): void {
if (this.#closed) return;
const bytes = Buffer.byteLength(JSON.stringify(value));
const waiter = this.#waiters.shift();
if (waiter !== undefined) {
waiter.resolve({ value, done: false });
return;
}
if (
this.#values.length >= MAX_NOTIFICATION_COUNT ||
this.#bytes + bytes > MAX_NOTIFICATION_BYTES
) {
this.#push({ kind: "notification", value, bytes: Buffer.byteLength(JSON.stringify(value)) });
}
pushControl(value: CodexRpcServerRequest, dispatch: () => void): void {
if (this.#closed) return;
// Count the retained request just like notification payloads. The callback
// is internal; a provider notification cannot create a control entry.
this.#push({ kind: "control", dispatch, bytes: Buffer.byteLength(JSON.stringify(value)) });
}
#push(entry: NotificationQueueEntry): void {
if (this.#closed) return;
if (this.#values.length >= MAX_NOTIFICATION_COUNT || this.#bytes + entry.bytes > MAX_NOTIFICATION_BYTES) {
throw new Error("PRP provider notification queue bound exceeded");
}
this.#values.push({ value, bytes });
this.#bytes += bytes;
this.#values.push(entry);
this.#bytes += entry.bytes;
this.#waiters.shift()?.();
}
close(error?: Error): void {
@@ -1522,25 +1527,29 @@ class NotificationQueue implements AsyncIterable<CodexRpcNotification> {
this.#error = error ?? null;
this.#values = [];
this.#bytes = 0;
for (const waiter of this.#waiters.splice(0)) {
if (this.#error !== null) waiter.reject(this.#error);
else waiter.resolve({ value: undefined, done: true });
}
for (const wake of this.#waiters.splice(0)) wake();
}
[Symbol.asyncIterator](): AsyncIterator<CodexRpcNotification> {
return {
next: async () => {
const queued = this.#values.shift();
if (queued !== undefined) {
this.#bytes -= queued.bytes;
return { value: queued.value, done: false };
for (;;) {
if (this.#error !== null) throw this.#error;
if (this.#closed) return { value: undefined, done: true };
const queued = this.#values.shift();
if (queued !== undefined) {
this.#bytes -= queued.bytes;
if (queued.kind === "control") {
// The consumer asks for next only after mapping the previous
// notification. Start the request here without awaiting the
// human response, so subsequent provider activity keeps flowing.
queued.dispatch();
continue;
}
return { value: queued.value, done: false };
}
await new Promise<void>(resolve => this.#waiters.push(resolve));
}
if (this.#error !== null) throw this.#error;
if (this.#closed) return { value: undefined, done: true };
return new Promise((resolveValue, reject) =>
this.#waiters.push({ resolve: resolveValue, reject }),
);
},
};
}
@@ -6087,14 +6096,15 @@ class DurablePrpCodexTransport implements CodexAppServerTransport {
isAcpxCanonicalInputMethod(method) || permission) &&
!this.#bridgedRuntimeInputs.has(requestId)
) {
this.#bridgedRuntimeInputs.set(requestId, {
const binding = {
permission,
durableTurnId:
typeof event.envelope.turnId === "string"
? event.envelope.turnId
: this.#durableTurnId,
});
void this.#handler({
};
this.#bridgedRuntimeInputs.set(requestId, binding);
const request: CodexRpcServerRequest = {
id: requestId,
method,
params,
@@ -6102,10 +6112,21 @@ class DurablePrpCodexTransport implements CodexAppServerTransport {
sourceEventId: event.sourceEventId,
sourceEventType: event.eventType,
},
}).catch((error) => {
this.#failTransport(
error instanceof Error ? error : new Error(String(error)),
);
};
const threadId = this.#threadId, turnId = this.#turnId, handler = this.#handler;
this.#queue.pushControl(request, () => {
// A detached controller, replaced turn or settled durable request
// cannot acquire approval authority when a slow consumer resumes.
if (this.#closed || this.#failure || this.#core !== core || this.#handler !== handler
|| this.#threadId !== threadId || this.#turnId !== turnId
|| this.#bridgedRuntimeInputs.get(requestId) !== binding) return;
try {
void handler(request).catch((error) => {
this.#failTransport(error instanceof Error ? error : new Error(String(error)));
});
} catch (error) {
this.#failTransport(error instanceof Error ? error : new Error(String(error)));
}
});
}
continue;
@@ -0,0 +1,33 @@
{
"commandDigest": "sha256:c6741d7e49cd1af4ecad9e07181ef96305bde48b56dce2958547f2f066666231",
"declaration": {
"schema": "paperclip.acpx_profile_declaration.v1",
"agent": "copilot",
"agentProfileVersion": 10,
"acpxVersion": "0.13.1",
"agentServerVersion": "1.0.88",
"protocolPolicyRevision": "copilot-agent-manual-v1",
"acpxPatchSha256": "bd5393058a218040d217fa85449d59a6f30507de54cd645bf0ef21422823f85e",
"policySha256": "a4be69be43db84052560420a3ca546a665c9165573c24d543eb33d144ba138a3",
"distributionSourceSha256": "c0a65e247fc47b263bd369a3d5ab505c4b323d4e6493be8a9ecbeb0e9dbb9107",
"agentFilesBinding": "registered-runtime-context-v1",
"systemInstructionDelivery": "COPILOT_HOME/copilot-instructions.md:replace-under-lifetime-lease-before-launch:v1",
"sharedRuntimeContract": "paperclip.acpx-runtime-contract.v1",
"innerDistributionSourceSha256": "9bb08347eed01f1ab44e065c8b06ead9be3a25973d6e6329dc4c0a099096279a",
"upstreamAppSha256": "7b48282a19b5b0814a0c96ad5e3a125173d792cc55f9525b2effea962f6063c0",
"patchedAppSha256": "61f8eebe0c30cc03b311c6818b2acb158a6d16ca58c8bfac5ebd42db095c2679",
"messageIdentityContract": "copilot-native-message-id-v1",
"ownedDistributionDelivery": "COPILOT_CLI_DIST_DIR:lease-owned-guarded-inner-distribution:v1",
"permissionContextContract": "copilot-edit-permission-context-v1",
"permissionContextSourceSha256": "fe1bb611bea289d81b1c7c973fbb01b93de133a7caa8fe78b7ff4ee1f485b224",
"permissionAdapterSourceSha256": "49421a779c76e286ce65d75052026eab9630b1995af9ccf045a2d43d284633ce",
"permissionLocationsSourceSha256": "f39a81da395b6e23aa2a1a45572a28846e5e81bfd3d764d9a456f74a79c752e9",
"permissionRedactionSourceSha256": "687270d7bbe3dccce6c2fed8664e76cda724b43e545cb153b9f54b018de52927",
"permissionClassifierSourceSha256": "1161eabd82e26133e3b3db3ab567f65d52808b03f176e93497e02c8330349fb4",
"permissionIdentitySourceSha256": "770b47305e571a81f344883057d0e4a482a1cd59ac77d045836593a8e739deb1",
"semanticToolReceiptContract": "paperclip.semantic_tool_receipt.v1",
"semanticReceiptSourceSha256": "3d3d0fe5ce0e4dbfc78cf95b1bfcff4d4b3760c548e74c6c12db5bcacdd46ae2",
"semanticBridgeSourceSha256": "ab8f872344b2beb50e3f9970e0631c451a5493e66d259582ecc9a214624269b5",
"toolEvidenceSourceSha256": "f0a93aab9940051972028d6f2610b4018a5a0d6b2326b7c61b767b38442629ca"
}
}
@@ -0,0 +1,59 @@
{
"commandDigest": "sha256:1df2a15b93bc3a14fa47fa3315344ba023fe2412048047cdc6f32096a6336564",
"declaration": {
"schema": "paperclip.acpx_profile_declaration.v1",
"agent": "cursor",
"agentProfileVersion": 10,
"acpxVersion": "0.13.1",
"agentServerVersion": "2026.09.26-dd393fe",
"patchVersion": "paperclip-cursor-usage-v4",
"distribution": {
"schema": "paperclip.cursor_distribution.v1",
"version": "2026.09.26-dd393fe",
"platforms": {
"darwin-arm64": {
"url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/darwin/arm64/agent-cli-package.tar.gz",
"archiveSha256": "538827d96a779bab854a865c8e42859e8e87db34b5f69770261b90fc8cfff191",
"closureSha256": "257424bd48e35412091c6adfc61e4648e836757ec1d240d890bba81a24918c30",
"executable": "node",
"entrypoint": "index.js",
"vendorClosureSha256": "77394184a89b0e7384971181da19c3c82d83a399b04e7944b3f94fe3d7e62b25"
},
"darwin-x64": {
"url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/darwin/x64/agent-cli-package.tar.gz",
"archiveSha256": "ed1771c44cbf0f8059c67cac0d939e6a60eb730bd066d7dc4cbb14de314cfb6e",
"closureSha256": "6f28c799c5afdc64fbdff8a2157f565f17ae7615efe014ac389d63bf70cf2be2",
"executable": "node",
"entrypoint": "index.js",
"vendorClosureSha256": "7c8775160af74e5fb8d25a30e8412c1a6476b0661529078a686e5118fd1c5e5f"
},
"linux-x64": {
"url": "https://downloads.cursor.com/lab/2026.09.26-dd393fe/linux/x64/agent-cli-package.tar.gz",
"archiveSha256": "8085fd120f5c71f4eae7fea26a043718e5644e3071e4fab3220a0e58c51f9593",
"closureSha256": "eadb8bb8ffb0450455b15b88c9b230307a9e149958a0c452d16dd157b4633d74",
"executable": "node",
"entrypoint": "index.js",
"vendorClosureSha256": "bf04ef8ea6a63191067a6b3e15139aa2c793d8419daab246aa3f0a012e1bbcd9"
}
},
"patchVersion": "paperclip-cursor-usage-v4"
},
"agentFilesBinding": "registered-runtime-context-v1",
"instructionBinding": "native-global-rules-v1",
"instructionAdmission": "synchronous-protocol-guard-v1",
"acpxPatchSha256": "bd5393058a218040d217fa85449d59a6f30507de54cd645bf0ef21422823f85e",
"sessionModeAdmission": "native-config-ack-recovery-bound-v1",
"sessionModes": [
"agent",
"plan",
"ask"
],
"defaultSessionMode": "agent",
"sharedRuntimeContract": "paperclip.acpx-runtime-contract.v1",
"nativePlanToolIdentity": "request-item-id-bound-lifecycle-v1",
"nativePermissionToolIdentity": "opaque-native-tool-id-sha256-v1",
"toolIdentitySourceSha256": "770b47305e571a81f344883057d0e4a482a1cd59ac77d045836593a8e739deb1",
"permissionAdapterSourceSha256": "49421a779c76e286ce65d75052026eab9630b1995af9ccf045a2d43d284633ce",
"toolEvidenceSourceSha256": "8310308ed9605415cb28b7c350d83defef68e90cd30bc2f0491d3d09825e8cd9"
}
}
@@ -0,0 +1,41 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { heartbeatRuns, issues, issueThreadInteractions, issueApprovals, type Db } from "@paperclipai/db";
import type { PrpStructuredRunResult } from "../../vendor/paperclip-runner/index.js";
import { nativeCompletionFeedback } from "./native-completion-feedback.js";
const state = vi.hoisted(() => ({ blockers: 0 }));
vi.mock("./native-deliverable-feedback.js", () => ({ validateNativeDeliverableEvidence: vi.fn(async () => undefined) }));
vi.mock("./automatic-completion-reviews.js", () => ({ findAutomaticCompletionReviews: vi.fn(async () => []) }));
vi.mock("../agent-invokability.js", () => ({ evaluateAgentInvokabilityFromDb: vi.fn() }));
vi.mock("../issues.js", () => ({ issueService: () => ({ getDependencyReadiness: async () => ({ unresolvedBlockerCount: state.blockers }) }) }));
vi.mock("./native-review-participant.js", () => ({ readNativeReviewAssignmentContext: () => null, getNativeReviewAssignment: vi.fn() }));
vi.mock("../../vendor/paperclip-runner/index.js", () => ({ normalizePrpResultSignals: () => ({ verification: [], actionableAttentionRequests: [] }) }));
const result = { reportedWorkDisposition: "done", summary: "EXACT_PRIVATE_MARKER", completionClaim: { objectiveSatisfied: true, criteria: [], remainingWork: [] } } as unknown as PrpStructuredRunResult;
function database(options: { interaction?: boolean; approval?: boolean; review?: boolean } = {}): Db {
// Pure query double: no client, PostgreSQL process, or network is created.
return { select: () => ({ from: (table: unknown) => {
const rows = table === heartbeatRuns ? [{ id: "run", companyId: "company", nativeIssueId: "issue", contextSnapshot: {} }]
: table === issues ? [{ id: "issue", companyId: "company", status: "in_progress", ...(options.review ? { executionState: { status: "pending" } } : {}) }]
: table === issueThreadInteractions && options.interaction ? [{ id: "request", kind: "request_confirmation", title: "Decision" }]
: table === issueApprovals && options.approval ? [{ id: "approval" }] : [];
const query = { where: () => query, limit: () => query, innerJoin: () => query, then: (resolve: (value: unknown[]) => unknown) => Promise.resolve(rows).then(resolve) };
return query;
} }) } as unknown as Db;
}
beforeEach(() => { state.blockers = 0; });
describe("native completion feedback format precedence", () => {
it("honors requested final format only after normal completion acceptance without echoing the summary", async () => {
const feedback = await nativeCompletionFeedback(database(), "run", result);
expect(feedback).toContain("Follow the user's explicitly requested final-response format, including an exact response when requested.");
expect(feedback).toContain("Task status will be committed after this turn and workspace finalization finish.");
expect(feedback).toContain("Do not claim an approval is needed unless one was requested.");
expect(feedback).not.toContain(result.summary);
});
it.each(["interaction", "approval", "review", "dependency"] as const)("preserves %s governance feedback instead of granting format precedence", async mode => {
state.blockers = mode === "dependency" ? 1 : 0;
const feedback = await nativeCompletionFeedback(database({ interaction: mode === "interaction", approval: mode === "approval", review: mode === "review" }), "run", result);
expect(feedback).not.toContain("final-response format");
expect(feedback).toMatch(/still waiting|still pending|unresolved dependencies/);
});
});
@@ -183,5 +183,5 @@ export async function nativeCompletionFeedback(
throw new Error("The named reviewer is not available in this company. Choose an available reviewer or report the concrete blocker.");
}
}
return "Completion report accepted. Task status will be committed after this turn and workspace finalization finish. Describe the completed work and any explicitly requested reviewer action; do not claim an approval is needed unless one was requested.";
return "Completion report accepted. Task status will be committed after this turn and workspace finalization finish. Follow the user's explicitly requested final-response format, including an exact response when requested. Otherwise describe the completed work and any explicitly requested reviewer action. Do not claim an approval is needed unless one was requested.";
}
@@ -94,7 +94,8 @@ describe("accepted Cursor plan passive-wait authority", () => {
const facts = fixture();
expect(nativeCursorPlanWaitFromFacts(facts)).not.toBeNull();
const current = resolveQualifiedAcpxProfile("cursor", "gpt-5.6-luna[context=272k,reasoning=medium,fast=false]");
const next = { ...current, agentProfileVersion: 10, commandDigest: `sha256:${"b".repeat(64)}` } satisfies typeof current;
// Model a future catalog revision without tying this test to today's version.
const next = { ...current, agentProfileVersion: (current.agentProfileVersion + 1) as typeof current.agentProfileVersion, commandDigest: `sha256:${"b".repeat(64)}` } satisfies typeof current;
expect(next.agentProfileVersion).toBeGreaterThan(current.agentProfileVersion);
const resolver = vi.spyOn(runner, "resolveQualifiedAcpxProfile").mockReturnValue(next);
try { expect(nativeCursorPlanWaitFromFacts(facts)).toBeNull(); }