Skip to content

The open-source app everyone uses to manage agents at work

feat(runner): normalize provider event contracts (#12350)

Dottab1cd2612121a
diff --git a/packages/paperclip-runner/protocol/manifest.json b/packages/paperclip-runner/protocol/manifest.json
index f3de19ef14..8575322f47 100644
--- a/packages/paperclip-runner/protocol/manifest.json
+++ b/packages/paperclip-runner/protocol/manifest.json
@@ -30,7 +30,7 @@
{
"path": "schemas/event.schema.json",
"id": "https://paperclip.dev/schemas/prp/v1/event.schema.json",
- "sha256": "d69ac4acfd9cd265f9dcb6a6580e949a67a50347093d0a7c12c2000a2da6d482"
+ "sha256": "e9827a7c31f004ae91388964a96b4ddf6ab40b85f29bf3922683d5dcf64f2559"
},
{
"path": "schemas/fixture.schema.json",
@@ -45,12 +45,12 @@
{
"path": "schemas/provider-descriptor.schema.json",
"id": "https://paperclip.dev/schemas/prp/v1/provider-descriptor.schema.json",
- "sha256": "26e8af9314f1ca49578bfbacdcc111332225b422ea4ff68918a25ddac59129a6"
+ "sha256": "a56c0c8501171c34bb72f6fba08d3872839a8b45bbc10daa93620afc9dc2b669"
},
{
"path": "schemas/provider-event.schema.json",
"id": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json",
- "sha256": "84521ea87ae782a7c07d1ef68b70f87fc4c436e79951a8076b7ba55e923fa88b"
+ "sha256": "e0ffb95cbde4afb65783106f471c5154cbcc59055461f96838cd8a5239e5ec56"
},
{
"path": "schemas/question-adapter-fixture.schema.json",
@@ -75,7 +75,7 @@
{
"path": "schemas/result.schema.json",
"id": "https://paperclip.dev/schemas/prp/v1/result.schema.json",
- "sha256": "90f02c0a96e8ab9f75970fd788b61c18ccbd9abbd005bedfba280701729adce0"
+ "sha256": "86d3b3c4d0f79de34a3e2e37beb183ea08d3bc9f70437a9f6f2b98bdf8faf828"
},
{
"path": "schemas/semantic-tool.schema.json",
diff --git a/packages/paperclip-runner/protocol/schemas/event.schema.json b/packages/paperclip-runner/protocol/schemas/event.schema.json
index 355e1f6477..9d2b3ed873 100644
--- a/packages/paperclip-runner/protocol/schemas/event.schema.json
+++ b/packages/paperclip-runner/protocol/schemas/event.schema.json
@@ -28,7 +28,7 @@
"itemId": { "type": "string", "minLength": 1, "maxLength": 160 },
"eventType": {
"enum": [
- "runner.connected", "runner.reconnected", "runner.reconciled", "runner.disconnected", "runner.draining", "runner.suspending", "runner.suspended", "runner.stopped", "runner.diagnostic",
+ "runner.connected", "runner.reconnected", "runner.reconciled", "runner.disconnected", "runner.draining", "runner.backpressure", "runner.suspending", "runner.suspended", "runner.stopped", "runner.diagnostic",
"runtime.phase.changed", "sandbox.metric", "workspace.ready", "workspace.change.updated", "workspace.diff.recorded", "workspace.file.referenced",
"harness.starting", "harness.ready", "harness.exited", "harness.diagnostic",
"plan.updated",
@@ -43,7 +43,7 @@
"session.starting", "session.started", "session.resuming", "session.resumed", "session.reconciled", "session.updated", "session.closed", "session.failed",
"turn.submitted", "turn.accepted", "turn.started", "turn.completed", "turn.failed", "turn.interrupted", "turn.cancelled",
"item.started", "item.delta", "item.completed", "item.failed", "usage.reported",
- "semantic_tool.input", "semantic_tool.result",
+ "semantic_tool.input", "semantic_tool.result", "semantic_tool.reconciled",
"mcp_app.discovered", "mcp_app.resource.resolved", "mcp_app.initializing", "mcp_app.ready", "mcp_app.tool_input", "mcp_app.tool_result", "mcp_app.action.requested", "mcp_app.action.resolved", "mcp_app.host_context.changed", "mcp_app.failed", "mcp_app.teardown",
"runtime_request.created", "runtime_request.resolved", "runtime_request.expired", "runtime_request.cancelled",
"interaction.request.proposed", "interaction.request.materialized", "interaction.request.rejected", "interaction.response.progressed", "interaction.response.resolved", "interaction.response.delivered",
@@ -152,6 +152,25 @@
}
}
},
+ {
+ "if": { "properties": { "eventType": { "const": "semantic_tool.reconciled" } } },
+ "then": {
+ "properties": {
+ "payload": {
+ "type": "object",
+ "properties": {
+ "semantic_tool": {
+ "allOf": [
+ { "$ref": "https://paperclip.dev/schemas/prp/v1/semantic-tool.schema.json" },
+ { "type": "object", "properties": { "phase": { "const": "reconciled" } } }
+ ]
+ }
+ },
+ "additionalProperties": true
+ }
+ }
+ }
+ },
{
"if": { "properties": { "eventType": { "const": "run.terminal" } } },
"then": {
diff --git a/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json b/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json
index 3bfbb66a06..53c174d983 100644
--- a/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json
+++ b/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json
@@ -5,13 +5,96 @@
"type": "object",
"required": ["provider", "driver", "model", "executionKind", "providerVersion"],
"properties": {
- "provider": { "const": "codex" },
- "driver": { "const": "codex_app_server" },
+ "provider": { "enum": ["codex", "opencode", "claude_managed", "aws_agentcore", "acpx"] },
+ "driver": { "enum": ["codex_app_server", "opencode_server", "claude_managed_agents_api", "aws_agentcore_harness_api", "acpx_runtime"] },
"model": { "type": ["string", "null"], "maxLength": 240 },
- "executionKind": { "const": "local_process" },
+ "executionKind": { "enum": ["local_process", "remote_service"] },
"providerVersion": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "service": { "enum": ["anthropic_managed_agents", "aws_bedrock_agentcore_harness"] },
"providerSessionId": { "type": ["string", "null"], "maxLength": 240 },
- "processId": { "type": ["integer", "null"], "minimum": 1 }
+ "processId": { "type": ["integer", "null"], "minimum": 1 },
+ "agentProcessId": { "type": ["integer", "null"], "minimum": 1 },
+ "endpointArn": { "type": "string", "minLength": 1, "maxLength": 2048 },
+ "endpointQualifier": { "type": "string", "minLength": 1, "maxLength": 240 },
+ "memoryId": { "type": "string", "minLength": 1, "maxLength": 240 },
+ "eventExpiryDays": { "const": 90 },
+ "agent": { "enum": ["pi", "claude", "codex"] },
+ "requestedModel": { "type": "string", "minLength": 1, "maxLength": 240 },
+ "acpProtocolVersion": { "const": 1 },
+ "agentServerPackage": { "type": "string", "minLength": 1, "maxLength": 240 },
+ "agentServerVersion": { "type": "string", "minLength": 1, "maxLength": 120 },
+ "agentRuntimePackage": { "type": ["string", "null"], "maxLength": 240 },
+ "agentRuntimeVersion": { "type": ["string", "null"], "maxLength": 120 },
+ "acpxRecordId": { "type": ["string", "null"], "maxLength": 240 }
},
- "additionalProperties": true
+ "allOf": [
+ {
+ "oneOf": [
+ {
+ "properties": {
+ "provider": { "const": "codex" },
+ "driver": { "const": "codex_app_server" },
+ "executionKind": { "const": "local_process" }
+ }
+ },
+ {
+ "properties": {
+ "provider": { "const": "opencode" },
+ "driver": { "const": "opencode_server" },
+ "executionKind": { "const": "local_process" }
+ }
+ },
+ {
+ "properties": {
+ "provider": { "const": "claude_managed" },
+ "driver": { "const": "claude_managed_agents_api" },
+ "executionKind": { "const": "remote_service" }
+ }
+ },
+ {
+ "properties": {
+ "provider": { "const": "aws_agentcore" },
+ "driver": { "const": "aws_agentcore_harness_api" },
+ "executionKind": { "const": "remote_service" }
+ }
+ },
+ {
+ "properties": {
+ "provider": { "const": "acpx" },
+ "driver": { "const": "acpx_runtime" },
+ "executionKind": { "const": "local_process" }
+ }
+ }
+ ]
+ },
+ {
+ "if": { "properties": { "executionKind": { "const": "remote_service" } } },
+ "then": {
+ "required": ["service"],
+ "properties": { "processId": { "const": null } }
+ }
+ },
+ {
+ "if": { "properties": { "executionKind": { "const": "local_process" } } },
+ "then": { "properties": { "service": false } }
+ },
+ {
+ "if": { "properties": { "provider": { "const": "claude_managed" } }, "required": ["provider"] },
+ "then": { "properties": { "service": { "const": "anthropic_managed_agents" } }, "required": ["service"] }
+ },
+ {
+ "if": { "properties": { "provider": { "const": "aws_agentcore" } }, "required": ["provider"] },
+ "then": {
+ "properties": { "service": { "const": "aws_bedrock_agentcore_harness" } },
+ "required": ["service", "endpointArn", "endpointQualifier", "memoryId", "eventExpiryDays"]
+ }
+ },
+ {
+ "if": { "properties": { "provider": { "const": "acpx" } }, "required": ["provider"] },
+ "then": {
+ "required": ["agent", "requestedModel", "acpProtocolVersion", "agentServerPackage", "agentServerVersion", "acpxRecordId", "agentProcessId"]
+ }
+ }
+ ],
+ "additionalProperties": false
}
diff --git a/packages/paperclip-runner/protocol/schemas/provider-event.schema.json b/packages/paperclip-runner/protocol/schemas/provider-event.schema.json
index 8af5200ddf..f0275dabf5 100644
--- a/packages/paperclip-runner/protocol/schemas/provider-event.schema.json
+++ b/packages/paperclip-runner/protocol/schemas/provider-event.schema.json
@@ -28,6 +28,7 @@
"safeUrl": { "type": ["string", "null"], "maxLength": 8192, "pattern": "^https?://" },
"plan": {
"type": "object",
+ "description": "A complete provider-authored within-turn checklist snapshot. Consumers replace the prior snapshot with the same planId in PRP sourceSeq order; this is not Paperclip's durable Plan document.",
"required": ["schema", "planId", "revision", "steps", "complete", "syncStatus"],
"properties": {
"schema": { "const": "paperclip.plan.updated.v1" },
@@ -36,8 +37,8 @@
"explanation": { "$ref": "#/$defs/nullableShortText" },
"steps": { "type": "array", "maxItems": 256, "items": { "type": "object", "required": ["stepId", "body", "status"], "properties": { "stepId": { "$ref": "#/$defs/id" }, "body": { "$ref": "#/$defs/shortText" }, "status": { "enum": ["pending", "in_progress", "completed", "blocked"] } }, "additionalProperties": false } },
"complete": { "type": "boolean" },
- "syncStatus": { "enum": ["streaming", "pending", "synchronized", "conflict", "not_applicable"] },
- "documentRevision": { "type": ["integer", "null"], "minimum": 1 }
+ "syncStatus": { "description": "Legacy compatibility field. Within-turn checklist snapshots use not_applicable.", "enum": ["streaming", "pending", "synchronized", "conflict", "not_applicable"] },
+ "documentRevision": { "description": "Legacy compatibility field. Within-turn checklist snapshots use null.", "type": ["integer", "null"], "minimum": 1 }
},
"additionalProperties": false
},
diff --git a/packages/paperclip-runner/protocol/schemas/result.schema.json b/packages/paperclip-runner/protocol/schemas/result.schema.json
index 62983b280e..95f438d45a 100644
--- a/packages/paperclip-runner/protocol/schemas/result.schema.json
+++ b/packages/paperclip-runner/protocol/schemas/result.schema.json
@@ -92,7 +92,15 @@
"required": ["reasonCode", "owner", "unblockAction", "scope"],
"properties": {
"reasonCode": { "type": "string", "minLength": 1 },
- "owner": { "type": "object", "additionalProperties": true },
+ "owner": {
+ "type": "object",
+ "required": ["kind", "name"],
+ "properties": {
+ "kind": { "enum": ["agent", "user", "system", "external"] },
+ "name": { "type": "string", "minLength": 1 }
+ },
+ "additionalProperties": true
+ },
"unblockAction": { "type": "string", "minLength": 1 },
"scope": { "enum": ["current_track", "task_wide"] }
},
diff --git a/packages/paperclip-runner/scripts/protocol-contract.mjs b/packages/paperclip-runner/scripts/protocol-contract.mjs
index 35743d4c7d..9ee5e8bde8 100644
--- a/packages/paperclip-runner/scripts/protocol-contract.mjs
+++ b/packages/paperclip-runner/scripts/protocol-contract.mjs
@@ -122,6 +122,7 @@ export function compileProtocolValidators(schemaRecords) {
conformanceFixture: get("conformance-fixture"),
conformanceOutput: get("conformance-output"),
fixture: get("fixture"),
+ providerDescriptor: get("provider-descriptor"),
questionAdapterFixture: get("question-adapter-fixture"),
};
}
diff --git a/packages/paperclip-runner/src/index.ts b/packages/paperclip-runner/src/index.ts
index 8c8f4d86db..4a01c2340d 100644
--- a/packages/paperclip-runner/src/index.ts
+++ b/packages/paperclip-runner/src/index.ts
@@ -8,6 +8,7 @@ export {
export type { DurableRecoveryIdentity } from "./control-plane/prp-transport-types.js";
export * from "./protocol/replay-contract.js";
export * from "./protocol/result-normalization.js";
+export * from "./provider-events.js";
export * from "./reducer/session-reducer.js";
export * from "./semantic-tools/index.js";
export * from "./tracer/replay.js";
diff --git a/packages/paperclip-runner/src/protocol/generated/schema-bundle.ts b/packages/paperclip-runner/src/protocol/generated/schema-bundle.ts
index e6a87e032f..d6b096a2db 100644
--- a/packages/paperclip-runner/src/protocol/generated/schema-bundle.ts
+++ b/packages/paperclip-runner/src/protocol/generated/schema-bundle.ts
@@ -344,10 +344,22 @@ export const providerDescriptorSchema = {
],
"properties": {
"provider": {
- "const": "codex"
+ "enum": [
+ "codex",
+ "opencode",
+ "claude_managed",
+ "aws_agentcore",
+ "acpx"
+ ]
},
"driver": {
- "const": "codex_app_server"
+ "enum": [
+ "codex_app_server",
+ "opencode_server",
+ "claude_managed_agents_api",
+ "aws_agentcore_harness_api",
+ "acpx_runtime"
+ ]
},
"model": {
"type": [
@@ -357,13 +369,22 @@ export const providerDescriptorSchema = {
"maxLength": 240
},
"executionKind": {
- "const": "local_process"
+ "enum": [
+ "local_process",
+ "remote_service"
+ ]
},
"providerVersion": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
+ "service": {
+ "enum": [
+ "anthropic_managed_agents",
+ "aws_bedrock_agentcore_harness"
+ ]
+ },
"providerSessionId": {
"type": [
"string",
@@ -377,9 +398,255 @@ export const providerDescriptorSchema = {
"null"
],
"minimum": 1
+ },
+ "agentProcessId": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "minimum": 1
+ },
+ "endpointArn": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 2048
+ },
+ "endpointQualifier": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 240
+ },
+ "memoryId": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 240
+ },
+ "eventExpiryDays": {
+ "const": 90
+ },
+ "agent": {
+ "enum": [
+ "pi",
+ "claude",
+ "codex"
+ ]
+ },
+ "requestedModel": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 240
+ },
+ "acpProtocolVersion": {
+ "const": 1
+ },
+ "agentServerPackage": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 240
+ },
+ "agentServerVersion": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 120
+ },
+ "agentRuntimePackage": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "maxLength": 240
+ },
+ "agentRuntimeVersion": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "maxLength": 120
+ },
+ "acpxRecordId": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "maxLength": 240
}
},
- "additionalProperties": true
+ "allOf": [
+ {
+ "oneOf": [
+ {
+ "properties": {
+ "provider": {
+ "const": "codex"
+ },
+ "driver": {
+ "const": "codex_app_server"
+ },
+ "executionKind": {
+ "const": "local_process"
+ }
+ }
+ },
+ {
+ "properties": {
+ "provider": {
+ "const": "opencode"
+ },
+ "driver": {
+ "const": "opencode_server"
+ },
+ "executionKind": {
+ "const": "local_process"
+ }
+ }
+ },
+ {
+ "properties": {
+ "provider": {
+ "const": "claude_managed"
+ },
+ "driver": {
+ "const": "claude_managed_agents_api"
+ },
+ "executionKind": {
+ "const": "remote_service"
+ }
+ }
+ },
+ {
+ "properties": {
+ "provider": {
+ "const": "aws_agentcore"
+ },
+ "driver": {
+ "const": "aws_agentcore_harness_api"
+ },
+ "executionKind": {
+ "const": "remote_service"
+ }
+ }
+ },
+ {
+ "properties": {
+ "provider": {
+ "const": "acpx"
+ },
+ "driver": {
+ "const": "acpx_runtime"
+ },
+ "executionKind": {
+ "const": "local_process"
+ }
+ }
+ }
+ ]
+ },
+ {
+ "if": {
+ "properties": {
+ "executionKind": {
+ "const": "remote_service"
+ }
+ }
+ },
+ "then": {
+ "required": [
+ "service"
+ ],
+ "properties": {
+ "processId": {
+ "const": null
+ }
+ }
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "executionKind": {
+ "const": "local_process"
+ }
+ }
+ },
+ "then": {
+ "properties": {
+ "service": false
+ }
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "provider": {
+ "const": "claude_managed"
+ }
+ },
+ "required": [
+ "provider"
+ ]
+ },
+ "then": {
+ "properties": {
+ "service": {
+ "const": "anthropic_managed_agents"
+ }
+ },
+ "required": [
+ "service"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "provider": {
+ "const": "aws_agentcore"
+ }
+ },
+ "required": [
+ "provider"
+ ]
+ },
+ "then": {
+ "properties": {
+ "service": {
+ "const": "aws_bedrock_agentcore_harness"
+ }
+ },
+ "required": [
+ "service",
+ "endpointArn",
+ "endpointQualifier",
+ "memoryId",
+ "eventExpiryDays"
+ ]
+ }
+ },
+ {
+ "if": {
+ "properties": {
+ "provider": {
+ "const": "acpx"
+ }
+ },
+ "required": [
+ "provider"
+ ]
+ },
+ "then": {
+ "required": [
+ "agent",
+ "requestedModel",
+ "acpProtocolVersion",
+ "agentServerPackage",
+ "agentServerVersion",
+ "acpxRecordId",
+ "agentProcessId"
+ ]
+ }
+ }
+ ],
+ "additionalProperties": false
} as const;
export const providerEventSchema = {
@@ -472,6 +739,7 @@ export const providerEventSchema = {
},
"plan": {
"type": "object",
+ "description": "A complete provider-authored within-turn checklist snapshot. Consumers replace the prior snapshot with the same planId in PRP sourceSeq order; this is not Paperclip's durable Plan document.",
"required": [
"schema",
"planId",
@@ -527,6 +795,7 @@ export const providerEventSchema = {
"type": "boolean"
},
"syncStatus": {
+ "description": "Legacy compatibility field. Within-turn checklist snapshots use not_applicable.",
"enum": [
"streaming",
"pending",
@@ -536,6 +805,7 @@ export const providerEventSchema = {
]
},
"documentRevision": {
+ "description": "Legacy compatibility field. Within-turn checklist snapshots use null.",
"type": [
"integer",
"null"
@@ -2775,6 +3045,24 @@ export const resultSchema = {
},
"owner": {
"type": "object",
+ "required": [
+ "kind",
+ "name"
+ ],
+ "properties": {
+ "kind": {
+ "enum": [
+ "agent",
+ "user",
+ "system",
+ "external"
+ ]
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1
+ }
+ },
"additionalProperties": true
},
"unblockAction": {
@@ -2974,6 +3262,7 @@ export const eventSchema = {
"runner.reconciled",
"runner.disconnected",
"runner.draining",
+ "runner.backpressure",
"runner.suspending",
"runner.suspended",
"runner.stopped",
@@ -3035,6 +3324,7 @@ export const eventSchema = {
"usage.reported",
"semantic_tool.input",
"semantic_tool.result",
+ "semantic_tool.reconciled",
"mcp_app.discovered",
"mcp_app.resource.resolved",
"mcp_app.initializing",
@@ -3533,6 +3823,40 @@ export const eventSchema = {
}
}
},
+ {
+ "if": {
+ "properties": {
+ "eventType": {
+ "const": "semantic_tool.reconciled"
+ }
+ }
+ },
+ "then": {
+ "properties": {
+ "payload": {
+ "type": "object",
+ "properties": {
+ "semantic_tool": {
+ "allOf": [
+ {
+ "$ref": "https://paperclip.dev/schemas/prp/v1/semantic-tool.schema.json"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "phase": {
+ "const": "reconciled"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "additionalProperties": true
+ }
+ }
+ }
+ },
{
"if": {
"properties": {
diff --git a/packages/paperclip-runner/src/protocol/result-normalization.test.ts b/packages/paperclip-runner/src/protocol/result-normalization.test.ts
index cf68d2977d..2473b821fe 100644
--- a/packages/paperclip-runner/src/protocol/result-normalization.test.ts
+++ b/packages/paperclip-runner/src/protocol/result-normalization.test.ts
@@ -69,6 +69,44 @@ describe("normalizePrpResultSignals", () => {
});
});
+ it("requires an identified owner for blocked results", () => {
+ const blockedResult = {
+ reportedWorkDisposition: "blocked",
+ summary: "External input is required.",
+ completionClaim: {
+ contractRevision: "1",
+ objectiveSatisfied: false,
+ criteria: [
+ { criterionId: "objective", status: "not_satisfied", evidenceRefs: [] },
+ ],
+ remainingWork: [
+ { description: "Wait for external input.", blocksCompletion: true },
+ ],
+ },
+ evidence: [],
+ verification: [],
+ blocker: {
+ reasonCode: "external_input_required",
+ owner: {},
+ unblockAction: "Provide the required input.",
+ scope: "current_track",
+ },
+ };
+
+ expect(validatePrpStructuredRunResult(blockedResult)).toMatchObject({
+ ok: false,
+ });
+ expect(
+ validatePrpStructuredRunResult({
+ ...blockedResult,
+ blocker: {
+ ...blockedResult.blocker,
+ owner: { kind: "external", name: "External input" },
+ },
+ }),
+ ).toMatchObject({ ok: true });
+ });
+
it("normalizes unambiguous completion aliases emitted by smaller tool callers", () => {
const toolShaped = {
schema: "paperclip_paperclip_finish",
diff --git a/packages/paperclip-runner/src/provider-events.test.ts b/packages/paperclip-runner/src/provider-events.test.ts
new file mode 100644
index 0000000000..887ad58d32
--- /dev/null
+++ b/packages/paperclip-runner/src/provider-events.test.ts
@@ -0,0 +1,409 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ CODEX_THREAD_ITEM_CLASSIFICATION,
+ PROVIDER_EVENT_FAMILIES,
+ canonicalProviderEventsFromAcpxRuntimeEvent,
+ canonicalProviderEventsFromCodex,
+ canonicalProviderEventsFromOpenCodePart,
+ createAcpxToolEventNormalizer,
+ providerFamilyCapabilities,
+} from "./provider-events.js";
+import { validatePrpEvent } from "./protocol/replay-contract.js";
+
+function envelope(event: ReturnType<typeof canonicalProviderEventsFromCodex>[number]) {
+ return {
+ schema: "paperclip.prp.event.v1", sourceEventId: `source:${event.itemId}`, sourceSeq: 1,
+ sourceInstanceId: "runner-1", sourceKind: "runner", runId: "run-1",
+ normalizedSessionId: "session-1", turnId: "turn-1", itemId: event.itemId,
+ eventType: event.eventType, schemaVersion: 1, priority: 1,
+ emittedAt: "2026-08-21T12:00:00.000Z", payload: event.payload,
+ };
+}
+
+describe("provider-neutral events", () => {
+ it("classifies the complete qualified 18-variant Codex ThreadItem inventory", () => {
+ expect(Object.keys(CODEX_THREAD_ITEM_CLASSIFICATION)).toEqual([
+ "userMessage", "hookPrompt", "agentMessage", "plan", "reasoning",
+ "commandExecution", "fileChange", "mcpToolCall", "dynamicToolCall",
+ "collabAgentToolCall", "subAgentActivity", "webSearch", "imageView",
+ "sleep", "imageGeneration", "enteredReviewMode", "exitedReviewMode",
+ "contextCompaction",
+ ]);
+ expect(Object.values(CODEX_THREAD_ITEM_CLASSIFICATION)).not.toContain("unclassified");
+ expect(CODEX_THREAD_ITEM_CLASSIFICATION.plan).toBe("existing_transcript");
+ });
+
+ it("negotiates every declared family and preserves explicit unsupported states", () => {
+ const capabilities = providerFamilyCapabilities({ plan: "available", artifact: "policy_disabled" });
+ expect(capabilities).toHaveLength(PROVIDER_EVENT_FAMILIES.length);
+ expect(capabilities.find((entry) => entry.family === "plan")?.detailLevel).toBe("structured");
+ expect(capabilities.find((entry) => entry.family === "artifact")?.availability).toBe("policy_disabled");
+ expect(capabilities.find((entry) => entry.family === "memory")?.availability).toBe("unsupported");
+ });
+
+ it("maps representative Codex variants across every canonical family to valid PRP", () => {
+ const cases: Array<[string, Record<string, unknown>]> = [
+ ["turn/plan/updated", { turnId: "turn-1", plan: [{ step: "Ship it", status: "inProgress" }] }],
+ ["item/completed", { item: { id: "exec-1", type: "commandExecution", status: "completed", output: "ok" } }],
+ ["item/completed", { item: { id: "web-1", type: "webSearch", action: { type: "search", query: "PRP" }, results: [{ ref_id: "source-1", title: "Protocol notes", url: "https://example.com/prp", snippet: "Canonical event details" }] } }],
+ ["item/completed", { item: { id: "child-1", type: "collabAgentToolCall", tool: "spawnAgent" } }],
+ ["model/rerouted", { turnId: "turn-1", fromModel: "gpt-5", toModel: "gpt-5.1", reason: "capacity" }],
+ ["thread/compacted", { itemId: "compact-1" }],
+ ["item/completed", { item: { id: "image-1", type: "imageView", path: "artifacts/a.png" } }],
+ ["item/completed", { item: { id: "review-1", type: "enteredReviewMode" } }],
+ ["hook/completed", { run: { id: "hook-1", eventName: "post-tool", scope: "workspace", status: "completed" } }],
+ ["item/completed", { item: { id: "message-1", type: "agentMessage", memoryCitation: { entries: [{ label: "Decision" }] } } }],
+ ["item/autoApprovalReview/completed", { reviewId: "safety-1", targetItemId: "exec-1" }],
+ ["item/commandExecution/terminalInteraction", { itemId: "exec-1", stdin: "secret input" }],
+ ["item/completed", { item: { id: "wait-1", type: "sleep", durationMs: 1000 } }],
+ ["warning", { message: "Update the provider configuration" }],
+ ];
+ const mapped = cases.flatMap(([method, params]) => canonicalProviderEventsFromCodex(method, params));
+ expect(mapped).toHaveLength(cases.length);
+ for (const event of mapped) expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ expect(JSON.stringify(mapped.find((entry) => entry.eventType === "terminal.input.sent"))).not.toContain("secret input");
+ expect(mapped.find((entry) => entry.eventType === "research.completed")?.payload.sources).toEqual([{
+ sourceId: "source-1",
+ title: "Protocol notes",
+ url: "https://example.com/prp",
+ snippet: "Canonical event details",
+ }]);
+ });
+
+ it("bounds and filters Codex research sources before they enter PRP", () => {
+ const event = canonicalProviderEventsFromCodex("item/completed", {
+ item: {
+ id: "web-1",
+ type: "webSearch",
+ results: [
+ { ref_id: "good", title: "Good", url: "https://example.com/good", snippet: "x".repeat(5000) },
+ { ref_id: "unsafe", title: "Unsafe", url: "file:///etc/passwd" },
+ ],
+ },
+ })[0]!;
+ expect(event.payload.sources).toEqual([expect.objectContaining({ sourceId: "good", url: "https://example.com/good", snippet: "x".repeat(4000) })]);
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("bounds Codex plan explanations before they enter PRP", () => {
+ const event = canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-1",
+ explanation: "x".repeat(5000),
+ plan: [{ step: "Ship it", status: "inProgress" }],
+ })[0]!;
+ expect(event.payload.explanation).toBe("x".repeat(4000));
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("normalizes malformed or non-positive Codex plan revisions", () => {
+ for (const revision of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+ const event = canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-revision",
+ revision,
+ plan: [{ step: "Ship it", status: "inProgress" }],
+ })[0]!;
+ expect(event.payload.revision).toBe(1);
+ expect(validatePrpEvent(envelope(event))).toEqual({
+ ok: true,
+ event: expect.any(Object),
+ issues: [],
+ });
+ }
+ expect(canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-revision",
+ revision: 7,
+ plan: [],
+ })[0]?.payload.revision).toBe(7);
+ });
+
+ it("marks a turn plan complete when every native step is complete", () => {
+ const event = canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-1",
+ plan: [
+ { step: "Inspect", status: "completed" },
+ { step: "Implement", status: "completed" },
+ ],
+ })[0]!;
+ expect(event).toMatchObject({
+ itemId: "turn-1",
+ eventType: "plan.updated",
+ payload: {
+ planId: "turn-1",
+ complete: true,
+ syncStatus: "not_applicable",
+ documentRevision: null,
+ },
+ });
+ });
+
+ it("treats Codex proposed-plan text as transcript content, not a checklist", () => {
+ expect(canonicalProviderEventsFromCodex("item/completed", {
+ item: { id: "proposed-plan-1", type: "plan", text: "# Proposed implementation\n\nShip it." },
+ })).toEqual([]);
+ });
+
+ it("uses an empty native plan as a stable clearing snapshot", () => {
+ const event = canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-1",
+ plan: [],
+ })[0]!;
+ expect(event).toMatchObject({
+ itemId: "turn-1",
+ payload: { planId: "turn-1", steps: [], complete: false },
+ });
+ });
+
+ it("normalizes provider plan statuses without accepting malformed steps", () => {
+ const event = canonicalProviderEventsFromCodex("turn/plan/updated", {
+ turnId: "turn-statuses",
+ plan: [
+ { step: "Active", status: "inProgress" },
+ { step: "Blocked", status: "failed" },
+ { step: "Later", status: "unexpected" },
+ { step: " ", status: "completed" },
+ ],
+ })[0]!;
+ expect(event.payload.steps).toEqual([
+ { stepId: "step-1", body: "Active", status: "in_progress" },
+ { stepId: "step-2", body: "Blocked", status: "blocked" },
+ { stepId: "step-3", body: "Later", status: "pending" },
+ ]);
+ expect(event.payload.complete).toBe(false);
+ });
+
+ it("preserves every structured ACPX plan entry in a stable turn snapshot", () => {
+ const event = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "plan",
+ tag: "plan",
+ entries: [
+ { content: "Inspect", status: "completed", priority: "high" },
+ { content: "Implement", status: "in_progress", priority: "medium" },
+ { content: "Verify", status: "pending", priority: "low" },
+ ],
+ } as never, "fallback", "turn-acp")[0]!;
+
+ expect(event).toMatchObject({
+ itemId: "turn-acp",
+ eventType: "plan.updated",
+ payload: {
+ planId: "turn-acp",
+ complete: false,
+ syncStatus: "not_applicable",
+ steps: [
+ { body: "Inspect", status: "completed" },
+ { body: "Implement", status: "in_progress" },
+ { body: "Verify", status: "pending" },
+ ],
+ },
+ });
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("does not infer an ACPX checklist from legacy status text", () => {
+ const events = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "status",
+ tag: "plan",
+ text: "Implement (in progress)",
+ } as never, "fallback", "turn-acp");
+ expect(events.some((event) => event.eventType === "plan.updated")).toBe(false);
+ });
+
+ it("bounds and sanitizes structured ACPX plan snapshots", () => {
+ const entries = Array.from({ length: 300 }, (_, index) => ({
+ content: index === 3 ? " " : `Step ${index} ${"x".repeat(5_000)}`,
+ status: index === 0 ? "completed" : "pending",
+ }));
+ const event = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "plan",
+ tag: "plan",
+ entries,
+ } as never, "fallback", "turn-bounded")[0]!;
+ const steps = event.payload.steps as Array<{ body: string }>;
+ expect(steps).toHaveLength(255);
+ expect(steps.every((step) => step.body.length <= 4_000)).toBe(true);
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("classifies only structured OpenCode parts and never assistant prose", () => {
+ expect(canonicalProviderEventsFromOpenCodePart({ id: "tool-1", type: "tool", tool: "read", state: { status: "completed", output: "done" } })[0]?.eventType).toBe("tool.execution.completed");
+ expect(canonicalProviderEventsFromOpenCodePart({ id: "text-1", type: "text", text: "I ran a command and delegated work" })).toEqual([]);
+ });
+
+ it("maps OpenCode pending dynamic tools to a valid builtin execution start", () => {
+ const event = canonicalProviderEventsFromOpenCodePart({
+ id: "prt_02c35c313001X42cqyvQrpXOFv",
+ type: "tool",
+ tool: "paperclip_report_progress",
+ callID: "call_6cd0302e681d44c2aba3c164",
+ state: { status: "pending", input: {}, raw: "" },
+ })[0]!;
+ expect(event).toMatchObject({
+ eventType: "tool.execution.started",
+ payload: {
+ schema: "paperclip.tool.execution.v1",
+ transport: "builtin",
+ status: "running",
+ name: "paperclip_report_progress",
+ },
+ });
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("preserves ACPX identity across title-less progress and completion updates", () => {
+ const normalize = createAcpxToolEventNormalizer();
+ const started = normalize({
+ type: "tool_call",
+ tag: "tool_call",
+ toolCallId: "tool-1",
+ title: "mcp__paperclip__search_tasks",
+ kind: "other",
+ status: "pending",
+ text: "mcp__paperclip__search_tasks (pending)",
+ locations: [{ path: "doc/plan.md", line: 4 }],
+ } as never);
+ const progressed = normalize({
+ type: "tool_call",
+ tag: "tool_call_update",
+ toolCallId: "tool-1",
+ title: "tool call",
+ status: "in_progress",
+ text: "Searching the task index",
+ } as never);
+ const completed = normalize({
+ type: "tool_call",
+ tag: "tool_call_update",
+ toolCallId: "tool-1",
+ title: "tool call",
+ status: "completed",
+ text: "tool call (completed)",
+ rawOutput: { ok: true },
+ } as never);
+
+ expect(progressed).toMatchObject({
+ title: "mcp__paperclip__search_tasks",
+ kind: "other",
+ text: "Searching the task index",
+ locations: [{ path: "doc/plan.md", line: 4 }],
+ });
+ expect(completed).toMatchObject({
+ title: "mcp__paperclip__search_tasks",
+ kind: "other",
+ locations: [{ path: "doc/plan.md", line: 4 }],
+ });
+
+ const mapped = [started, progressed, completed].flatMap((event, index) =>
+ canonicalProviderEventsFromAcpxRuntimeEvent(event, `fallback-${index}`));
+ expect(mapped.at(-1)).toMatchObject({
+ eventType: "tool.execution.completed",
+ payload: {
+ transport: "mcp",
+ namespace: "paperclip",
+ name: "search_tasks",
+ operation: "search",
+ target: "doc/plan.md",
+ status: "completed",
+ },
+ });
+ for (const event of mapped) {
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ }
+ });
+
+ it("treats provider status metacharacters as literal progress text", () => {
+ const normalize = createAcpxToolEventNormalizer();
+ expect(() => normalize({
+ type: "tool_call",
+ tag: "tool_call",
+ toolCallId: "tool-hostile-status",
+ title: "Read",
+ kind: "read",
+ status: "[",
+ text: "Read ([)",
+ } as never)).not.toThrow();
+ expect(normalize({
+ type: "tool_call",
+ tag: "tool_call_update",
+ toolCallId: "tool-hostile-status",
+ title: "Read",
+ status: "(",
+ text: "Meaningful progress",
+ } as never)).toMatchObject({ text: "Meaningful progress" });
+ });
+
+ it("normalizes dotted MCP names, ToolSearch, and truly unnamed calls", () => {
+ const dotted = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "tool_call", tag: "tool_call", toolCallId: "mcp-1", title: "mcp.paperclip.get_task_context",
+ kind: "other", status: "pending", text: "Starting",
+ } as never, "fallback")[0]!;
+ const toolSearch = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "tool_call", tag: "tool_call", toolCallId: "search-1", title: "ToolSearch",
+ kind: "other", status: "pending", text: "Starting",
+ } as never, "fallback")[0]!;
+ const unnamed = canonicalProviderEventsFromAcpxRuntimeEvent({
+ type: "tool_call", tag: "tool_call", toolCallId: "unknown-1", title: "tool call",
+ kind: "other", status: "pending", text: "tool call (pending)",
+ } as never, "fallback")[0]!;
+
+ expect(dotted.payload).toMatchObject({ transport: "mcp", namespace: "paperclip", name: "get_task_context", operation: "read" });
+ expect(toolSearch.payload).toMatchObject({ transport: "builtin", namespace: null, name: "ToolSearch", operation: "search" });
+ expect(unnamed.payload).toMatchObject({ name: null, operation: "unknown" });
+ });
+
+ it("presents OpenCode's server-qualified semantic tool with its canonical name", () => {
+ const event = canonicalProviderEventsFromOpenCodePart({
+ id: "finish-1",
+ type: "tool",
+ tool: "paperclip_paperclip_finish",
+ state: { status: "running", input: {} },
+ })[0]!;
+ expect(event.payload).toMatchObject({ name: "paperclip_finish", transport: "builtin" });
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("recovers an interrupted OpenCode function label and error from its structured call id", () => {
+ const event = canonicalProviderEventsFromOpenCodePart({
+ id: "prt_interrupted",
+ type: "tool",
+ tool: "unknown",
+ callID: "functions.todowrite:0",
+ state: {
+ status: "error",
+ input: {},
+ error: "Tool execution aborted",
+ metadata: { interrupted: true },
+ },
+ })[0]!;
+ expect(event).toMatchObject({
+ eventType: "tool.execution.completed",
+ payload: {
+ name: "todowrite",
+ status: "failed",
+ output: "Tool execution aborted",
+ outputBytes: 22,
+ },
+ });
+ expect(validatePrpEvent(envelope(event))).toEqual({ ok: true, event: expect.any(Object), issues: [] });
+ });
+
+ it("does not infer a tool label from an opaque provider call id", () => {
+ const event = canonicalProviderEventsFromOpenCodePart({
+ id: "prt_unknown",
+ type: "tool",
+ tool: "unknown",
+ callID: "call_f3d79e",
+ state: { status: "error", error: "Unavailable" },
+ })[0]!;
+ expect(event.payload).toMatchObject({ name: "unknown", output: "Unavailable" });
+ });
+
+ it("rejects a canonical event whose payload belongs to another family", () => {
+ const plan = canonicalProviderEventsFromCodex("item/completed", {
+ item: { id: "plan-1", type: "plan", text: "Ship it" },
+ })[0]!;
+ expect(validatePrpEvent(envelope({
+ ...plan,
+ eventType: "tool.execution.completed",
+ }))).toMatchObject({ ok: false });
+ });
+});
diff --git a/packages/paperclip-runner/src/provider-events.ts b/packages/paperclip-runner/src/provider-events.ts
new file mode 100644
index 0000000000..65bedc04ca
--- /dev/null
+++ b/packages/paperclip-runner/src/provider-events.ts
@@ -0,0 +1,592 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Structural subset of an ACP runtime event consumed by the canonical event
+ * mapper. Keeping the protocol layer vendor-neutral avoids making ACPX a
+ * runtime dependency merely to describe events; the ACPX provider can pass
+ * its richer event objects directly because they satisfy this shape.
+ */
+export interface AcpRuntimeEventShape {
+ type: string;
+ toolCallId?: string;
+ title?: string;
+ kind?: string;
+ locations?: unknown[];
+ text?: string;
+ status?: string;
+ rawOutput?: unknown;
+ tag?: string;
+ entries?: Array<{ content: string; status?: string }>;
+ [key: string]: unknown;
+}
+
+export const PROVIDER_EVENT_FAMILIES = [
+ "plan", "tool_execution", "research", "delegation", "model_identity",
+ "context", "artifact", "review", "hook", "memory", "safety", "terminal",
+ "wait", "provider_notice",
+] as const;
+
+export type ProviderEventFamily = (typeof PROVIDER_EVENT_FAMILIES)[number];
+export type ProviderEventAvailability = "available" | "unsupported" | "policy_disabled";
+
+/**
+ * Exhaustive inventory from the qualified Codex app-server ThreadItem schema.
+ * Keeping this closed makes a provider upgrade fail visibly in the inventory
+ * test instead of silently dropping a new native item shape.
+ */
+export const CODEX_THREAD_ITEM_CLASSIFICATION = {
+ userMessage: "existing_transcript",
+ hookPrompt: "hook",
+ agentMessage: "existing_transcript",
+ // Codex's `plan` ThreadItem is proposed-plan document text. The live
+ // execution checklist is a separate `turn/plan/updated` notification.
+ plan: "existing_transcript",
+ reasoning: "existing_reasoning",
+ commandExecution: "tool_execution",
+ fileChange: "existing_workspace_change",
+ mcpToolCall: "tool_execution",
+ dynamicToolCall: "tool_execution",
+ collabAgentToolCall: "delegation",
+ subAgentActivity: "delegation",
+ webSearch: "research",
+ imageView: "artifact",
+ sleep: "wait",
+ imageGeneration: "artifact",
+ enteredReviewMode: "review",
+ exitedReviewMode: "review",
+ contextCompaction: "context",
+} as const satisfies Record<string, ProviderEventFamily | `existing_${string}`>;
+
+export interface TypedEventFamilyCapability {
+ family: ProviderEventFamily;
+ version: 1;
+ availability: ProviderEventAvailability;
+ detailLevel: "summary" | "structured";
+}
+
+export type CanonicalProviderEventType =
+ | "plan.updated"
+ | "tool.execution.started" | "tool.execution.progressed" | "tool.execution.completed"
+ | "research.started" | "research.progressed" | "research.completed"
+ | "delegation.started" | "delegation.updated" | "delegation.completed"
+ | "model.route.changed" | "model.verification.updated" | "context.compacted"
+ | "artifact.viewed" | "artifact.generated" | "review.mode.changed"
+ | "hook.started" | "hook.completed" | "memory.citation.referenced"
+ | "safety.review.started" | "safety.review.completed" | "terminal.input.sent"
+ | "wait.started" | "wait.completed" | "provider.notice.recorded";
+
+export interface CanonicalProviderEvent {
+ eventType: CanonicalProviderEventType;
+ payload: Record<string, unknown>;
+ itemId: string;
+}
+
+const MAX_OUTPUT = 64 * 1024;
+
+function record(value: unknown): Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+ ? value as Record<string, unknown>
+ : {};
+}
+
+function text(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function integer(value: unknown): number | null {
+ return Number.isSafeInteger(value) ? Number(value) : null;
+}
+
+function safeId(value: string, fallback: string): string {
+ const candidate = value.replace(/[^A-Za-z0-9._:-]/g, "-").slice(0, 160);
+ return /^[A-Za-z0-9]/.test(candidate) ? candidate : fallback;
+}
+
+const GENERIC_ACP_TOOL_NAMES = new Set(["tool", "tool call", "tool_call", "acp_tool"]);
+
+function normalizedToolWords(value: string): string[] {
+ return value
+ .replace(/^mcp__(.+?)__/, "")
+ .replace(/^mcp\.[^.]+\./, "")
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+ .replace(/[^A-Za-z0-9]+/g, " ")
+ .trim()
+ .toLowerCase()
+ .split(/\s+/)
+ .filter(Boolean);
+}
+
+function isGenericAcpToolName(value: unknown): boolean {
+ const name = text(value)
+ .trim()
+ .toLowerCase()
+ .replace(/\s*\((?:pending|in[_ -]?progress|completed|failed|cancelled|canceled)\)$/, "");
+ return !name || GENERIC_ACP_TOOL_NAMES.has(name);
+}
+
+function meaningfulAcpToolProgress(value: string, title: string | undefined, status: string | undefined): boolean {
+ const progress = value.trim();
+ if (!progress || /^tool(?:\s+|_)call\b/i.test(progress)) return false;
+ const statusPattern = (status ?? "")
+ .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+ .replaceAll("_", "[ _-]?");
+ if (!title || !statusPattern) return true;
+ const escapedTitle = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ return !new RegExp(`^${escapedTitle}\\s*\\(${statusPattern}\\)\\s*$`, "i").test(progress);
+}
+
+interface AcpxToolLifecycleIdentity {
+ title?: string;
+ kind?: string;
+ locations?: unknown[];
+ progress?: string;
+}
+
+/**
+ * ACP tool updates are deltas: a later update may omit the title, kind, and
+ * locations that were present on the opening event. ACPX represents a missing
+ * title as the literal `tool call`, so consumers must restore lifecycle
+ * identity before translating the event into a durable protocol record.
+ */
+export function createAcpxToolEventNormalizer<T extends AcpRuntimeEventShape>(): (event: T) => T {
+ const lifecycle = new Map<string, AcpxToolLifecycleIdentity>();
+ return (event) => {
+ if (event.type !== "tool_call" || !event.toolCallId) return event;
+ const previous = lifecycle.get(event.toolCallId) ?? {};
+ const incomingTitle = isGenericAcpToolName(event.title) ? undefined : event.title?.trim();
+ const title = previous.title ?? incomingTitle;
+ const kind = previous.kind && previous.kind !== "other"
+ ? previous.kind
+ : event.kind ?? previous.kind;
+ const locations = event.locations?.length ? event.locations : previous.locations;
+ const eventText = text(event.text);
+ const progress = meaningfulAcpToolProgress(eventText, incomingTitle, event.status)
+ ? eventText
+ : previous.progress;
+ lifecycle.set(event.toolCallId, { title, kind, locations, progress });
+ return {
+ ...event,
+ title,
+ kind,
+ locations,
+ ...(progress && canonicalStatus(event.status, "running") === "running" ? { text: progress } : {}),
+ } as T;
+ };
+}
+
+function acpxMcpToolIdentity(value: string): { namespace: string; name: string } | null {
+ const doubleUnderscore = value.match(/^mcp__(.+?)__(.+)$/i);
+ if (doubleUnderscore) return { namespace: doubleUnderscore[1], name: doubleUnderscore[2] };
+ const dotted = value.match(/^mcp\.([^.]+)\.(.+)$/i);
+ return dotted ? { namespace: dotted[1], name: dotted[2] } : null;
+}
+
+function acpxToolOperation(
+ kindValue: unknown,
+ name: string,
+): "read" | "search" | "list" | "execute" | "edit" | "unknown" {
+ const kind = text(kindValue).toLowerCase();
+ if (kind === "read") return "read";
+ if (kind === "search" || kind === "fetch") return "search";
+ if (["edit", "delete", "move"].includes(kind)) return "edit";
+ if (kind === "execute") return "execute";
+
+ const words = normalizedToolWords(name);
+ const first = words[0] ?? "";
+ const compact = words.join("");
+ if (["get", "read", "inspect", "view"].includes(first)) return "read";
+ if (["list", "glob"].includes(first)) return "list";
+ if (["toolsearch", "websearch"].includes(compact) || ["find", "search", "grep", "query", "lookup", "fetch", "open", "browse"].includes(first)) return "search";
+ if (["write", "edit", "update", "set", "patch", "upsert", "sync", "create", "add", "register", "upload", "delete", "remove", "move", "rename", "report", "answer", "request", "decide", "comment", "finish", "complete", "block"].includes(first)) return "edit";
+ if (["run", "execute", "bash", "shell", "command", "start", "spawn", "delegate", "send", "message", "stop", "cancel", "interrupt", "wait", "sleep", "poll"].includes(first)) return "execute";
+ return "unknown";
+}
+
+function digest(value: string): string {
+ return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function boundedOutput(value: string): Pick<Record<string, unknown>, "output" | "outputBytes" | "outputTruncated" | "outputDigest"> {
+ const bytes = Buffer.byteLength(value);
+ const output = Buffer.from(value).subarray(Math.max(0, bytes - MAX_OUTPUT)).toString("utf8");
+ return { output, outputBytes: bytes, outputTruncated: bytes > MAX_OUTPUT, outputDigest: digest(value) };
+}
+
+function canonicalStatus(value: unknown, fallback: "running" | "completed" | "failed" | "cancelled" | "interrupted"): "running" | "completed" | "failed" | "cancelled" | "interrupted" {
+ const status = text(value).toLowerCase().replaceAll("_", "-");
+ if (status === "completed" || status === "success") return "completed";
+ if (status === "failed" || status === "error") return "failed";
+ if (status === "cancelled" || status === "canceled") return "cancelled";
+ if (status === "interrupted" || status === "aborted") return "interrupted";
+ if (status === "running" || status === "pending" || status === "in-progress") return "running";
+ return fallback;
+}
+
+function planStepStatus(value: unknown): "pending" | "in_progress" | "completed" | "blocked" {
+ const status = text(value)
+ .replace(/([a-z])([A-Z])/g, "$1_$2")
+ .toLowerCase()
+ .replaceAll("-", "_");
+ if (status === "in_progress" || status === "completed" || status === "blocked") return status;
+ if (status === "failed" || status === "error") return "blocked";
+ return "pending";
+}
+
+function operationFromActions(item: Record<string, unknown>): "read" | "search" | "list" | "execute" | "edit" | "unknown" {
+ const action = record(Array.isArray(item.commandActions) ? item.commandActions[0] : undefined);
+ const kind = text(action.type).toLowerCase();
+ if (kind === "read") return "read";
+ if (kind === "search") return "search";
+ if (kind === "listfiles") return "list";
+ return text(item.command) ? "execute" : "unknown";
+}
+
+function executionPayload(item: Record<string, unknown>, status: string): Record<string, unknown> {
+ const id = safeId(text(item.id), "execution");
+ const output = text(item.aggregatedOutput, text(item.output));
+ const action = record(Array.isArray(item.commandActions) ? item.commandActions[0] : undefined);
+ const target = text(action.path) || null;
+ return {
+ schema: "paperclip.tool.execution.v1",
+ executionId: id,
+ transport: text(item.type) === "mcpToolCall" ? "mcp" : text(item.type) === "dynamicToolCall" ? "dynamic" : "process",
+ operation: text(item.type).includes("ToolCall") ? "unknown" : operationFromActions(item),
+ name: text(item.tool, text(item.command)) || null,
+ target: target?.startsWith("/") || target?.split("/").includes("..") ? null : target,
+ namespace: text(item.server, text(item.namespace)) || null,
+ readOnly: typeof item.readOnlyHint === "boolean" ? item.readOnlyHint : null,
+ status,
+ durationMs: integer(item.durationMs),
+ exitCode: integer(item.exitCode),
+ progress: null,
+ ...boundedOutput(output),
+ };
+}
+
+function turnPlanPayload(params: Record<string, unknown>): Record<string, unknown> {
+ const plan = Array.isArray(params.plan) ? params.plan : [];
+ const steps = plan.slice(0, 256).flatMap((entry, index) => {
+ const step = record(entry);
+ const body = text(step.step).trim().slice(0, 4000);
+ return body
+ ? [{ stepId: `step-${index + 1}`, body, status: planStepStatus(step.status) }]
+ : [];
+ });
+ const planComplete = steps.length > 0 && steps.every((step) => step.status === "completed");
+ const planId = safeId(text(params.turnId), "turn-plan");
+ const revision = Number(params.revision);
+ return {
+ schema: "paperclip.plan.updated.v1",
+ planId,
+ revision: Number.isSafeInteger(revision) && revision > 0 ? revision : 1,
+ explanation: text(params.explanation).slice(0, 4000) || null,
+ steps,
+ complete: planComplete,
+ syncStatus: "not_applicable",
+ documentRevision: null,
+ };
+}
+
+function researchSources(item: Record<string, unknown>, researchId: string): Array<Record<string, unknown>> {
+ if (!Array.isArray(item.results)) return [];
+ return item.results.slice(0, 64).flatMap((value, index) => {
+ const result = record(value);
+ const url = text(result.url).slice(0, 8192);
+ if (!url.startsWith("http://") && !url.startsWith("https://")) return [];
+ const fallbackId = `${researchId}:source:${index + 1}`;
+ return [{
+ sourceId: safeId(text(result.ref_id, text(result.refId, fallbackId)), fallbackId),
+ title: text(result.title, url).slice(0, 4000),
+ url,
+ snippet: text(result.snippet).slice(0, 4000) || null,
+ }];
+ });
+}
+
+/** Maps qualified Codex app-server notifications to bounded canonical PRP events. */
+export function canonicalProviderEventsFromCodex(method: string, paramsValue: unknown): CanonicalProviderEvent[] {
+ const params = record(paramsValue);
+ const item = record(params.item);
+ const type = text(item.type);
+ const itemId = safeId(text(item.id, text(params.itemId)), "provider-item");
+ const completed = method === "item/completed";
+ if (method === "turn/plan/updated") {
+ const turnPlanId = safeId(text(params.turnId), "turn-plan");
+ return [{ eventType: "plan.updated", payload: turnPlanPayload(params), itemId: turnPlanId }];
+ }
+ if ((method === "item/started" || completed) && ["commandExecution", "mcpToolCall", "dynamicToolCall"].includes(type)) {
+ return [{ eventType: completed ? "tool.execution.completed" : "tool.execution.started", payload: executionPayload(item, completed ? canonicalStatus(item.status, "completed") : "running"), itemId }];
+ }
+ if (method === "item/commandExecution/outputDelta" || method === "item/mcpToolCall/progress") {
+ const delta = text(params.delta, text(params.message));
+ return [{ eventType: "tool.execution.progressed", payload: { ...executionPayload({ ...item, id: itemId, output: delta }, "running"), progress: delta.slice(0, 4000) || null }, itemId }];
+ }
+ if ((method === "item/started" || completed) && type === "webSearch") {
+ const action = record(item.action);
+ const actionType = text(action.type, "other").replace("openPage", "open_page").replace("findInPage", "find_in_page");
+ const url = text(action.url) || null;
+ return [{ eventType: completed ? "research.completed" : "research.started", payload: { schema: "paperclip.research.v1", researchId: itemId, action: actionType, status: completed ? "completed" : "running", query: text(item.query, text(action.query)) || null, url: url?.startsWith("http://") || url?.startsWith("https://") ? url : null, pattern: text(action.pattern) || null, sources: completed ? researchSources(item, itemId) : [] }, itemId }];
+ }
+ if ((method === "item/started" || completed) && (type === "collabAgentToolCall" || type === "subAgentActivity")) {
+ return [{ eventType: completed ? "delegation.completed" : "delegation.started", payload: { schema: "paperclip.delegation.v1", delegationId: itemId, action: text(item.tool, "spawnAgent").replace("spawnAgent", "spawn").replace("sendInput", "message").replace("resumeAgent", "resume").replace("closeAgent", "close"), status: completed ? "completed" : "running", children: [] }, itemId }];
+ }
+ if (method === "model/rerouted") {
+ return [{ eventType: "model.route.changed", payload: { schema: "paperclip.model.route_changed.v1", routeId: safeId(text(params.turnId), "model-route"), provider: "openai", requestedModel: text(params.fromModel, "unknown"), fromModel: text(params.fromModel) || null, effectiveModel: text(params.toModel, "unknown"), reason: text(params.reason, "provider reroute").slice(0, 4000) }, itemId }];
+ }
+ if (method === "model/verification" || method === "model/safetyBuffering/updated") {
+ return [{ eventType: "model.verification.updated", payload: { schema: "paperclip.model.verification.v1", verificationId: safeId(text(params.turnId), "model-verification"), status: params.showBufferingUi === true ? "running" : "completed", classes: Array.isArray(params.verifications) ? params.verifications.slice(0, 32) : [], buffering: params.showBufferingUi === true, summary: Array.isArray(params.reasons) ? params.reasons.join("; ").slice(0, 4000) : null }, itemId }];
+ }
+ if (method === "thread/compacted" || ((method === "item/completed" || method === "item/started") && type === "contextCompaction")) {
+ return [{ eventType: "context.compacted", payload: { schema: "paperclip.context.compacted.v1", compactionId: itemId, reason: "provider", preTokens: null, postTokens: null, sameSession: true }, itemId }];
+ }
+ if ((method === "item/started" || completed) && type === "imageView") {
+ const path = text(item.path).replaceAll("\\", "/");
+ return [{ eventType: "artifact.viewed", payload: { schema: "paperclip.artifact.viewed.v1", artifactId: itemId, reference: path.startsWith("/") || path.split("/").includes("..") ? null : path, mediaType: "image/*", title: null }, itemId }];
+ }
+ if ((method === "item/started" || completed) && type === "imageGeneration") {
+ const path = text(item.savedPath).replaceAll("\\", "/");
+ return [{ eventType: "artifact.generated", payload: { schema: "paperclip.artifact.generated.v1", artifactId: itemId, status: completed ? text(item.status, "completed") : "running", reference: path.startsWith("/") || path.split("/").includes("..") ? null : path || null, mediaType: "image/*", registered: false, transparentBackground: typeof item.transparentBackground === "boolean" ? item.transparentBackground : null, failure: text(record(item.failure).message) || null }, itemId }];
+ }
+ if ((method === "item/started" || completed) && (type === "enteredReviewMode" || type === "exitedReviewMode")) {
+ return [{ eventType: "review.mode.changed", payload: { schema: "paperclip.review.mode_changed.v1", reviewId: itemId, state: type === "enteredReviewMode" ? "entered" : "exited", scope: text(item.review) || null }, itemId }];
+ }
+ if (method === "hook/started" || method === "hook/completed") {
+ const run = record(params.run);
+ return [{ eventType: method === "hook/started" ? "hook.started" : "hook.completed", payload: { schema: "paperclip.hook.v1", hookId: safeId(text(run.id), "hook"), event: text(run.eventName, "unknown"), scope: text(run.scope, "provider"), status: method === "hook/started" ? "running" : text(run.status, "completed"), blocking: run.executionMode === "blocking", durationMs: integer(run.durationMs), summary: text(run.statusMessage) || null }, itemId: safeId(text(run.id), "hook") }];
+ }
+ if (completed && type === "agentMessage" && item.memoryCitation) {
+ const citation = record(item.memoryCitation);
+ const entries = Array.isArray(citation.entries) ? citation.entries : [];
+ return entries.slice(0, 64).map((entry, index) => ({ eventType: "memory.citation.referenced" as const, payload: { schema: "paperclip.memory.citation.v1", citationId: `${itemId}:citation:${index + 1}`, messageItemId: itemId, label: text(record(entry).label, `Memory source ${index + 1}`).slice(0, 4000), available: false, reference: null }, itemId: `${itemId}:citation:${index + 1}` }));
+ }
+ if (method === "item/autoApprovalReview/started" || method === "item/autoApprovalReview/completed") {
+ return [{ eventType: method.endsWith("started") ? "safety.review.started" : "safety.review.completed", payload: { schema: "paperclip.safety.review.v1", reviewId: safeId(text(params.reviewId), "safety-review"), targetExecutionId: text(params.targetItemId) || null, status: method.endsWith("started") ? "running" : "completed", decision: method.endsWith("started") ? "pending" : "unknown", summary: null }, itemId: safeId(text(params.reviewId), "safety-review") }];
+ }
+ if (method === "item/commandExecution/terminalInteraction") {
+ return [{ eventType: "terminal.input.sent", payload: { schema: "paperclip.terminal.input_sent.v1", executionId: safeId(text(params.itemId), "execution"), origin: "agent", inputClass: "text", byteCount: Buffer.byteLength(text(params.stdin)) }, itemId: safeId(text(params.itemId), "execution") }];
+ }
+ if ((method === "item/started" || completed) && type === "sleep") {
+ return [{ eventType: completed ? "wait.completed" : "wait.started", payload: { schema: "paperclip.wait.v1", waitId: itemId, reason: "timer", status: completed ? "completed" : "running", plannedDurationMs: integer(item.durationMs), elapsedDurationMs: completed ? integer(item.durationMs) : null }, itemId }];
+ }
+ if (["error", "warning", "guardianWarning", "deprecationNotice", "configWarning", "windows/worldWritableWarning"].includes(method)) {
+ return [{ eventType: "provider.notice.recorded", payload: { schema: "paperclip.provider.notice.v1", noticeId: safeId(`${method}:${text(params.code, "notice")}`, "provider-notice"), severity: method === "error" ? "error" : "warning", category: method.replaceAll("/", "_").slice(0, 160), scope: method.includes("config") || method.includes("windows") ? "environment" : "turn", recoverable: method !== "error", userActionable: method === "error" || method === "warning", summary: text(params.message, "Provider notice").slice(0, 4000) }, itemId }];
+ }
+ return [];
+}
+
+/** Maps documented OpenCode structured message parts. Unrecognized parts are deliberately unsupported. */
+export function canonicalProviderEventsFromOpenCodePart(partValue: unknown): CanonicalProviderEvent[] {
+ const part = record(partValue);
+ const type = text(part.type).toLowerCase();
+ const itemId = safeId(text(part.id, text(part.callID, text(part.callId))), "opencode-part");
+ const state = record(part.state);
+ const nativeStatus = text(state.status).toLowerCase().replaceAll("_", "-");
+ const status = canonicalStatus(state.status, "running");
+ if (["tool", "tool-call", "tool_call", "bash", "command"].includes(type)) {
+ const tool = canonicalOpenCodeDisplayToolName(
+ text(part.tool, text(part.name, type)),
+ text(part.callID, text(part.callId)),
+ );
+ // OpenCode places terminal tool failures in `state.error`, not `output`.
+ // Preserve the bounded provider message so a failed row is actionable.
+ const output = text(state.output, text(part.output, text(state.error)));
+ const payload = {
+ schema: "paperclip.tool.execution.v1",
+ executionId: itemId,
+ transport: type === "tool" || type.includes("tool") ? "builtin" : "process",
+ operation: /read/i.test(tool) ? "read" : /search|grep|find/i.test(tool) ? "search" : /list|glob/i.test(tool) ? "list" : /edit|write|patch/i.test(tool) ? "edit" : "execute",
+ name: tool || null,
+ target: null,
+ namespace: null,
+ readOnly: /read|search|grep|find|list|glob/i.test(tool),
+ status,
+ durationMs: integer(state.time),
+ exitCode: integer(state.exit),
+ progress: status === "running" ? text(state.title).slice(0, 4000) || null : null,
+ ...boundedOutput(output),
+ };
+ const eventType = nativeStatus === "pending"
+ ? "tool.execution.started"
+ : status === "running"
+ ? "tool.execution.progressed"
+ : "tool.execution.completed";
+ return [{ eventType, payload, itemId }];
+ }
+ if (["websearch", "web_search"].includes(type)) {
+ return [{ eventType: status === "running" ? "research.progressed" : "research.completed", payload: { schema: "paperclip.research.v1", researchId: itemId, action: "search", status: status === "interrupted" ? "cancelled" : status, query: text(part.query) || null, url: null, pattern: null, sources: [] }, itemId }];
+ }
+ if (["subtask", "task"].includes(type)) {
+ return [{ eventType: status === "running" ? "delegation.updated" : "delegation.completed", payload: { schema: "paperclip.delegation.v1", delegationId: itemId, action: "spawn", status: status === "cancelled" ? "interrupted" : status, children: [] }, itemId }];
+ }
+ if (["compaction", "context-compaction"].includes(type)) {
+ return [{ eventType: "context.compacted", payload: { schema: "paperclip.context.compacted.v1", compactionId: itemId, reason: "provider", preTokens: null, postTokens: null, sameSession: true }, itemId }];
+ }
+ return [];
+}
+
+/** Maps ACPX's bounded public runtime events; raw ACP JSON-RPC never enters PRP. */
+export function canonicalProviderEventsFromAcpxRuntimeEvent(
+ event: AcpRuntimeEventShape,
+ fallbackItemId: string,
+ turnId?: string,
+): CanonicalProviderEvent[] {
+ const runtimeType = text(record(event).type);
+ if (!["text_delta", "status", "tool_call", "plan", "error", "done"].includes(runtimeType)) {
+ return [{
+ eventType: "provider.notice.recorded",
+ payload: {
+ schema: "paperclip.provider.notice.v1",
+ noticeId: safeId(`${fallbackItemId}:${runtimeType || "unknown"}`, "acpx-unclassified-update"),
+ severity: "warning",
+ category: `unclassified_acp_${runtimeType || "unknown"}`.slice(0, 160),
+ scope: "turn",
+ recoverable: true,
+ userActionable: false,
+ summary: "The qualified ACP agent emitted an unclassified runtime update.",
+ },
+ itemId: fallbackItemId,
+ }];
+ }
+ const itemId = safeId(
+ event.type === "tool_call"
+ ? text(event.toolCallId, fallbackItemId)
+ : event.type === "plan"
+ ? text(turnId, fallbackItemId)
+ : fallbackItemId,
+ "acpx-item",
+ );
+ if (event.type === "plan") {
+ const steps = (event.entries ?? []).slice(0, 256).flatMap((entry, index) => {
+ const body = entry.content.trim().slice(0, 4000);
+ return body
+ ? [{
+ stepId: `step-${index + 1}`,
+ body,
+ status: planStepStatus(entry.status),
+ }]
+ : [];
+ });
+ const complete = steps.length > 0 && steps.every((step) => step.status === "completed");
+ return [{
+ eventType: "plan.updated",
+ payload: {
+ schema: "paperclip.plan.updated.v1",
+ planId: safeId(text(turnId, fallbackItemId), "turn-plan"),
+ revision: 1,
+ explanation: null,
+ steps,
+ complete,
+ syncStatus: "not_applicable",
+ documentRevision: null,
+ },
+ itemId,
+ }];
+ }
+ if (event.type === "tool_call") {
+ const status = canonicalStatus(event.status, "running");
+ const output = typeof event.rawOutput === "string"
+ ? event.rawOutput
+ : event.rawOutput === undefined
+ ? ""
+ : JSON.stringify(event.rawOutput);
+ const title = isGenericAcpToolName(event.title) ? "" : text(event.title).trim();
+ const mcp = acpxMcpToolIdentity(title);
+ const name = mcp?.name ?? title;
+ const operation = acpxToolOperation(event.kind, name);
+ const payload = {
+ schema: "paperclip.tool.execution.v1",
+ executionId: itemId,
+ transport: mcp ? "mcp" : "builtin",
+ operation,
+ name: name || null,
+ target: safeAcpLocation(event.locations?.[0]),
+ namespace: mcp?.namespace ?? null,
+ readOnly: ["read", "search", "list"].includes(operation),
+ status,
+ durationMs: null,
+ exitCode: null,
+ progress: status === "running" ? text(event.text).slice(0, 4000) || null : null,
+ ...boundedOutput(output),
+ };
+ const terminal = status !== "running";
+ return [{
+ eventType: terminal ? "tool.execution.completed" : event.tag === "tool_call" ? "tool.execution.started" : "tool.execution.progressed",
+ payload,
+ itemId,
+ }];
+ }
+ if (event.type === "status" && event.tag === "current_mode_update") {
+ const statusText = text(event.text);
+ const state = /review|plan/i.test(statusText) ? "entered" : "exited";
+ return [{
+ eventType: "review.mode.changed",
+ payload: {
+ schema: "paperclip.review.mode_changed.v1",
+ reviewId: itemId,
+ state,
+ scope: statusText.slice(0, 4000) || null,
+ },
+ itemId,
+ }];
+ }
+ if (event.type === "status" && event.tag && ![
+ "usage_update",
+ "available_commands_update",
+ "config_option_update",
+ "session_info_update",
+ ].includes(event.tag)) {
+ return [{
+ eventType: "provider.notice.recorded",
+ payload: {
+ schema: "paperclip.provider.notice.v1",
+ noticeId: itemId,
+ severity: "info",
+ category: `acp_${event.tag}`.slice(0, 160),
+ scope: "turn",
+ recoverable: true,
+ userActionable: false,
+ summary: text(event.text).slice(0, 4000) || "ACP provider update",
+ },
+ itemId,
+ }];
+ }
+ return [];
+}
+
+export function canonicalOpenCodeDisplayToolName(value: string, callId = ""): string {
+ let name = value.trim();
+ // Some OpenRouter models ask OpenCode for a function using a qualified
+ // `callID` while OpenCode reports the display tool as `unknown`. Recover
+ // only this documented, structured prefix; opaque provider call IDs remain
+ // opaque and continue to display as unknown.
+ if (!name || name === "unknown" || name === "tool") {
+ const qualified = /^functions[./:_-]([^:/.]+)(?::\d+)?$/i.exec(callId.trim());
+ if (qualified?.[1]) name = qualified[1];
+ }
+ // OpenCode exposes MCP tools as `<server>_<tool>`. Paperclip's semantic
+ // tools already carry the paperclip prefix, producing names such as
+ // `paperclip_paperclip_finish` in native events. Keep the transport-native
+ // name in the raw trace, while presenting the stable protocol operation.
+ while (name.startsWith("paperclip_paperclip_")) {
+ name = name.slice("paperclip_".length);
+ }
+ return name;
+}
+
+function safeAcpLocation(value: unknown): string | null {
+ const location = record(value);
+ const raw = text(location.path, text(location.uri)).replaceAll("\\", "/");
+ if (!raw || raw.startsWith("/") || raw.split("/").includes("..") || /^[a-z]+:\/\//i.test(raw)) return null;
+ return raw.slice(0, 4000);
+}
+
+export function providerFamilyCapabilities(
+ availability: Partial<Record<ProviderEventFamily, ProviderEventAvailability>>,
+): TypedEventFamilyCapability[] {
+ return PROVIDER_EVENT_FAMILIES.map((family) => ({
+ family,
+ version: 1,
+ availability: availability[family] ?? "unsupported",
+ detailLevel: availability[family] === "available" ? "structured" : "summary",
+ }));
+}
diff --git a/packages/paperclip-runner/test/protocol-contract.test.mjs b/packages/paperclip-runner/test/protocol-contract.test.mjs
index 523b79f5ac..fb63206d6a 100644
--- a/packages/paperclip-runner/test/protocol-contract.test.mjs
+++ b/packages/paperclip-runner/test/protocol-contract.test.mjs
@@ -85,6 +85,27 @@ test("accepted fixtures satisfy the complete JSON Schemas", async () => {
assert.doesNotThrow(() => assertSchemaInstance(validators.fixture, unsupported, "required-v2", false));
});
+test("provider descriptors require coherent provider, driver, and execution combinations", async () => {
+ const schemas = await loadSchemaCatalog(resolve(protocolRoot, "schemas"));
+ const validators = compileProtocolValidators(schemas);
+ const codex = {
+ provider: "codex",
+ driver: "codex_app_server",
+ model: "gpt-5.3-codex",
+ executionKind: "local_process",
+ providerVersion: "1",
+ };
+ assert.doesNotThrow(() => assertSchemaInstance(validators.providerDescriptor, codex, "codex-provider"));
+ assert.throws(
+ () => assertSchemaInstance(
+ validators.providerDescriptor,
+ { ...codex, driver: "opencode_server" },
+ "mismatched-provider",
+ ),
+ /schema_validation_failed: mismatched-provider must be accepted/,
+ );
+});
+
test("the Codex question fixture uses stable provider-neutral IDs", async () => {
const value = await fixture("questions/codex.json");
assert.doesNotThrow(() => assertCodexQuestionFixture(value));