The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add TypeScript PRP replay contracts (#12091)
Dottab2d1673b9e57
diff --git a/packages/paperclip-runner/README.md b/packages/paperclip-runner/README.mdindex efb874ce07..4fb0afce3f 100644--- a/packages/paperclip-runner/README.md+++ b/packages/paperclip-runner/README.md@@ -2,26 +2,31 @@This private workspace package contains the staged Paperclip Runner work.-This change adds only the language-neutral PRP v1 contract. It does not add a-runtime, a server adapter, or a public package export. The schemas and fixtures-are safe to review and merge before production behavior exists.+The package currently exposes only the language-neutral PRP v1 TypeScript+contract, provider-neutral structured questions and responses, deterministic+fixture validation/replay, structured-result normalization, and the session+reducer oracle. It does not add a runner process, provider transport, server+adapter, semantic-tool authorization, or production Paperclip behavior.The first provider scope is Codex. The protocol contains provider-neutral eventand semantic receipt shapes, but their presence does not authorize a tool orenable a provider.-Run the protocol gate with:+The root export is intentionally narrow. The `./testing` entry point and package+release boundary will arrive with the later package-boundary change.++Run the complete contract gate with:```shpnpm --filter @paperclipai/paperclip-runner check:protocol```-Use `generate:protocol-manifest` after a schema or fixture change. Commit the-updated manifest with its source change. Do not edit the manifest by hand.-The gate compiles every schema with AJV 2020-12. It validates accepted replay,-question, and cross-language conformance fixtures against the declared schemas.-It also proves that the unsupported required-version fixture is rejected.+Use `generate:protocol-manifest` after a schema or fixture change,+`generate:protocol-types` after a schema change, and+`generate:replay-goldens` after an intentional reducer change. Commit generated+outputs with their sources; do not edit them by hand.-The next pull request will add TypeScript validation and replay behavior. The-public root and `./testing` exports will arrive with the package boundary pull-request.+The gate compiles every schema with AJV 2020-12, validates accepted fixtures,+rejects unsupported required versions, checks generated TypeScript schema+drift, runs the TypeScript contract tests, and compares reducer snapshots and+parity summaries byte-for-byte with their checked-in golden files.diff --git a/packages/paperclip-runner/package.json b/packages/paperclip-runner/package.jsonindex c289744ee4..4cb69e29dd 100644--- a/packages/paperclip-runner/package.json+++ b/packages/paperclip-runner/package.json@@ -7,15 +7,37 @@"node": ">=24.11.0"},"type": "module",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "protocol",+ "README.md"+ ],"scripts": {- "build": "pnpm run check:protocol-manifest",- "typecheck": "node --check scripts/protocol-contract.mjs && node --check scripts/generate-protocol-manifest.mjs",- "test": "node --test test/protocol-contract.test.mjs",+ "build": "pnpm run check:protocol-manifest && pnpm run build:typescript && node scripts/generate-replay-goldens.mjs --check",+ "build:typescript": "pnpm run check:protocol-types && tsc -p tsconfig.json",+ "typecheck": "node --check scripts/protocol-contract.mjs && node --check scripts/generate-protocol-manifest.mjs && node --check scripts/generate-protocol-schema-module.mjs && node --check scripts/generate-replay-goldens.mjs && pnpm run check:protocol-types && tsc -p tsconfig.json --noEmit",+ "test": "node --test test/protocol-contract.test.mjs && vitest run","generate:protocol-manifest": "node scripts/generate-protocol-manifest.mjs","check:protocol-manifest": "node scripts/generate-protocol-manifest.mjs --check",- "check:protocol": "pnpm run typecheck && pnpm run check:protocol-manifest && pnpm test"+ "generate:protocol-types": "node scripts/generate-protocol-schema-module.mjs",+ "check:protocol-types": "node scripts/generate-protocol-schema-module.mjs --check",+ "generate:replay-goldens": "pnpm run build:typescript && node scripts/generate-replay-goldens.mjs",+ "check:replay-goldens": "pnpm run build:typescript && node scripts/generate-replay-goldens.mjs --check",+ "check:protocol": "pnpm run typecheck && pnpm run check:protocol-manifest && pnpm test && pnpm run check:replay-goldens"+ },+ "dependencies": {+ "ajv": "^8.20.0",+ "json-schema-to-ts": "^3.1.1"},"devDependencies": {- "ajv": "^8.20.0"+ "@types/node": "^24.0.0",+ "typescript": "^5.7.3",+ "vitest": "^4.1.10"}}diff --git a/packages/paperclip-runner/protocol/README.md b/packages/paperclip-runner/protocol/README.mdindex 405c2bbd34..a6aa201bef 100644--- a/packages/paperclip-runner/protocol/README.md+++ b/packages/paperclip-runner/protocol/README.md@@ -30,3 +30,8 @@ The conformance manifest records every source file and its SHA-256 digest. Runruns the same generator with `--check` to reject drift. This check also compilesthe JSON Schemas and validates every replay, question, and cross-languageconformance fixture against its declared schema.++The files in `fixtures/replay/golden/` are deterministic reducer oracles. Each+accepted replay fixture has a complete session snapshot and a compact parity+summary. `pnpm generate:replay-goldens` updates them after an intentional+reducer change; package build and CI fail when they drift.diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.snapshot.jsonnew file mode 100644index 0000000000..f9266589f9--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.snapshot.json@@ -0,0 +1,130 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Duplicate event",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_duplicate",+ "runId": "run_replay_duplicate",+ "environmentLeaseId": "lease_replay_duplicate",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_duplicate",+ "driverSessionId": "driver_replay_duplicate"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "new_per_run",+ "driver": {+ "kind": "fake",+ "version": "1.0.0"+ },+ "steer": false,+ "interrupt": true,+ "resume": true,+ "runtimeRequests": false,+ "structuredResult": true,+ "typedEvents": true+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "completed",+ "activeTurnId": null,+ "items": [+ {+ "itemId": "item_replay_duplicate",+ "kind": "assistant_message",+ "status": "completed",+ "text": "Exactly one projection."+ }+ ],+ "requests": [],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "done",+ "summary": "Duplicate delivery was idempotent.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": true,+ "criteria": [],+ "remainingWork": []+ },+ "evidence": [],+ "verification": [],+ "attentionRequests": [],+ "artifacts": []+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded",+ "reportedWorkDisposition": "done"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_duplicate_01",+ "sourceSeq": 1,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:30:00.010Z",+ "summary": "session started"+ },+ {+ "position": 2,+ "sourceEventId": "event_duplicate_02",+ "sourceSeq": 2,+ "eventType": "turn.started",+ "emittedAt": "2026-08-07T12:30:00.020Z",+ "summary": "turn started"+ },+ {+ "position": 3,+ "sourceEventId": "event_duplicate_03",+ "sourceSeq": 3,+ "eventType": "item.completed",+ "emittedAt": "2026-08-07T12:30:00.030Z",+ "itemId": "item_replay_duplicate",+ "summary": "Completed assistant_message"+ },+ {+ "position": 4,+ "sourceEventId": "event_duplicate_04",+ "sourceSeq": 4,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:30:00.040Z",+ "summary": "Duplicate delivery was idempotent."+ },+ {+ "position": 5,+ "sourceEventId": "event_duplicate_05",+ "sourceSeq": 5,+ "eventType": "turn.completed",+ "emittedAt": "2026-08-07T12:30:00.050Z",+ "summary": "turn completed"+ },+ {+ "position": 6,+ "sourceEventId": "event_duplicate_06",+ "sourceSeq": 6,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:30:00.060Z",+ "summary": "Run succeeded"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 6+ },+ "processedEventIds": [+ "event_duplicate_01",+ "event_duplicate_02",+ "event_duplicate_03",+ "event_duplicate_04",+ "event_duplicate_05",+ "event_duplicate_06"+ ],+ "duplicateEventIds": [+ "event_duplicate_03"+ ],+ "outOfOrderEventIds": [],+ "gaps": [],+ "integrity": "complete"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.summary.jsonnew file mode 100644index 0000000000..73538edbca--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/duplicate-event.summary.json@@ -0,0 +1,11 @@+{+ "runId": "run_replay_duplicate",+ "integrity": "complete",+ "timelineCount": 6,+ "duplicateEventIds": [+ "event_duplicate_03"+ ],+ "gaps": [],+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.snapshot.jsonnew file mode 100644index 0000000000..9cb7b87521--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.snapshot.json@@ -0,0 +1,143 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Failed run",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_failed",+ "runId": "run_replay_failed",+ "environmentLeaseId": "lease_replay_failed",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_failed",+ "driverSessionId": "driver_replay_failed"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "new_per_run",+ "driver": {+ "kind": "fake",+ "version": "1.0.0"+ },+ "steer": true,+ "interrupt": true,+ "resume": true,+ "runtimeRequests": true,+ "structuredResult": true,+ "typedEvents": true+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "failed",+ "activeTurnId": null,+ "items": [+ {+ "itemId": "item_failed_command",+ "kind": "command",+ "status": "failed",+ "text": ""+ }+ ],+ "requests": [],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "yielded",+ "summary": "The scripted command failed and needs a retry.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": false,+ "criteria": [],+ "remainingWork": [+ {+ "description": "Retry the failed command",+ "blocksCompletion": true+ }+ ]+ },+ "evidence": [],+ "verification": [+ {+ "commandOrCheck": "fake command",+ "status": "failed"+ }+ ],+ "attentionRequests": [],+ "artifacts": [],+ "continuation": {+ "kind": "retry",+ "summary": "Retry after correcting the command",+ "idempotencyKey": "retry_replay_failed"+ }+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "failed",+ "runTerminalState": "failed",+ "reportedWorkDisposition": "yielded"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_failed_01",+ "sourceSeq": 1,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:10:00.020Z",+ "summary": "session started"+ },+ {+ "position": 2,+ "sourceEventId": "event_failed_02",+ "sourceSeq": 2,+ "eventType": "turn.started",+ "emittedAt": "2026-08-07T12:10:00.030Z",+ "summary": "turn started"+ },+ {+ "position": 3,+ "sourceEventId": "event_failed_03",+ "sourceSeq": 3,+ "eventType": "item.failed",+ "emittedAt": "2026-08-07T12:10:00.040Z",+ "itemId": "item_failed_command",+ "summary": "Command exited with code 1"+ },+ {+ "position": 4,+ "sourceEventId": "event_failed_04",+ "sourceSeq": 4,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:10:00.050Z",+ "summary": "The scripted command failed and needs a retry."+ },+ {+ "position": 5,+ "sourceEventId": "event_failed_05",+ "sourceSeq": 5,+ "eventType": "turn.failed",+ "emittedAt": "2026-08-07T12:10:00.060Z",+ "summary": "turn failed"+ },+ {+ "position": 6,+ "sourceEventId": "event_failed_06",+ "sourceSeq": 6,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:10:00.070Z",+ "summary": "Run failed"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 6+ },+ "processedEventIds": [+ "event_failed_01",+ "event_failed_02",+ "event_failed_03",+ "event_failed_04",+ "event_failed_05",+ "event_failed_06"+ ],+ "duplicateEventIds": [],+ "outOfOrderEventIds": [],+ "gaps": [],+ "integrity": "complete"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.summary.jsonnew file mode 100644index 0000000000..318a672894--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/failed-run.summary.json@@ -0,0 +1,9 @@+{+ "runId": "run_replay_failed",+ "integrity": "complete",+ "timelineCount": 6,+ "duplicateEventIds": [],+ "gaps": [],+ "turnTerminalState": "failed",+ "runTerminalState": "failed"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.snapshot.jsonnew file mode 100644index 0000000000..55d0858ff4--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.snapshot.json@@ -0,0 +1,166 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Happy path",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_happy",+ "runId": "run_replay_happy",+ "environmentLeaseId": "lease_replay_happy",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_happy",+ "driverSessionId": "driver_replay_happy",+ "providerSessionId": "provider_replay_happy"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "new_per_run",+ "driver": {+ "kind": "fake",+ "version": "1.0.0"+ },+ "steer": true,+ "interrupt": true,+ "resume": true,+ "runtimeRequests": true,+ "structuredResult": true,+ "typedEvents": true,+ "unsupported": []+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "completed",+ "activeTurnId": null,+ "items": [+ {+ "itemId": "item_replay_message",+ "kind": "assistant_message",+ "status": "completed",+ "text": "Validated fixture. Replay complete."+ }+ ],+ "requests": [],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "done",+ "summary": "The scripted run completed successfully.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": true,+ "criteria": [],+ "remainingWork": []+ },+ "evidence": [],+ "verification": [+ {+ "commandOrCheck": "fixture replay",+ "status": "passed"+ }+ ],+ "attentionRequests": [],+ "artifacts": []+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded",+ "reportedWorkDisposition": "done",+ "workAssessmentId": "assessment_replay_happy",+ "statusDecisionId": "decision_replay_happy"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_happy_01",+ "sourceSeq": 1,+ "eventType": "runtime.phase.changed",+ "emittedAt": "2026-08-07T12:00:00.030Z",+ "summary": "Phase changed to workspace preparing"+ },+ {+ "position": 2,+ "sourceEventId": "event_happy_02",+ "sourceSeq": 2,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:00:00.040Z",+ "summary": "session started"+ },+ {+ "position": 3,+ "sourceEventId": "event_happy_03",+ "sourceSeq": 3,+ "eventType": "turn.started",+ "emittedAt": "2026-08-07T12:00:00.050Z",+ "summary": "turn started"+ },+ {+ "position": 4,+ "sourceEventId": "event_happy_04",+ "sourceSeq": 4,+ "eventType": "item.started",+ "emittedAt": "2026-08-07T12:00:00.060Z",+ "itemId": "item_replay_message",+ "summary": "Started assistant_message"+ },+ {+ "position": 5,+ "sourceEventId": "event_happy_05",+ "sourceSeq": 5,+ "eventType": "item.delta",+ "emittedAt": "2026-08-07T12:00:00.070Z",+ "itemId": "item_replay_message",+ "summary": "Validated fixture. "+ },+ {+ "position": 6,+ "sourceEventId": "event_happy_06",+ "sourceSeq": 6,+ "eventType": "item.completed",+ "emittedAt": "2026-08-07T12:00:00.080Z",+ "itemId": "item_replay_message",+ "summary": "Completed assistant_message"+ },+ {+ "position": 7,+ "sourceEventId": "event_happy_07",+ "sourceSeq": 7,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:00:00.090Z",+ "summary": "The scripted run completed successfully."+ },+ {+ "position": 8,+ "sourceEventId": "event_happy_08",+ "sourceSeq": 8,+ "eventType": "turn.completed",+ "emittedAt": "2026-08-07T12:00:00.100Z",+ "summary": "turn completed"+ },+ {+ "position": 9,+ "sourceEventId": "event_happy_09",+ "sourceSeq": 9,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:00:00.110Z",+ "summary": "Run succeeded"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 9+ },+ "processedEventIds": [+ "event_happy_01",+ "event_happy_02",+ "event_happy_03",+ "event_happy_04",+ "event_happy_05",+ "event_happy_06",+ "event_happy_07",+ "event_happy_08",+ "event_happy_09"+ ],+ "duplicateEventIds": [],+ "outOfOrderEventIds": [],+ "gaps": [],+ "integrity": "complete"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.summary.jsonnew file mode 100644index 0000000000..4d26a94a7b--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/happy-path.summary.json@@ -0,0 +1,9 @@+{+ "runId": "run_replay_happy",+ "integrity": "complete",+ "timelineCount": 9,+ "duplicateEventIds": [],+ "gaps": [],+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.snapshot.jsonnew file mode 100644index 0000000000..39b84778d4--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.snapshot.json@@ -0,0 +1,138 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Interrupted run",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_interrupted",+ "runId": "run_replay_interrupted",+ "environmentLeaseId": "lease_replay_interrupted",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_interrupted",+ "driverSessionId": "driver_replay_interrupted"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "reuse_per_issue",+ "driver": {+ "kind": "fake",+ "version": "1.0.0"+ },+ "steer": true,+ "interrupt": true,+ "resume": true,+ "runtimeRequests": true,+ "structuredResult": true,+ "typedEvents": true+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "interrupted",+ "activeTurnId": null,+ "items": [],+ "requests": [+ {+ "requestId": "request_interrupted_permission",+ "requestKind": "runtime",+ "type": "permission",+ "status": "pending",+ "prompt": "Allow the fake command?"+ }+ ],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "yielded",+ "summary": "The turn was interrupted.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": false,+ "criteria": [],+ "remainingWork": [+ {+ "description": "Resume the interrupted turn",+ "blocksCompletion": true+ }+ ]+ },+ "evidence": [],+ "verification": [],+ "attentionRequests": [],+ "artifacts": [],+ "continuation": {+ "kind": "same_agent",+ "summary": "Resume in the same normalized session",+ "idempotencyKey": "resume_replay_interrupted"+ }+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "interrupted",+ "runTerminalState": "cancelled",+ "reportedWorkDisposition": "yielded"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_interrupted_01",+ "sourceSeq": 1,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:20:00.020Z",+ "summary": "session started"+ },+ {+ "position": 2,+ "sourceEventId": "event_interrupted_02",+ "sourceSeq": 2,+ "eventType": "turn.started",+ "emittedAt": "2026-08-07T12:20:00.030Z",+ "summary": "turn started"+ },+ {+ "position": 3,+ "sourceEventId": "event_interrupted_03",+ "sourceSeq": 3,+ "eventType": "runtime_request.created",+ "emittedAt": "2026-08-07T12:20:00.040Z",+ "summary": "permission: Allow the fake command?"+ },+ {+ "position": 4,+ "sourceEventId": "event_interrupted_04",+ "sourceSeq": 4,+ "eventType": "turn.interrupted",+ "emittedAt": "2026-08-07T12:20:00.060Z",+ "summary": "turn interrupted"+ },+ {+ "position": 5,+ "sourceEventId": "event_interrupted_05",+ "sourceSeq": 5,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:20:00.070Z",+ "summary": "The turn was interrupted."+ },+ {+ "position": 6,+ "sourceEventId": "event_interrupted_06",+ "sourceSeq": 6,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:20:00.080Z",+ "summary": "Run cancelled"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 6+ },+ "processedEventIds": [+ "event_interrupted_01",+ "event_interrupted_02",+ "event_interrupted_03",+ "event_interrupted_04",+ "event_interrupted_05",+ "event_interrupted_06"+ ],+ "duplicateEventIds": [],+ "outOfOrderEventIds": [],+ "gaps": [],+ "integrity": "complete"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.summary.jsonnew file mode 100644index 0000000000..308e8f1cd0--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/interrupted-run.summary.json@@ -0,0 +1,9 @@+{+ "runId": "run_replay_interrupted",+ "integrity": "complete",+ "timelineCount": 6,+ "duplicateEventIds": [],+ "gaps": [],+ "turnTerminalState": "interrupted",+ "runTerminalState": "cancelled"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.snapshot.jsonnew file mode 100644index 0000000000..4b60a8556f--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.snapshot.json@@ -0,0 +1,127 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Source sequence gap",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_gap",+ "runId": "run_replay_gap",+ "environmentLeaseId": "lease_replay_gap",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_gap",+ "driverSessionId": "driver_replay_gap"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "new_per_run",+ "driver": {+ "kind": "fake",+ "version": "1.0.0"+ },+ "steer": false,+ "interrupt": false,+ "resume": true,+ "runtimeRequests": false,+ "structuredResult": true,+ "typedEvents": true+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "completed",+ "activeTurnId": null,+ "items": [],+ "requests": [],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "needs_review",+ "summary": "The source gap requires reconciliation.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": false,+ "criteria": [],+ "remainingWork": [+ {+ "description": "Replay missing source event",+ "blocksCompletion": true+ }+ ]+ },+ "evidence": [],+ "verification": [],+ "attentionRequests": [],+ "artifacts": []+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded",+ "reportedWorkDisposition": "needs_review"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_gap_01",+ "sourceSeq": 1,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:40:00.010Z",+ "summary": "session started"+ },+ {+ "position": 2,+ "sourceEventId": "event_gap_02",+ "sourceSeq": 2,+ "eventType": "turn.started",+ "emittedAt": "2026-08-07T12:40:00.020Z",+ "summary": "turn started"+ },+ {+ "position": 3,+ "sourceEventId": "event_gap_04",+ "sourceSeq": 4,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:40:00.040Z",+ "summary": "The source gap requires reconciliation."+ },+ {+ "position": 4,+ "sourceEventId": "event_gap_05",+ "sourceSeq": 5,+ "eventType": "turn.completed",+ "emittedAt": "2026-08-07T12:40:00.050Z",+ "summary": "turn completed"+ },+ {+ "position": 5,+ "sourceEventId": "event_gap_06",+ "sourceSeq": 6,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:40:00.060Z",+ "summary": "Run succeeded"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 6+ },+ "processedEventIds": [+ "event_gap_01",+ "event_gap_02",+ "event_gap_04",+ "event_gap_05",+ "event_gap_06"+ ],+ "duplicateEventIds": [],+ "outOfOrderEventIds": [],+ "gaps": [+ {+ "sourceKey": "runner:runner_replay",+ "expected": 3,+ "received": 4,+ "missingCount": 1,+ "missing": [+ 3+ ],+ "truncated": false+ }+ ],+ "integrity": "gap_detected"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.summary.jsonnew file mode 100644index 0000000000..3f86623bd6--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/source-gap.summary.json@@ -0,0 +1,20 @@+{+ "runId": "run_replay_gap",+ "integrity": "gap_detected",+ "timelineCount": 5,+ "duplicateEventIds": [],+ "gaps": [+ {+ "sourceKey": "runner:runner_replay",+ "expected": 3,+ "received": 4,+ "missingCount": 1,+ "missing": [+ 3+ ],+ "truncated": false+ }+ ],+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.snapshot.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.snapshot.jsonnew file mode 100644index 0000000000..cdca456aa7--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.snapshot.json@@ -0,0 +1,111 @@+{+ "schema": "paperclip.prp.session-snapshot.v1",+ "fixtureName": "Unknown optional fields",+ "identity": {+ "schema": "paperclip.prp.identity.v1",+ "companyId": "company_replay",+ "issueId": "issue_replay_future",+ "runId": "run_replay_future",+ "environmentLeaseId": "lease_replay_future",+ "runnerInstanceId": "runner_replay",+ "normalizedSessionId": "session_replay_future",+ "driverSessionId": "driver_replay_future",+ "futureIdentityLabel": "preserved"+ },+ "capabilities": {+ "schema": "paperclip.prp.capabilities.v1",+ "sessionReusePolicy": "new_per_run",+ "driver": {+ "kind": "fake",+ "version": "1.1.0",+ "futureDriverField": true+ },+ "steer": true,+ "interrupt": true,+ "resume": true,+ "runtimeRequests": true,+ "structuredResult": true,+ "typedEvents": true,+ "futureCapability": {+ "mode": "optional"+ }+ },+ "runPhase": "terminal",+ "sessionState": "running",+ "turnState": "completed",+ "activeTurnId": null,+ "items": [],+ "requests": [],+ "proposedResult": {+ "schema": "paperclip.run_result.v1",+ "reportedWorkDisposition": "done",+ "summary": "Unknown optional fields did not change the v1 projection.",+ "completionClaim": {+ "contractRevision": "replay-contract-v1",+ "objectiveSatisfied": true,+ "criteria": [],+ "remainingWork": []+ },+ "evidence": [],+ "verification": [],+ "attentionRequests": [],+ "artifacts": [],+ "futureResultAnnotation": {+ "safe": true+ }+ },+ "terminal": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded",+ "reportedWorkDisposition": "done",+ "futureTerminalReason": "optional"+ },+ "timeline": [+ {+ "position": 1,+ "sourceEventId": "event_future_01",+ "sourceSeq": 1,+ "eventType": "session.started",+ "emittedAt": "2026-08-07T12:50:00.010Z",+ "summary": "session started"+ },+ {+ "position": 2,+ "sourceEventId": "event_future_02",+ "sourceSeq": 2,+ "eventType": "run.result.proposed",+ "emittedAt": "2026-08-07T12:50:00.020Z",+ "summary": "Unknown optional fields did not change the v1 projection."+ },+ {+ "position": 3,+ "sourceEventId": "event_future_03",+ "sourceSeq": 3,+ "eventType": "turn.completed",+ "emittedAt": "2026-08-07T12:50:00.030Z",+ "summary": "turn completed"+ },+ {+ "position": 4,+ "sourceEventId": "event_future_04",+ "sourceSeq": 4,+ "eventType": "run.terminal",+ "emittedAt": "2026-08-07T12:50:00.040Z",+ "summary": "Run succeeded"+ }+ ],+ "sourceCursors": {+ "runner:runner_replay": 4+ },+ "processedEventIds": [+ "event_future_01",+ "event_future_02",+ "event_future_03",+ "event_future_04"+ ],+ "duplicateEventIds": [],+ "outOfOrderEventIds": [],+ "gaps": [],+ "integrity": "complete"+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.summary.json b/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.summary.jsonnew file mode 100644index 0000000000..24bebe0fbc--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/golden/unknown-optional-fields.summary.json@@ -0,0 +1,9 @@+{+ "runId": "run_replay_future",+ "integrity": "complete",+ "timelineCount": 4,+ "duplicateEventIds": [],+ "gaps": [],+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded"+}diff --git a/packages/paperclip-runner/protocol/manifest.json b/packages/paperclip-runner/protocol/manifest.jsonindex 7aded07243..96a0361d4d 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": "b930af4a187c26312b4fff66813498b95332cb4e972f8b9282cdceafdf0de32c"+ "sha256": "d69ac4acfd9cd265f9dcb6a6580e949a67a50347093d0a7c12c2000a2da6d482"},{"path": "schemas/fixture.schema.json",@@ -139,6 +139,78 @@"expectation": "accept","compatibilityCase": "canonical"},+ {+ "path": "fixtures/replay/golden/duplicate-event.snapshot.json",+ "sha256": "24a6c221f9d46824128cde009b277dae2ea8672a608cf7fa2d7e4a714e38bc92",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/duplicate-event.summary.json",+ "sha256": "dcbb2dae5810649cc59c6c0fe136e1033131d9510ebcbcc5f3435bfa998b95c9",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/failed-run.snapshot.json",+ "sha256": "a2bb468e3ca94b092a86afb8a57d2d05e0ce3cd6e9f87927dea81aef5aa32dd1",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/failed-run.summary.json",+ "sha256": "d7ac19d40b5d1d6106e2232cd2436ba1c4232bc6daa8a71957f12300ba851f65",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/happy-path.snapshot.json",+ "sha256": "037c114df8f205a13fa9070b07e6f9707218b8249bd196925246b054a7690853",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/happy-path.summary.json",+ "sha256": "00d2a033518c7b3f51ecb10aa64f7456922f6b3f930d853b3db35e72eaf55325",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/interrupted-run.snapshot.json",+ "sha256": "dc216831c437cc8fd2c37cee6f40f342767b21e01a511f2235a443be0d0b7b0c",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/interrupted-run.summary.json",+ "sha256": "753f226607b2d97301736d7f54b281ab7157397f3f32015c644787d370526332",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/source-gap.snapshot.json",+ "sha256": "7db7f25e423a721e60adfcdfee02db6d5e6fcd4a644ee180f5e29810ebbc0d78",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/source-gap.summary.json",+ "sha256": "861d0ee3fafe13bf8bf0fb71b7c1ef9a62cb26efba4dc8db889f36d27a14a813",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/unknown-optional-fields.snapshot.json",+ "sha256": "cf5b13a4b8d7ae73d1632e0539ec50d2ebcee8fbb6a2f33b28db7ff786fa90ff",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },+ {+ "path": "fixtures/replay/golden/unknown-optional-fields.summary.json",+ "sha256": "7d983bcad0439b7884e70d07f8070b53ed594fba2da3e8ac6998570e238e84dc",+ "expectation": "accept",+ "compatibilityCase": "deterministic-replay-oracle"+ },{"path": "fixtures/replay/happy-path.json","sha256": "dfe0aeb4e7a217f8d375afe6e6d1ab0151bb8e81921b07ae0aaa6c4d0b8f8a1d",diff --git a/packages/paperclip-runner/protocol/schemas/event.schema.json b/packages/paperclip-runner/protocol/schemas/event.schema.jsonindex 332e70b396..355e1f6477 100644--- a/packages/paperclip-runner/protocol/schemas/event.schema.json+++ b/packages/paperclip-runner/protocol/schemas/event.schema.json@@ -19,7 +19,7 @@"properties": {"schema": { "const": "paperclip.prp.event.v1" },"sourceEventId": { "type": "string", "minLength": 1, "maxLength": 160 },- "sourceSeq": { "type": "integer", "minimum": 1 },+ "sourceSeq": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },"sourceInstanceId": { "type": "string", "minLength": 1, "maxLength": 160 },"sourceKind": { "enum": ["runner", "control_plane"] },"runId": { "type": "string", "minLength": 1, "maxLength": 160 },diff --git a/packages/paperclip-runner/scripts/generate-protocol-manifest.mjs b/packages/paperclip-runner/scripts/generate-protocol-manifest.mjsindex 3bc3d59462..6535eb07fc 100644--- a/packages/paperclip-runner/scripts/generate-protocol-manifest.mjs+++ b/packages/paperclip-runner/scripts/generate-protocol-manifest.mjs@@ -22,7 +22,8 @@ const protocolRoot = resolve(packageRoot, "protocol");const schemaDirectory = resolve(protocolRoot, "schemas");const fixtureDirectory = resolve(protocolRoot, "fixtures");const outputPath = resolve(protocolRoot, "manifest.json");-const expectedRejectedFixture = "fixtures/replay/unsupported-required-version.json";+const expectedRejectedFixture =+ "fixtures/replay/unsupported-required-version.json";export async function buildProtocolManifest() {const schemas = await loadSchemaCatalog(schemaDirectory);@@ -38,7 +39,9 @@ export async function buildProtocolManifest() {let expectation = "accept";let compatibilityCase = "canonical";- if (relativePath.startsWith("fixtures/replay/")) {+ if (relativePath.startsWith("fixtures/replay/golden/")) {+ compatibilityCase = "deterministic-replay-oracle";+ } else if (relativePath.startsWith("fixtures/replay/")) {if (relativePath === expectedRejectedFixture) {expectation = "reject";compatibilityCase = "unknown-required-version";@@ -46,7 +49,10 @@ export async function buildProtocolManifest() {assertReplayFixtureCompatibility(value);throw new Error(`${relativePath} did not fail closed`);} catch (error) {- if (!String(error.message).startsWith("unsupported_required_version:")) throw error;+ if (+ !String(error.message).startsWith("unsupported_required_version:")+ )+ throw error;}assertSchemaInstance(validators.fixture, value, relativePath, false);} else {@@ -58,7 +64,11 @@ export async function buildProtocolManifest() {}} else if (relativePath === "fixtures/questions/codex.json") {assertCodexQuestionFixture(value);- assertSchemaInstance(validators.questionAdapterFixture, value, relativePath);+ assertSchemaInstance(+ validators.questionAdapterFixture,+ value,+ relativePath,+ );compatibilityCase = "codex-structured-input";} else if (relativePath === "fixtures/conformance-minimal-run.json") {assertSchemaInstance(validators.conformanceFixture, value, relativePath);@@ -100,10 +110,14 @@ async function main() {if (process.argv.includes("--check")) {const current = await readFile(outputPath, "utf8").catch(() => "");if (current !== encoded) {- process.stderr.write("The generated PRP contract manifest is stale. Run pnpm generate:protocol-manifest.\n");+ process.stderr.write(+ "The generated PRP contract manifest is stale. Run pnpm generate:protocol-manifest.\n",+ );process.exitCode = 1;} else {- process.stdout.write("The generated PRP contract manifest matches its sources.\n");+ process.stdout.write(+ "The generated PRP contract manifest matches its sources.\n",+ );}} else {await writeFile(outputPath, encoded);@@ -111,4 +125,5 @@ async function main() {}}-if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) await main();+if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url))+ await main();diff --git a/packages/paperclip-runner/scripts/generate-protocol-schema-module.mjs b/packages/paperclip-runner/scripts/generate-protocol-schema-module.mjsnew file mode 100644index 0000000000..210870ec00--- /dev/null+++ b/packages/paperclip-runner/scripts/generate-protocol-schema-module.mjs@@ -0,0 +1,70 @@+import { mkdir, readFile, writeFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const schemaDirectory = resolve(packageRoot, "protocol/schemas");+const outputPath = resolve(+ packageRoot,+ "src/protocol/generated/schema-bundle.ts",+);+const schemaNames = [+ "identity",+ "capabilities",+ "command",+ "provider-descriptor",+ "provider-event",+ "workspace-diff",+ "workspace-file-reference",+ "semantic-tool",+ "usage",+ "stop-reason",+ "terminal",+ "question-set",+ "question-response",+ "question-adapter-fixture",+ "request",+ "result",+ "event",+ "fixture",+];++const schemas = await Promise.all(+ schemaNames.map(async (name) => ({+ name,+ value: JSON.parse(+ await readFile(resolve(schemaDirectory, `${name}.schema.json`), "utf8"),+ ),+ })),+);++const identifier = (name) =>+ name.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());+const declarations = schemas+ .map(+ ({ name, value }) =>+ `export const ${identifier(name)}Schema = ${JSON.stringify(value, null, 2)} as const;`,+ )+ .join("\n\n");+const bundle = schemaNames+ .map((name) => ` ${JSON.stringify(name)}: ${identifier(name)}Schema,`)+ .join("\n");+const generated = `// Generated by scripts/generate-protocol-schema-module.mjs. Do not edit.\n\n${declarations}\n\nexport const prpSchemaBundle = {\n${bundle}\n} as const;\n`;++if (process.argv.includes("--check")) {+ const current = await readFile(outputPath, "utf8").catch(() => "");+ if (current !== generated) {+ process.stderr.write(+ "Generated PRP schema module is stale. Run pnpm generate:protocol-types.\n",+ );+ process.exitCode = 1;+ } else {+ process.stdout.write(+ "Generated PRP schema module matches the JSON Schema sources.\n",+ );+ }+} else {+ await mkdir(dirname(outputPath), { recursive: true });+ await writeFile(outputPath, generated);+ process.stdout.write("Generated PRP schema module.\n");+}diff --git a/packages/paperclip-runner/scripts/generate-replay-goldens.mjs b/packages/paperclip-runner/scripts/generate-replay-goldens.mjsnew file mode 100644index 0000000000..e2699d0825--- /dev/null+++ b/packages/paperclip-runner/scripts/generate-replay-goldens.mjs@@ -0,0 +1,68 @@+import { mkdir, readFile, writeFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import {+ parsePrpFixtureText,+ replayParitySummary,+ reducePrpFixture,+} from "../dist/index.js";++const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const fixtureDirectory = resolve(packageRoot, "protocol/fixtures/replay");+const goldenDirectory = resolve(fixtureDirectory, "golden");+const fixtureNames = [+ "happy-path",+ "failed-run",+ "interrupted-run",+ "duplicate-event",+ "source-gap",+ "unknown-optional-fields",+];+const check = process.argv.includes("--check");+const stale = [];++await mkdir(goldenDirectory, { recursive: true });+for (const fixtureName of fixtureNames) {+ const source = await readFile(+ resolve(fixtureDirectory, `${fixtureName}.json`),+ "utf8",+ );+ const validation = parsePrpFixtureText(source);+ if (!validation.ok) {+ throw new Error(+ `${fixtureName}.json failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`,+ );+ }+ const snapshot = reducePrpFixture(validation.fixture);+ const outputs = [+ ["snapshot", snapshot],+ ["summary", replayParitySummary(snapshot)],+ ];+ for (const [kind, value] of outputs) {+ const path = resolve(goldenDirectory, `${fixtureName}.${kind}.json`);+ const generated = `${JSON.stringify(value, null, 2)}\n`;+ if (check) {+ if ((await readFile(path, "utf8").catch(() => "")) !== generated) {+ stale.push(`${fixtureName}.${kind}.json`);+ }+ } else {+ await writeFile(path, generated);+ }+ }+}++if (stale.length > 0) {+ process.stderr.write(+ `Replay golden files are stale:\n- ${stale.join("\n- ")}\n`,+ );+ process.exitCode = 1;+} else if (check) {+ process.stdout.write(+ "Replay golden snapshots and parity summaries are current.\n",+ );+} else {+ process.stdout.write(+ "Generated Replay golden snapshots and parity summaries.\n",+ );+}diff --git a/packages/paperclip-runner/src/contracts/completion-result.test.ts b/packages/paperclip-runner/src/contracts/completion-result.test.tsnew file mode 100644index 0000000000..321f0789bb--- /dev/null+++ b/packages/paperclip-runner/src/contracts/completion-result.test.ts@@ -0,0 +1,107 @@+import Ajv2020 from "ajv/dist/2020.js";+import { describe, expect, it } from "vitest";+import {+ PRP_COMPLETION_RESULT_OUTPUT_SCHEMA,+ PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA,+} from "./completion-result.js";++const baseResult = {+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "done",+ summary: "Completed the requested work.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ { criterionId: "objective", status: "satisfied", evidenceRefs: [] },+ ],+ remainingWork: [],+ },+ evidence: [],+ verification: [],+ attentionRequests: [],+ artifacts: [],+};++describe("provider-neutral completion result schema", () => {+ const validate = new Ajv2020({ allErrors: true, strict: false }).compile(+ PRP_COMPLETION_RESULT_OUTPUT_SCHEMA,+ );++ it("allows done with no verification and no actionable attention", () => {+ expect(validate(structuredClone(baseResult))).toBe(true);+ });++ it("allows provider tool callers to omit the constant schema discriminator", () => {+ const providerValidate = new Ajv2020({+ allErrors: true,+ strict: false,+ }).compile(PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA);+ const providerResult = structuredClone(baseResult) as Record<+ string,+ unknown+ >;+ delete providerResult.schema;+ expect(providerValidate(providerResult)).toBe(true);+ });++ it("admits known smaller-model aliases at the provider boundary for canonical normalization", () => {+ const providerValidate = new Ajv2020({+ allErrors: true,+ strict: false,+ }).compile(PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA);+ const providerResult = structuredClone(baseResult);+ providerResult.schema = "paperclip_paperclip_finish";+ providerResult.reportedWorkDisposition = "completed";+ providerResult.completionClaim.criteria[0]!.status = "passed";+ providerResult.verification = [+ { commandOrCheck: "model check", status: "pass" } as never,+ ];+ expect(providerValidate(providerResult)).toBe(true);+ });++ it("requires a reason code for verification that was not run", () => {+ const result = structuredClone(baseResult);+ result.verification = [+ { commandOrCheck: "Run tests", status: "not_run" } as never,+ ];+ expect(validate(result)).toBe(false);++ result.verification = [+ {+ commandOrCheck: "Run tests",+ status: "not_run",+ reasonCode: "tool_unavailable",+ } as never,+ ];+ expect(validate(result)).toBe(true);+ });++ it("requires needs_review for actionable attention", () => {+ const result = structuredClone(baseResult);+ result.attentionRequests = [+ {+ kind: "review",+ summary: "Confirm the external result.",+ ownerClass: "human",+ } as never,+ ];+ expect(validate(result)).toBe(false);++ result.reportedWorkDisposition = "needs_review";+ expect(validate(result)).toBe(true);+ });++ it("requires agent-owned attention to identify its target agent", () => {+ const result = structuredClone(baseResult);+ result.reportedWorkDisposition = "needs_review";+ result.attentionRequests = [+ {+ kind: "agent_handoff",+ summary: "Ask the deployment agent to continue.",+ ownerClass: "agent",+ } as never,+ ];+ expect(validate(result)).toBe(false);+ });+});diff --git a/packages/paperclip-runner/src/contracts/completion-result.ts b/packages/paperclip-runner/src/contracts/completion-result.tsnew file mode 100644index 0000000000..11be498be4--- /dev/null+++ b/packages/paperclip-runner/src/contracts/completion-result.ts@@ -0,0 +1,387 @@+/** Provider-neutral semantic completion tools and their strict model-facing schemas. */+export const PRP_COMPLETION_TOOL_NAME = "paperclip_finish" as const;+export const PRP_BLOCK_TOOL_NAME = "paperclip_block" as const;+export const PRP_SEMANTIC_TOOL_NAMES = [+ PRP_COMPLETION_TOOL_NAME,+ PRP_BLOCK_TOOL_NAME,+] as const;++export const PRP_VERIFICATION_REASON_CODES = [+ "environment_unavailable",+ "tool_unavailable",+ "dependency_missing",+ "permission_denied",+ "credential_missing",+ "policy_restricted",+ "external_service_unavailable",+ "budget_exhausted",+ "other",+] as const;++export const PRP_ACTIONABLE_ATTENTION_KINDS = [+ "review",+ "human_input",+ "approval",+ "credential",+ "external_action",+ "agent_handoff",+] as const;++export const PRP_ATTENTION_OWNER_CLASSES = [+ "human",+ "agent",+ "external_system",+] as const;++const completionClaimSchema = {+ type: "object",+ additionalProperties: false,+ required: [+ "contractRevision",+ "objectiveSatisfied",+ "criteria",+ "remainingWork",+ ],+ properties: {+ contractRevision: { type: "string", minLength: 1 },+ objectiveSatisfied: { type: "boolean" },+ criteria: {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["criterionId", "status", "evidenceRefs"],+ properties: {+ criterionId: { type: "string", minLength: 1 },+ status: { enum: ["satisfied", "not_satisfied", "unknown"] },+ evidenceRefs: { type: "array", items: { type: "string" } },+ },+ },+ },+ remainingWork: {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["description", "blocksCompletion"],+ properties: {+ description: { type: "string", minLength: 1 },+ blocksCompletion: { type: "boolean" },+ },+ },+ },+ },+} as const;++const evidenceSchema = {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["ref"],+ properties: { ref: { type: "string", minLength: 1 } },+ },+} as const;++const verificationSchema = {+ type: "array",+ description:+ "Checks used to verify the work. Use failed only when the check actually ran and found a defect in the work. If a check could not run or complete because the environment, tool, dependency, permission, credential, policy, external service, or budget was unavailable, use not_run with reasonCode even when the attempted command exited non-zero.",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["commandOrCheck", "status"],+ properties: {+ commandOrCheck: { type: "string", minLength: 1 },+ status: {+ enum: ["passed", "failed", "not_run"],+ description:+ "passed: the check ran and succeeded. failed: the check ran to a meaningful verdict and found the work incorrect. not_run: the check had no meaningful verdict because it was not attempted or an environment/tool/dependency/permission/credential/policy/service/budget limitation prevented it from completing; command launch or setup failures are not_run.",+ },+ reasonCode: {+ enum: [...PRP_VERIFICATION_REASON_CODES],+ description:+ "Required for not_run; identify why the check had no meaningful verdict.",+ },+ detail: { type: "string" },+ artifactRef: { type: "string", minLength: 1 },+ },+ allOf: [+ {+ if: {+ properties: { status: { const: "not_run" } },+ required: ["status"],+ },+ then: { required: ["reasonCode"] },+ },+ ],+ },+} as const;++const attentionRequestsSchema = {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["kind", "summary", "ownerClass"],+ properties: {+ kind: { enum: [...PRP_ACTIONABLE_ATTENTION_KINDS] },+ summary: { type: "string", minLength: 1 },+ ownerClass: { enum: [...PRP_ATTENTION_OWNER_CLASSES] },+ targetAgentId: { type: "string", minLength: 1 },+ },+ allOf: [+ {+ if: {+ properties: { ownerClass: { const: "agent" } },+ required: ["ownerClass"],+ },+ then: { required: ["targetAgentId"] },+ },+ ],+ },+} as const;++const artifactsSchema = {+ type: "array",+ items: {+ type: "object",+ additionalProperties: false,+ required: ["kind", "ref"],+ properties: {+ kind: { type: "string", minLength: 1 },+ ref: { type: "string", minLength: 1 },+ },+ },+} as const;++const commonResultProperties = {+ schema: { type: "string", const: "paperclip.run_result.v1" },+ summary: { type: "string", minLength: 1 },+ completionClaim: completionClaimSchema,+ evidence: evidenceSchema,+ verification: verificationSchema,+ attentionRequests: attentionRequestsSchema,+ artifacts: artifactsSchema,+} as const;++export const PRP_COMPLETION_RESULT_OUTPUT_SCHEMA = {+ type: "object",+ additionalProperties: false,+ required: [+ "reportedWorkDisposition",+ "summary",+ "completionClaim",+ "evidence",+ "verification",+ "attentionRequests",+ "artifacts",+ ],+ properties: {+ ...commonResultProperties,+ reportedWorkDisposition: { enum: ["done", "needs_review"] },+ },+ allOf: [+ {+ if: {+ properties: { reportedWorkDisposition: { const: "done" } },+ required: ["reportedWorkDisposition"],+ },+ then: { properties: { attentionRequests: { maxItems: 0 } } },+ },+ {+ if: {+ properties: { reportedWorkDisposition: { const: "needs_review" } },+ required: ["reportedWorkDisposition"],+ },+ then: { properties: { attentionRequests: { minItems: 1 } } },+ },+ ],+} as const;++export const PRP_BLOCK_RESULT_OUTPUT_SCHEMA = {+ type: "object",+ additionalProperties: false,+ required: [+ "reportedWorkDisposition",+ "summary",+ "completionClaim",+ "evidence",+ "verification",+ "attentionRequests",+ "artifacts",+ "blocker",+ ],+ properties: {+ ...commonResultProperties,+ reportedWorkDisposition: { type: "string", const: "blocked" },+ attentionRequests: {+ type: "array",+ maxItems: 0,+ items: attentionRequestsSchema.items,+ },+ blocker: {+ type: "object",+ additionalProperties: false,+ required: ["reasonCode", "owner", "unblockAction", "scope"],+ properties: {+ reasonCode: { type: "string", minLength: 1 },+ owner: {+ type: "object",+ additionalProperties: false,+ required: ["kind", "name"],+ properties: {+ kind: { enum: ["agent", "user", "system", "external"] },+ name: { type: "string", minLength: 1 },+ },+ },+ unblockAction: { type: "string", minLength: 1 },+ scope: { enum: ["current_track", "task_wide"] },+ },+ },+ },+} as const;++const providerVerificationCompatibilitySchema = {+ type: "array",+ description:+ "Checks used to verify the work. Use failed only when the check actually ran and found a defect in the work. If a check could not run or complete because the environment, tool, dependency, permission, credential, policy, external service, or budget was unavailable, use not_run with reasonCode even when the attempted command exited non-zero.",+ items: {+ type: "object",+ additionalProperties: true,+ required: ["status"],+ properties: {+ commandOrCheck: { type: "string", minLength: 1 },+ command: { type: "string", minLength: 1 },+ status: {+ enum: [+ "passed",+ "failed",+ "not_run",+ "blocked",+ "skipped",+ "pass",+ "success",+ "succeeded",+ "fail",+ ],+ description:+ "passed: the check ran and succeeded. failed: the check ran to a meaningful verdict and found the work incorrect. not_run: no meaningful verdict because the check was not attempted or could not complete. Prefer not_run over legacy blocked/skipped, and include reasonCode for any unavailable check.",+ },+ reasonCode: {+ enum: [...PRP_VERIFICATION_REASON_CODES],+ description:+ "Required for not_run; identify why the check had no meaningful verdict.",+ },+ detail: { type: "string" },+ result: { type: "string" },+ cwd: { type: "string" },+ artifactRef: { type: "string", minLength: 1 },+ },+ },+} as const;++const providerCompletionClaimCompatibilitySchema = {+ ...completionClaimSchema,+ properties: {+ ...completionClaimSchema.properties,+ criteria: {+ ...completionClaimSchema.properties.criteria,+ items: {+ ...completionClaimSchema.properties.criteria.items,+ properties: {+ ...completionClaimSchema.properties.criteria.items.properties,+ status: {+ enum: [+ "satisfied",+ "not_satisfied",+ "unknown",+ "pass",+ "passed",+ "complete",+ "completed",+ "fail",+ "failed",+ "incomplete",+ ],+ description:+ "Use satisfied when the criterion is met, not_satisfied when it is not met, or unknown when no verdict is available. Common provider aliases are accepted and normalized.",+ },+ },+ },+ },+ },+} as const;++const providerCommonResultProperties = {+ ...commonResultProperties,+ schema: {+ enum: [+ "paperclip.run_result.v1",+ "paperclip_finish",+ "paperclip_paperclip_finish",+ "paperclip_finish.v1",+ ],+ },+ completionClaim: providerCompletionClaimCompatibilitySchema,+} as const;++const providerAttentionCompatibilitySchema = {+ type: "array",+ items: {+ type: "object",+ additionalProperties: true,+ required: ["kind", "summary"],+ properties: {+ kind: { type: "string", minLength: 1 },+ summary: { type: "string", minLength: 1 },+ ownerClass: { enum: [...PRP_ATTENTION_OWNER_CLASSES] },+ targetAgentId: { type: "string", minLength: 1 },+ requestedCapability: { type: "string", minLength: 1 },+ requiredAuthority: { type: "string", minLength: 1 },+ target: { type: "object", additionalProperties: true },+ },+ },+} as const;++/**+ * Provider-facing compatibility schemas. Canonical PRP validation still uses+ * the strict schemas above after legacy aliases have been normalized.+ */+export const PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA = {+ type: "object",+ additionalProperties: true,+ required: [+ "reportedWorkDisposition",+ "summary",+ "completionClaim",+ "evidence",+ "verification",+ ],+ properties: {+ ...providerCommonResultProperties,+ reportedWorkDisposition: { enum: ["done", "needs_review", "completed"] },+ verification: providerVerificationCompatibilitySchema,+ attentionRequests: providerAttentionCompatibilitySchema,+ },+} as const;++export const PRP_BLOCK_RESULT_PROVIDER_INPUT_SCHEMA = {+ type: "object",+ additionalProperties: true,+ required: [+ "reportedWorkDisposition",+ "summary",+ "completionClaim",+ "evidence",+ "verification",+ "blocker",+ ],+ properties: {+ ...providerCommonResultProperties,+ reportedWorkDisposition: { type: "string", const: "blocked" },+ verification: providerVerificationCompatibilitySchema,+ attentionRequests: providerAttentionCompatibilitySchema,+ blocker: PRP_BLOCK_RESULT_OUTPUT_SCHEMA.properties.blocker,+ },+} as const;diff --git a/packages/paperclip-runner/src/contracts/question-set.test.ts b/packages/paperclip-runner/src/contracts/question-set.test.tsnew file mode 100644index 0000000000..04644da0aa--- /dev/null+++ b/packages/paperclip-runner/src/contracts/question-set.test.ts@@ -0,0 +1,108 @@+import { describe, expect, it } from "vitest";++import {+ PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ PAPERCLIP_QUESTION_SET_SCHEMA,+ parsePaperclipQuestionResponse,+ parsePaperclipQuestionSet,+ type PaperclipQuestionSet,+} from "./question-set.js";++const questionSet: PaperclipQuestionSet = {+ schema: PAPERCLIP_QUESTION_SET_SCHEMA,+ title: "Release input",+ questions: [+ {+ id: "environment",+ prompt: "Where should we deploy?",+ required: true,+ answerMode: "single_select",+ options: [+ { id: "staging", label: "Staging" },+ { id: "production", label: "Production" },+ ],+ customAnswer: { enabled: true, label: "Other" },+ },+ {+ id: "replicas",+ prompt: "How many replicas?",+ required: true,+ answerMode: "text",+ textValidation: { inputType: "integer", minimum: 1, maximum: 20 },+ },+ ],+};++describe("Paperclip question-set contract", () => {+ it("round-trips the portable presentation model", () => {+ expect(parsePaperclipQuestionSet(questionSet)).toEqual(questionSet);+ expect(+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { selectedOptionIds: ["staging"] },+ replicas: { text: "3" },+ },+ }),+ ).toEqual({+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { selectedOptionIds: ["staging"] },+ replicas: { text: "3" },+ },+ });+ });++ it("rejects missing, unknown, and provider-shaped answers", () => {+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { selectedOptionIds: ["unknown"] },+ replicas: { text: "3" },+ },+ }),+ ).toThrow(/unknown option/);+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: { environment: { selectedOptionIds: ["staging"] } },+ }),+ ).toThrow(/replicas.*required/);+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ answers: { environment: { answers: ["Staging"] } },+ }),+ ).toThrow(/paperclip.question_response.v1/);+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { answers: ["Staging"] },+ replicas: { text: "3" },+ },+ }),+ ).toThrow(/canonical response contract/);+ });++ it("applies typed numeric validation before an adapter sees the answer", () => {+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { customText: "Canary" },+ replicas: { text: "3.5" },+ },+ }),+ ).toThrow(/valid integer/);+ expect(() =>+ parsePaperclipQuestionResponse(questionSet, {+ schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA,+ answers: {+ environment: { customText: "Canary" },+ replicas: { text: "21" },+ },+ }),+ ).toThrow(/at most 20/);+ });+});diff --git a/packages/paperclip-runner/src/contracts/question-set.ts b/packages/paperclip-runner/src/contracts/question-set.tsnew file mode 100644index 0000000000..a0a0323fea--- /dev/null+++ b/packages/paperclip-runner/src/contracts/question-set.ts@@ -0,0 +1,664 @@+export const PAPERCLIP_QUESTION_SET_SCHEMA =+ "paperclip.question_set.v1" as const;+export const PAPERCLIP_QUESTION_RESPONSE_SCHEMA =+ "paperclip.question_response.v1" as const;+export const PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2 =+ "paperclip.runtime_request.v2" as const;++export type PaperclipQuestionAnswerMode =+ "single_select" | "multi_select" | "text";++export interface PaperclipQuestionOption {+ id: string;+ label: string;+ description?: string;+}++export interface PaperclipQuestionCustomAnswer {+ enabled: true;+ label?: string;+ placeholder?: string;+}++export interface PaperclipQuestionTextValidation {+ minLength?: number;+ maxLength?: number;+ pattern?: string;+ inputType?: "text" | "number" | "integer";+ minimum?: number;+ maximum?: number;+}++export interface PaperclipQuestion {+ id: string;+ header?: string;+ prompt: string;+ helpText?: string;+ required: boolean;+ answerMode: PaperclipQuestionAnswerMode;+ options?: PaperclipQuestionOption[];+ customAnswer?: PaperclipQuestionCustomAnswer;+ textValidation?: PaperclipQuestionTextValidation;+}++export interface PaperclipQuestionSet {+ schema: typeof PAPERCLIP_QUESTION_SET_SCHEMA;+ title?: string;+ description?: string;+ submitLabel?: string;+ questions: PaperclipQuestion[];+}++export interface PaperclipQuestionAnswer {+ selectedOptionIds?: string[];+ text?: string;+ customText?: string;+}++export interface PaperclipQuestionResponse {+ schema: typeof PAPERCLIP_QUESTION_RESPONSE_SCHEMA;+ answers: Record<string, PaperclipQuestionAnswer>;+}++export interface PaperclipRuntimeRequestOrigin {+ adapter: string;+ provider?: string;+ method?: string;+}++export interface PaperclipRuntimeInputRequest {+ schema: typeof PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2;+ requestKind: "runtime";+ requestId: string;+ type: "input";+ status: "pending" | "resolved" | "expired" | "cancelled";+ prompt: string;+ input: PaperclipQuestionSet;+ origin?: PaperclipRuntimeRequestOrigin;+ turnId?: string;+ itemId?: string;+}++export class PaperclipQuestionValidationError extends Error {+ readonly code = "invalid_question_response" as const;+ readonly path: string;++ constructor(path: string, detail: string) {+ super(`${path}: ${detail}`);+ this.name = "PaperclipQuestionValidationError";+ this.path = path;+ }+}++function record(value: unknown): Record<string, unknown> | null {+ return typeof value === "object" && value !== null && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : null;+}++function rejectUnknownKeys(+ value: Record<string, unknown>,+ allowed: readonly string[],+ path: string,+): void {+ const allowedKeys = new Set(allowed);+ const unknown = Object.keys(value).find((key) => !allowedKeys.has(key));+ if (unknown !== undefined) {+ throw new PaperclipQuestionValidationError(+ `${path}/${unknown}`,+ "is not part of the canonical response contract",+ );+ }+}++function requiredText(value: unknown, path: string, maxLength = 4_000): string {+ if (+ typeof value !== "string" ||+ value.length === 0 ||+ value.length > maxLength+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ `must be a non-empty string of at most ${maxLength} characters`,+ );+ }+ return value;+}++function optionalText(+ value: unknown,+ path: string,+ maxLength = 4_000,+): string | undefined {+ if (value === undefined) return undefined;+ if (typeof value !== "string" || value.length > maxLength) {+ throw new PaperclipQuestionValidationError(+ path,+ `must be a string of at most ${maxLength} characters`,+ );+ }+ return value;+}++function optionalFiniteNumber(+ value: unknown,+ path: string,+): number | undefined {+ if (value === undefined) return undefined;+ if (typeof value !== "number" || !Number.isFinite(value)) {+ throw new PaperclipQuestionValidationError(path, "must be a finite number");+ }+ return value;+}++/** Parse and sanitize the provider-neutral presentation contract at an adapter boundary. */+export function parsePaperclipQuestionSet(+ value: unknown,+): PaperclipQuestionSet {+ const candidate = record(value);+ if (+ candidate === null ||+ candidate.schema !== PAPERCLIP_QUESTION_SET_SCHEMA+ ) {+ throw new PaperclipQuestionValidationError(+ "/input",+ `must use ${PAPERCLIP_QUESTION_SET_SCHEMA}`,+ );+ }+ if (+ !Array.isArray(candidate.questions) ||+ candidate.questions.length === 0 ||+ candidate.questions.length > 64+ ) {+ throw new PaperclipQuestionValidationError(+ "/input/questions",+ "must contain between 1 and 64 questions",+ );+ }+ const questionIds = new Set<string>();+ const questions = candidate.questions.map(+ (rawQuestion, questionIndex): PaperclipQuestion => {+ const path = `/input/questions/${questionIndex}`;+ const question = record(rawQuestion);+ if (question === null)+ throw new PaperclipQuestionValidationError(path, "must be an object");+ const id = requiredText(question.id, `${path}/id`, 160);+ if (questionIds.has(id))+ throw new PaperclipQuestionValidationError(+ `${path}/id`,+ "must be unique",+ );+ questionIds.add(id);+ const answerMode = question.answerMode;+ if (+ answerMode !== "single_select" &&+ answerMode !== "multi_select" &&+ answerMode !== "text"+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/answerMode`,+ "must be single_select, multi_select, or text",+ );+ }+ if (typeof question.required !== "boolean") {+ throw new PaperclipQuestionValidationError(+ `${path}/required`,+ "must be boolean",+ );+ }+ if (Array.isArray(question.options) && question.options.length > 128) {+ throw new PaperclipQuestionValidationError(+ `${path}/options`,+ "cannot contain more than 128 options",+ );+ }+ const options: PaperclipQuestionOption[] | undefined = Array.isArray(+ question.options,+ )+ ? question.options.map((rawOption, optionIndex) => {+ const optionPath = `${path}/options/${optionIndex}`;+ const option = record(rawOption);+ if (option === null)+ throw new PaperclipQuestionValidationError(+ optionPath,+ "must be an object",+ );+ return {+ id: requiredText(option.id, `${optionPath}/id`, 160),+ label: requiredText(option.label, `${optionPath}/label`, 1_000),+ ...(optionalText(+ option.description,+ `${optionPath}/description`,+ ) !== undefined+ ? {+ description: optionalText(+ option.description,+ `${optionPath}/description`,+ ),+ }+ : {}),+ };+ })+ : undefined;+ if (+ options !== undefined &&+ new Set(options.map((option) => option.id)).size !== options.length+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/options`,+ "option IDs must be unique within a question",+ );+ }+ if (answerMode !== "text" && (!options || options.length === 0)) {+ throw new PaperclipQuestionValidationError(+ `${path}/options`,+ "select questions require at least one option",+ );+ }+ if (+ answerMode === "text" &&+ options !== undefined &&+ options.length > 0+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/options`,+ "text questions cannot define options",+ );+ }+ const custom = record(question.customAnswer);+ const customAnswer =+ custom === null+ ? undefined+ : {+ enabled: true as const,+ ...(optionalText(+ custom.label,+ `${path}/customAnswer/label`,+ 1_000,+ ) !== undefined+ ? {+ label: optionalText(+ custom.label,+ `${path}/customAnswer/label`,+ 1_000,+ ),+ }+ : {}),+ ...(optionalText(+ custom.placeholder,+ `${path}/customAnswer/placeholder`,+ 1_000,+ ) !== undefined+ ? {+ placeholder: optionalText(+ custom.placeholder,+ `${path}/customAnswer/placeholder`,+ 1_000,+ ),+ }+ : {}),+ };+ if (custom !== null && custom.enabled !== true) {+ throw new PaperclipQuestionValidationError(+ `${path}/customAnswer/enabled`,+ "must be true when customAnswer is present",+ );+ }+ if (answerMode === "text" && customAnswer !== undefined) {+ throw new PaperclipQuestionValidationError(+ `${path}/customAnswer`,+ "text questions do not use a separate custom answer",+ );+ }+ const validation = record(question.textValidation);+ const textValidation: PaperclipQuestionTextValidation | undefined =+ validation === null+ ? undefined+ : {+ ...(typeof validation.minLength === "number"+ ? { minLength: validation.minLength }+ : {}),+ ...(typeof validation.maxLength === "number"+ ? { maxLength: validation.maxLength }+ : {}),+ ...(optionalText(+ validation.pattern,+ `${path}/textValidation/pattern`,+ 1_000,+ ) !== undefined+ ? {+ pattern: optionalText(+ validation.pattern,+ `${path}/textValidation/pattern`,+ 1_000,+ ),+ }+ : {}),+ ...(validation.inputType === "number" ||+ validation.inputType === "integer" ||+ validation.inputType === "text"+ ? { inputType: validation.inputType }+ : {}),+ ...(optionalFiniteNumber(+ validation.minimum,+ `${path}/textValidation/minimum`,+ ) !== undefined+ ? {+ minimum: optionalFiniteNumber(+ validation.minimum,+ `${path}/textValidation/minimum`,+ ),+ }+ : {}),+ ...(optionalFiniteNumber(+ validation.maximum,+ `${path}/textValidation/maximum`,+ ) !== undefined+ ? {+ maximum: optionalFiniteNumber(+ validation.maximum,+ `${path}/textValidation/maximum`,+ ),+ }+ : {}),+ };+ if (validation !== null) {+ for (const key of ["minLength", "maxLength"] as const) {+ const raw = validation[key];+ if (+ raw !== undefined &&+ (!Number.isSafeInteger(raw) ||+ (raw as number) < 0 ||+ (raw as number) > 100_000)+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/textValidation/${key}`,+ "must be an integer from 0 through 100000",+ );+ }+ }+ if (+ validation.inputType !== undefined &&+ !["text", "number", "integer"].includes(String(validation.inputType))+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/textValidation/inputType`,+ "must be text, number, or integer",+ );+ }+ if (+ textValidation?.minLength !== undefined &&+ textValidation.maxLength !== undefined &&+ textValidation.minLength > textValidation.maxLength+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/textValidation`,+ "minLength cannot exceed maxLength",+ );+ }+ if (+ textValidation?.minimum !== undefined &&+ textValidation.maximum !== undefined &&+ textValidation.minimum > textValidation.maximum+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/textValidation`,+ "minimum cannot exceed maximum",+ );+ }+ if (textValidation?.pattern !== undefined) {+ try {+ new RegExp(textValidation.pattern);+ } catch {+ throw new PaperclipQuestionValidationError(+ `${path}/textValidation/pattern`,+ "must be a valid regular expression",+ );+ }+ }+ }+ return {+ id,+ ...(optionalText(question.header, `${path}/header`, 1_000) !== undefined+ ? { header: optionalText(question.header, `${path}/header`, 1_000) }+ : {}),+ prompt: requiredText(question.prompt, `${path}/prompt`),+ ...(optionalText(question.helpText, `${path}/helpText`) !== undefined+ ? { helpText: optionalText(question.helpText, `${path}/helpText`) }+ : {}),+ required: question.required,+ answerMode,+ ...(options !== undefined ? { options } : {}),+ ...(customAnswer !== undefined ? { customAnswer } : {}),+ ...(textValidation !== undefined ? { textValidation } : {}),+ };+ },+ );+ return {+ schema: PAPERCLIP_QUESTION_SET_SCHEMA,+ ...(optionalText(candidate.title, "/input/title", 1_000) !== undefined+ ? { title: optionalText(candidate.title, "/input/title", 1_000) }+ : {}),+ ...(optionalText(candidate.description, "/input/description") !== undefined+ ? {+ description: optionalText(+ candidate.description,+ "/input/description",+ ),+ }+ : {}),+ ...(optionalText(candidate.submitLabel, "/input/submitLabel", 200) !==+ undefined+ ? {+ submitLabel: optionalText(+ candidate.submitLabel,+ "/input/submitLabel",+ 200,+ ),+ }+ : {}),+ questions,+ };+}++function answerHasValue(answer: PaperclipQuestionAnswer): boolean {+ return Boolean(+ answer.text?.trim() ||+ answer.customText?.trim() ||+ answer.selectedOptionIds?.length,+ );+}++/** Revalidate untrusted UI input against the persisted question set. */+export function parsePaperclipQuestionResponse(+ questionSetValue: unknown,+ responseValue: unknown,+): PaperclipQuestionResponse {+ const questionSet = parsePaperclipQuestionSet(questionSetValue);+ const response = record(responseValue);+ if (+ response === null ||+ response.schema !== PAPERCLIP_QUESTION_RESPONSE_SCHEMA+ ) {+ throw new PaperclipQuestionValidationError(+ "/response",+ `must use ${PAPERCLIP_QUESTION_RESPONSE_SCHEMA}`,+ );+ }+ rejectUnknownKeys(response, ["schema", "answers"], "/response");+ const rawAnswers = record(response.answers);+ if (rawAnswers === null)+ throw new PaperclipQuestionValidationError(+ "/response/answers",+ "must be an object keyed by question ID",+ );+ const questions = new Map(+ questionSet.questions.map((question) => [question.id, question]),+ );+ for (const questionId of Object.keys(rawAnswers)) {+ if (!questions.has(questionId))+ throw new PaperclipQuestionValidationError(+ `/response/answers/${questionId}`,+ "does not match a question in the persisted set",+ );+ }+ const answers: Record<string, PaperclipQuestionAnswer> = {};+ for (const question of questionSet.questions) {+ const path = `/response/answers/${question.id}`;+ const raw = rawAnswers[question.id];+ if (raw === undefined) {+ if (question.required)+ throw new PaperclipQuestionValidationError(path, "is required");+ continue;+ }+ const answer = record(raw);+ if (answer === null)+ throw new PaperclipQuestionValidationError(path, "must be an object");+ rejectUnknownKeys(+ answer,+ ["selectedOptionIds", "text", "customText"],+ path,+ );+ const selectedOptionIds =+ answer.selectedOptionIds === undefined+ ? undefined+ : Array.isArray(answer.selectedOptionIds) &&+ answer.selectedOptionIds.every((entry) => typeof entry === "string")+ ? [...answer.selectedOptionIds]+ : null;+ if (selectedOptionIds === null)+ throw new PaperclipQuestionValidationError(+ `${path}/selectedOptionIds`,+ "must be an array of strings",+ );+ if (+ selectedOptionIds !== undefined &&+ new Set(selectedOptionIds).size !== selectedOptionIds.length+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/selectedOptionIds`,+ "cannot contain duplicates",+ );+ }+ const textValue = optionalText(answer.text, `${path}/text`, 100_000);+ const customText = optionalText(+ answer.customText,+ `${path}/customText`,+ 100_000,+ );+ if (question.answerMode === "text") {+ if (selectedOptionIds?.length || customText !== undefined)+ throw new PaperclipQuestionValidationError(+ path,+ "text answers only carry text",+ );+ } else {+ if (textValue !== undefined)+ throw new PaperclipQuestionValidationError(+ path,+ "select answers do not carry text",+ );+ const allowed = new Set(+ (question.options ?? []).map((option) => option.id),+ );+ for (const optionId of selectedOptionIds ?? []) {+ if (!allowed.has(optionId))+ throw new PaperclipQuestionValidationError(+ `${path}/selectedOptionIds`,+ `contains unknown option ${optionId}`,+ );+ }+ if (+ question.answerMode === "single_select" &&+ (selectedOptionIds?.length ?? 0) > 1+ ) {+ throw new PaperclipQuestionValidationError(+ `${path}/selectedOptionIds`,+ "single-select answers choose at most one option",+ );+ }+ if (customText !== undefined && question.customAnswer?.enabled !== true) {+ throw new PaperclipQuestionValidationError(+ `${path}/customText`,+ "custom answers are not enabled for this question",+ );+ }+ if (+ customText?.trim() &&+ (selectedOptionIds?.length ?? 0) > 0 &&+ question.answerMode === "single_select"+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ "single-select answers cannot select an option and a custom answer",+ );+ }+ }+ const parsed: PaperclipQuestionAnswer = {+ ...(selectedOptionIds !== undefined ? { selectedOptionIds } : {}),+ ...(textValue !== undefined ? { text: textValue } : {}),+ ...(customText !== undefined ? { customText } : {}),+ };+ if (question.required && !answerHasValue(parsed))+ throw new PaperclipQuestionValidationError(path, "is required");+ const boundedText =+ question.answerMode === "text" ? parsed.text : parsed.customText;+ if (boundedText !== undefined) {+ const validation = question.textValidation;+ if (+ validation?.minLength !== undefined &&+ boundedText.length < validation.minLength+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ `must contain at least ${validation.minLength} characters`,+ );+ }+ if (+ validation?.maxLength !== undefined &&+ boundedText.length > validation.maxLength+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ `must contain at most ${validation.maxLength} characters`,+ );+ }+ if (+ validation?.pattern !== undefined &&+ !new RegExp(validation.pattern).test(boundedText)+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ "does not match the required format",+ );+ }+ if (+ validation?.inputType === "number" ||+ validation?.inputType === "integer"+ ) {+ const numeric = Number(boundedText);+ if (+ !Number.isFinite(numeric) ||+ (validation.inputType === "integer" && !Number.isInteger(numeric))+ ) {+ throw new PaperclipQuestionValidationError(+ path,+ `must be a valid ${validation.inputType}`,+ );+ }+ if (validation.minimum !== undefined && numeric < validation.minimum)+ throw new PaperclipQuestionValidationError(+ path,+ `must be at least ${validation.minimum}`,+ );+ if (validation.maximum !== undefined && numeric > validation.maximum)+ throw new PaperclipQuestionValidationError(+ path,+ `must be at most ${validation.maximum}`,+ );+ }+ }+ if (answerHasValue(parsed)) answers[question.id] = parsed;+ }+ return { schema: PAPERCLIP_QUESTION_RESPONSE_SCHEMA, answers };+}diff --git a/packages/paperclip-runner/src/index.ts b/packages/paperclip-runner/src/index.tsnew file mode 100644index 0000000000..5048fc3a21--- /dev/null+++ b/packages/paperclip-runner/src/index.ts@@ -0,0 +1,7 @@+export * from "./contracts/completion-result.js";+export * from "./contracts/question-set.js";+export * from "./protocol/replay-contract.js";+export * from "./protocol/replay-loader.js";+export * from "./protocol/result-normalization.js";+export * from "./reducer/session-reducer.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.tsnew file mode 100644index 0000000000..37368bec6e--- /dev/null+++ b/packages/paperclip-runner/src/protocol/generated/schema-bundle.ts@@ -0,0 +1,3657 @@+// Generated by scripts/generate-protocol-schema-module.mjs. Do not edit.++export const identitySchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/identity.schema.json",+ "title": "PRP identity graph",+ "type": "object",+ "required": [+ "schema",+ "companyId",+ "issueId",+ "runId",+ "environmentLeaseId",+ "runnerInstanceId",+ "normalizedSessionId",+ "driverSessionId"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.identity.v1"+ },+ "companyId": {+ "$ref": "#/$defs/stableId"+ },+ "issueId": {+ "$ref": "#/$defs/stableId"+ },+ "runId": {+ "$ref": "#/$defs/stableId"+ },+ "environmentLeaseId": {+ "$ref": "#/$defs/stableId"+ },+ "runnerInstanceId": {+ "$ref": "#/$defs/stableId"+ },+ "normalizedSessionId": {+ "$ref": "#/$defs/stableId"+ },+ "driverSessionId": {+ "$ref": "#/$defs/stableId"+ },+ "providerSessionId": {+ "$ref": "#/$defs/stableId"+ }+ },+ "additionalProperties": true,+ "$defs": {+ "stableId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"+ }+ }+} as const;++export const capabilitiesSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/capabilities.schema.json",+ "title": "PRP negotiated capabilities",+ "type": "object",+ "required": [+ "schema",+ "sessionReusePolicy",+ "driver",+ "steer",+ "interrupt",+ "resume",+ "runtimeRequests",+ "structuredResult",+ "typedEvents"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.capabilities.v1"+ },+ "sessionReusePolicy": {+ "enum": [+ "new_per_run",+ "reuse_per_issue",+ "reuse_per_workspace"+ ]+ },+ "driver": {+ "type": "object",+ "required": [+ "kind",+ "version"+ ],+ "properties": {+ "kind": {+ "type": "string",+ "minLength": 1,+ "maxLength": 80+ },+ "version": {+ "type": "string",+ "minLength": 1,+ "maxLength": 80+ }+ },+ "additionalProperties": true+ },+ "steer": {+ "type": "boolean"+ },+ "interrupt": {+ "type": "boolean"+ },+ "resume": {+ "type": "boolean"+ },+ "runtimeRequests": {+ "type": "boolean"+ },+ "structuredResult": {+ "type": "boolean"+ },+ "typedEvents": {+ "type": "boolean"+ },+ "typedEventFamilies": {+ "type": "array",+ "maxItems": 64,+ "items": {+ "type": "object",+ "required": [+ "family",+ "version",+ "availability",+ "detailLevel"+ ],+ "properties": {+ "family": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[a-z][a-z0-9_.-]*$"+ },+ "version": {+ "const": 1+ },+ "availability": {+ "enum": [+ "available",+ "unsupported",+ "policy_disabled"+ ]+ },+ "detailLevel": {+ "enum": [+ "summary",+ "structured"+ ]+ }+ },+ "additionalProperties": false+ }+ },+ "semanticTools": {+ "type": "object",+ "required": [+ "schema",+ "schemaVersion",+ "operations"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.semantic_tools.v1"+ },+ "schemaVersion": {+ "const": 1+ },+ "operations": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "operationId",+ "version",+ "availability",+ "redactionDisposition"+ ],+ "properties": {+ "operationId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"+ },+ "version": {+ "const": 1+ },+ "availability": {+ "enum": [+ "available",+ "denied",+ "unsupported"+ ]+ },+ "redactionDisposition": {+ "const": "digest_only"+ },+ "requiredClaims": {+ "type": "array",+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "uniqueItems": true+ },+ "reasonCode": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[a-z][a-z0-9_.:-]*$"+ }+ },+ "additionalProperties": true+ }+ }+ },+ "additionalProperties": true+ },+ "unsupported": {+ "type": "array",+ "items": {+ "type": "string",+ "minLength": 1+ },+ "uniqueItems": true+ }+ },+ "additionalProperties": true+} as const;++export const commandSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/command.schema.json",+ "title": "PRP runner command",+ "type": "object",+ "required": [+ "schema",+ "commandId",+ "controllerSeq",+ "type",+ "issuedAt",+ "payload"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.command.v1"+ },+ "commandId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "controllerSeq": {+ "type": "integer",+ "minimum": 1+ },+ "type": {+ "enum": [+ "run.prepare",+ "run.attach",+ "session.open",+ "turn.start",+ "turn.steer",+ "turn.interrupt",+ "turn.stop",+ "request.resolve",+ "interaction.receipt",+ "semantic_tool.result",+ "session.snapshot",+ "session.close",+ "session.budget.increase",+ "session.destroy",+ "run.cancel",+ "runner.drain",+ "runner.suspend",+ "runner.shutdown"+ ]+ },+ "issuedAt": {+ "type": "string",+ "format": "date-time"+ },+ "deadlineAt": {+ "type": "string",+ "format": "date-time"+ },+ "precondition": {+ "type": "object",+ "properties": {+ "runnerState": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "runState": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "sessionState": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "activeTurnId": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "additionalProperties": true+ },+ "payload": {+ "type": "object",+ "additionalProperties": true+ }+ },+ "additionalProperties": true+} as const;++export const providerDescriptorSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/provider-descriptor.schema.json",+ "title": "PRP provider runtime descriptor",+ "type": "object",+ "required": [+ "provider",+ "driver",+ "model",+ "executionKind",+ "providerVersion"+ ],+ "properties": {+ "provider": {+ "const": "codex"+ },+ "driver": {+ "const": "codex_app_server"+ },+ "model": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "executionKind": {+ "const": "local_process"+ },+ "providerVersion": {+ "type": "string",+ "minLength": 1,+ "maxLength": 120+ },+ "providerSessionId": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "processId": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 1+ }+ },+ "additionalProperties": true+} as const;++export const providerEventSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json",+ "title": "Provider-neutral runner activity payload",+ "oneOf": [+ {+ "$ref": "#/$defs/plan"+ },+ {+ "$ref": "#/$defs/toolExecution"+ },+ {+ "$ref": "#/$defs/research"+ },+ {+ "$ref": "#/$defs/delegation"+ },+ {+ "$ref": "#/$defs/modelRoute"+ },+ {+ "$ref": "#/$defs/modelVerification"+ },+ {+ "$ref": "#/$defs/contextCompacted"+ },+ {+ "$ref": "#/$defs/artifactViewed"+ },+ {+ "$ref": "#/$defs/artifactGenerated"+ },+ {+ "$ref": "#/$defs/reviewMode"+ },+ {+ "$ref": "#/$defs/hook"+ },+ {+ "$ref": "#/$defs/memoryCitation"+ },+ {+ "$ref": "#/$defs/safetyReview"+ },+ {+ "$ref": "#/$defs/terminalInput"+ },+ {+ "$ref": "#/$defs/wait"+ },+ {+ "$ref": "#/$defs/providerNotice"+ }+ ],+ "$defs": {+ "id": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"+ },+ "shortText": {+ "type": "string",+ "maxLength": 4000+ },+ "nullableShortText": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 4000+ },+ "safePath": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 4096,+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).*$"+ },+ "safeUrl": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 8192,+ "pattern": "^https?://"+ },+ "plan": {+ "type": "object",+ "required": [+ "schema",+ "planId",+ "revision",+ "steps",+ "complete",+ "syncStatus"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.plan.updated.v1"+ },+ "planId": {+ "$ref": "#/$defs/id"+ },+ "revision": {+ "type": "integer",+ "minimum": 1+ },+ "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+ }+ },+ "additionalProperties": false+ },+ "toolExecution": {+ "type": "object",+ "required": [+ "schema",+ "executionId",+ "transport",+ "operation",+ "status",+ "output",+ "outputBytes",+ "outputTruncated",+ "outputDigest"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.tool.execution.v1"+ },+ "executionId": {+ "$ref": "#/$defs/id"+ },+ "transport": {+ "enum": [+ "process",+ "mcp",+ "dynamic",+ "builtin"+ ]+ },+ "operation": {+ "enum": [+ "read",+ "search",+ "list",+ "execute",+ "edit",+ "unknown"+ ]+ },+ "name": {+ "$ref": "#/$defs/nullableShortText"+ },+ "target": {+ "$ref": "#/$defs/safePath"+ },+ "namespace": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "readOnly": {+ "type": [+ "boolean",+ "null"+ ]+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed",+ "cancelled",+ "interrupted"+ ]+ },+ "durationMs": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "exitCode": {+ "type": [+ "integer",+ "null"+ ]+ },+ "progress": {+ "$ref": "#/$defs/nullableShortText"+ },+ "output": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 65536+ },+ "outputBytes": {+ "type": "integer",+ "minimum": 0+ },+ "outputTruncated": {+ "type": "boolean"+ },+ "outputDigest": {+ "type": [+ "string",+ "null"+ ],+ "pattern": "^sha256:[a-f0-9]{64}$"+ }+ },+ "additionalProperties": false+ },+ "research": {+ "type": "object",+ "required": [+ "schema",+ "researchId",+ "action",+ "status",+ "sources"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.research.v1"+ },+ "researchId": {+ "$ref": "#/$defs/id"+ },+ "action": {+ "enum": [+ "search",+ "open_page",+ "find_in_page",+ "other"+ ]+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed",+ "cancelled"+ ]+ },+ "query": {+ "$ref": "#/$defs/nullableShortText"+ },+ "url": {+ "$ref": "#/$defs/safeUrl"+ },+ "pattern": {+ "$ref": "#/$defs/nullableShortText"+ },+ "sources": {+ "type": "array",+ "maxItems": 64,+ "items": {+ "type": "object",+ "required": [+ "sourceId",+ "title",+ "url",+ "snippet"+ ],+ "properties": {+ "sourceId": {+ "$ref": "#/$defs/id"+ },+ "title": {+ "$ref": "#/$defs/shortText"+ },+ "url": {+ "$ref": "#/$defs/safeUrl"+ },+ "snippet": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ }+ }+ },+ "additionalProperties": false+ },+ "delegation": {+ "type": "object",+ "required": [+ "schema",+ "delegationId",+ "action",+ "status",+ "children"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.delegation.v1"+ },+ "delegationId": {+ "$ref": "#/$defs/id"+ },+ "action": {+ "enum": [+ "spawn",+ "message",+ "resume",+ "wait",+ "close"+ ]+ },+ "status": {+ "enum": [+ "running",+ "waiting",+ "completed",+ "failed",+ "interrupted",+ "closed"+ ]+ },+ "children": {+ "type": "array",+ "maxItems": 64,+ "items": {+ "type": "object",+ "required": [+ "childId",+ "role",+ "model",+ "status",+ "summary",+ "activitySummary"+ ],+ "properties": {+ "childId": {+ "$ref": "#/$defs/id"+ },+ "role": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 160+ },+ "model": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "status": {+ "enum": [+ "running",+ "waiting",+ "completed",+ "failed",+ "interrupted",+ "closed"+ ]+ },+ "summary": {+ "$ref": "#/$defs/nullableShortText"+ },+ "activitySummary": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ }+ }+ },+ "additionalProperties": false+ },+ "modelRoute": {+ "type": "object",+ "required": [+ "schema",+ "routeId",+ "provider",+ "requestedModel",+ "fromModel",+ "effectiveModel",+ "reason"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.model.route_changed.v1"+ },+ "routeId": {+ "$ref": "#/$defs/id"+ },+ "provider": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "requestedModel": {+ "type": "string",+ "minLength": 1,+ "maxLength": 240+ },+ "fromModel": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "effectiveModel": {+ "type": "string",+ "minLength": 1,+ "maxLength": 240+ },+ "reason": {+ "$ref": "#/$defs/shortText"+ }+ },+ "additionalProperties": false+ },+ "modelVerification": {+ "type": "object",+ "required": [+ "schema",+ "verificationId",+ "status",+ "classes",+ "buffering",+ "summary"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.model.verification.v1"+ },+ "verificationId": {+ "$ref": "#/$defs/id"+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed"+ ]+ },+ "classes": {+ "type": "array",+ "maxItems": 32,+ "items": {+ "type": "string",+ "maxLength": 160+ }+ },+ "buffering": {+ "type": "boolean"+ },+ "summary": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "contextCompacted": {+ "type": "object",+ "required": [+ "schema",+ "compactionId",+ "reason",+ "preTokens",+ "postTokens",+ "sameSession"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.context.compacted.v1"+ },+ "compactionId": {+ "$ref": "#/$defs/id"+ },+ "reason": {+ "enum": [+ "context_window",+ "manual",+ "provider",+ "unknown"+ ]+ },+ "preTokens": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "postTokens": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "sameSession": {+ "type": "boolean"+ }+ },+ "additionalProperties": false+ },+ "artifactViewed": {+ "type": "object",+ "required": [+ "schema",+ "artifactId",+ "reference",+ "mediaType",+ "title"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.artifact.viewed.v1"+ },+ "artifactId": {+ "$ref": "#/$defs/id"+ },+ "reference": {+ "$ref": "#/$defs/safePath"+ },+ "mediaType": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 160+ },+ "title": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "artifactGenerated": {+ "type": "object",+ "required": [+ "schema",+ "artifactId",+ "status",+ "reference",+ "mediaType",+ "registered",+ "failure"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.artifact.generated.v1"+ },+ "artifactId": {+ "$ref": "#/$defs/id"+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed"+ ]+ },+ "reference": {+ "$ref": "#/$defs/safePath"+ },+ "mediaType": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 160+ },+ "registered": {+ "type": "boolean"+ },+ "transparentBackground": {+ "type": [+ "boolean",+ "null"+ ]+ },+ "failure": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "reviewMode": {+ "type": "object",+ "required": [+ "schema",+ "reviewId",+ "state",+ "scope"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.review.mode_changed.v1"+ },+ "reviewId": {+ "$ref": "#/$defs/id"+ },+ "state": {+ "enum": [+ "entered",+ "exited"+ ]+ },+ "scope": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "hook": {+ "type": "object",+ "required": [+ "schema",+ "hookId",+ "event",+ "scope",+ "status",+ "blocking",+ "durationMs",+ "summary"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.hook.v1"+ },+ "hookId": {+ "$ref": "#/$defs/id"+ },+ "event": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "scope": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed",+ "cancelled"+ ]+ },+ "blocking": {+ "type": "boolean"+ },+ "durationMs": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "summary": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "memoryCitation": {+ "type": "object",+ "required": [+ "schema",+ "citationId",+ "messageItemId",+ "label",+ "available",+ "reference"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.memory.citation.v1"+ },+ "citationId": {+ "$ref": "#/$defs/id"+ },+ "messageItemId": {+ "$ref": "#/$defs/id"+ },+ "label": {+ "$ref": "#/$defs/shortText"+ },+ "available": {+ "type": "boolean"+ },+ "reference": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 4096+ }+ },+ "additionalProperties": false+ },+ "safetyReview": {+ "type": "object",+ "required": [+ "schema",+ "reviewId",+ "targetExecutionId",+ "status",+ "decision",+ "summary"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.safety.review.v1"+ },+ "reviewId": {+ "$ref": "#/$defs/id"+ },+ "targetExecutionId": {+ "anyOf": [+ {+ "$ref": "#/$defs/id"+ },+ {+ "type": "null"+ }+ ]+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "failed"+ ]+ },+ "decision": {+ "enum": [+ "pending",+ "allowed",+ "denied",+ "user_required",+ "unknown"+ ]+ },+ "summary": {+ "$ref": "#/$defs/nullableShortText"+ }+ },+ "additionalProperties": false+ },+ "terminalInput": {+ "type": "object",+ "required": [+ "schema",+ "executionId",+ "origin",+ "inputClass",+ "byteCount"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.terminal.input_sent.v1"+ },+ "executionId": {+ "$ref": "#/$defs/id"+ },+ "origin": {+ "enum": [+ "agent",+ "user",+ "system"+ ]+ },+ "inputClass": {+ "enum": [+ "text",+ "control",+ "eof"+ ]+ },+ "byteCount": {+ "type": "integer",+ "minimum": 0+ }+ },+ "additionalProperties": false+ },+ "wait": {+ "type": "object",+ "required": [+ "schema",+ "waitId",+ "reason",+ "status",+ "plannedDurationMs",+ "elapsedDurationMs"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.wait.v1"+ },+ "waitId": {+ "$ref": "#/$defs/id"+ },+ "reason": {+ "enum": [+ "timer",+ "provider",+ "rate_limit",+ "unknown"+ ]+ },+ "status": {+ "enum": [+ "running",+ "completed",+ "interrupted",+ "cancelled"+ ]+ },+ "plannedDurationMs": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "elapsedDurationMs": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ }+ },+ "additionalProperties": false+ },+ "providerNotice": {+ "type": "object",+ "required": [+ "schema",+ "noticeId",+ "severity",+ "category",+ "scope",+ "recoverable",+ "userActionable",+ "summary"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.provider.notice.v1"+ },+ "noticeId": {+ "$ref": "#/$defs/id"+ },+ "severity": {+ "enum": [+ "info",+ "warning",+ "error"+ ]+ },+ "category": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "scope": {+ "enum": [+ "turn",+ "session",+ "environment",+ "account"+ ]+ },+ "recoverable": {+ "type": "boolean"+ },+ "userActionable": {+ "type": "boolean"+ },+ "summary": {+ "$ref": "#/$defs/shortText"+ }+ },+ "additionalProperties": false+ }+ }+} as const;++export const workspaceDiffSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/workspace-diff.schema.json",+ "title": "Paperclip workspace diff",+ "type": "object",+ "required": [+ "schema",+ "changeSetId",+ "revision",+ "source",+ "complete",+ "files",+ "totals",+ "patchArtifactRef"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.workspace.diff.v1"+ },+ "changeSetId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 200+ },+ "revision": {+ "type": "integer",+ "minimum": 1+ },+ "source": {+ "enum": [+ "harness_reported",+ "runner_verified"+ ]+ },+ "complete": {+ "type": "boolean"+ },+ "files": {+ "type": "array",+ "maxItems": 2000,+ "items": {+ "type": "object",+ "required": [+ "path",+ "operation",+ "previousPath",+ "additions",+ "deletions",+ "binary",+ "diff"+ ],+ "properties": {+ "path": {+ "type": "string",+ "minLength": 1,+ "maxLength": 1024,+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"+ },+ "operation": {+ "enum": [+ "create",+ "modify",+ "delete",+ "rename",+ "mode_change"+ ]+ },+ "previousPath": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string",+ "minLength": 1,+ "maxLength": 1024,+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"+ }+ ]+ },+ "additions": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "deletions": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "binary": {+ "type": "boolean"+ },+ "diff": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 262144+ }+ },+ "additionalProperties": false+ }+ },+ "totals": {+ "type": "object",+ "required": [+ "files",+ "additions",+ "deletions"+ ],+ "properties": {+ "files": {+ "type": "integer",+ "minimum": 0+ },+ "additions": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ },+ "deletions": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0+ }+ },+ "additionalProperties": false+ },+ "patchArtifactRef": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 2048+ }+ },+ "additionalProperties": false+} as const;++export const workspaceFileReferenceSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/workspace-file-reference.schema.json",+ "title": "Paperclip workspace file reference",+ "type": "object",+ "required": [+ "schema",+ "referenceId",+ "source",+ "path",+ "displayName",+ "mediaType",+ "presentation",+ "line",+ "preview",+ "previewTruncated",+ "contentDigest"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.workspace.file_reference.v1"+ },+ "referenceId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 240+ },+ "source": {+ "enum": [+ "harness_reported",+ "runner_verified"+ ]+ },+ "path": {+ "type": "string",+ "minLength": 1,+ "maxLength": 1024,+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"+ },+ "displayName": {+ "type": "string",+ "minLength": 1,+ "maxLength": 255+ },+ "mediaType": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 160+ },+ "presentation": {+ "enum": [+ "document",+ "code",+ "image",+ "generic"+ ]+ },+ "line": {+ "type": [+ "integer",+ "null"+ ],+ "minimum": 1+ },+ "preview": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 262144+ },+ "previewTruncated": {+ "type": "boolean"+ },+ "contentDigest": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string",+ "pattern": "^sha256:[a-f0-9]{64}$"+ }+ ]+ }+ },+ "additionalProperties": false+} as const;++export const semanticToolSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/semantic-tool.schema.json",+ "title": "PRP provider-neutral semantic tool envelope",+ "type": "object",+ "required": [+ "schema",+ "schemaVersion",+ "phase",+ "operationId",+ "callId",+ "correlation",+ "idempotencyKey",+ "content"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.semantic_tool.v1"+ },+ "schemaVersion": {+ "const": 1+ },+ "phase": {+ "enum": [+ "input",+ "result"+ ]+ },+ "operationId": {+ "$ref": "#/$defs/stableId"+ },+ "callId": {+ "$ref": "#/$defs/stableId"+ },+ "correlation": {+ "type": "object",+ "required": [+ "runId",+ "normalizedSessionId",+ "turnId",+ "itemId"+ ],+ "properties": {+ "runId": {+ "$ref": "#/$defs/stableId"+ },+ "normalizedSessionId": {+ "$ref": "#/$defs/stableId"+ },+ "turnId": {+ "$ref": "#/$defs/stableId"+ },+ "itemId": {+ "$ref": "#/$defs/stableId"+ },+ "requestId": {+ "$ref": "#/$defs/stableId"+ }+ },+ "additionalProperties": true+ },+ "idempotencyKey": {+ "type": [+ "string",+ "null"+ ],+ "minLength": 1,+ "maxLength": 240+ },+ "content": {+ "$ref": "#/$defs/safeContent"+ },+ "outcome": {+ "enum": [+ "succeeded",+ "denied",+ "conflict",+ "duplicate",+ "unavailable",+ "failed"+ ]+ },+ "code": {+ "$ref": "#/$defs/stableCode"+ },+ "retryable": {+ "type": "boolean"+ },+ "authorizationBoundary": {+ "enum": [+ "company",+ "actor",+ "active_task",+ "grant",+ "governed_action",+ "lock",+ "revision"+ ]+ },+ "operationReceiptId": {+ "$ref": "#/$defs/stableId"+ },+ "auditReceiptId": {+ "$ref": "#/$defs/stableId"+ },+ "currentRevision": {+ "oneOf": [+ {+ "type": "integer",+ "minimum": 0+ },+ {+ "$ref": "#/$defs/stableId"+ }+ ]+ },+ "duplicateOfReceiptId": {+ "$ref": "#/$defs/stableId"+ },+ "artifactRefs": {+ "type": "array",+ "items": {+ "allOf": [+ {+ "$ref": "#/$defs/safeReference"+ },+ {+ "type": "object",+ "properties": {+ "kind": {+ "enum": [+ "artifact",+ "work_product"+ ]+ }+ }+ }+ ]+ },+ "uniqueItems": true+ },+ "targets": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/immutableTarget"+ },+ "uniqueItems": true+ },+ "causalRefs": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/safeReference"+ },+ "uniqueItems": true+ }+ },+ "allOf": [+ {+ "if": {+ "properties": {+ "phase": {+ "const": "result"+ }+ }+ },+ "then": {+ "required": [+ "outcome",+ "code",+ "retryable",+ "authorizationBoundary",+ "operationReceiptId"+ ]+ }+ }+ ],+ "additionalProperties": true,+ "$defs": {+ "stableId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 240,+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"+ },+ "stableCode": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[a-z][a-z0-9_.:-]*$"+ },+ "safeContent": {+ "type": "object",+ "required": [+ "digest",+ "redactionDisposition",+ "references"+ ],+ "properties": {+ "digest": {+ "type": "string",+ "pattern": "^sha256:[a-f0-9]{64}$"+ },+ "redactionDisposition": {+ "enum": [+ "digest_only",+ "allowlisted_references",+ "redacted"+ ]+ },+ "references": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/safeReference"+ },+ "uniqueItems": true+ }+ },+ "additionalProperties": true+ },+ "safeReference": {+ "type": "object",+ "required": [+ "kind",+ "id"+ ],+ "properties": {+ "kind": {+ "enum": [+ "task",+ "document_revision",+ "interaction",+ "approval",+ "decision",+ "artifact",+ "work_product",+ "wake",+ "monitor",+ "audit",+ "operation"+ ]+ },+ "id": {+ "$ref": "#/$defs/stableId"+ }+ },+ "additionalProperties": true+ },+ "immutableTarget": {+ "type": "object",+ "required": [+ "kind",+ "id",+ "immutable"+ ],+ "properties": {+ "kind": {+ "enum": [+ "document_revision",+ "interaction",+ "approval",+ "decision"+ ]+ },+ "id": {+ "$ref": "#/$defs/stableId"+ },+ "immutable": {+ "const": true+ },+ "revisionId": {+ "$ref": "#/$defs/stableId"+ },+ "decisionId": {+ "$ref": "#/$defs/stableId"+ }+ },+ "additionalProperties": true+ }+ }+} as const;++export const usageSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/usage.schema.json",+ "title": "PRP provider usage receipt",+ "type": "object",+ "required": [+ "provider",+ "model",+ "cumulative",+ "runDelta"+ ],+ "properties": {+ "provider": {+ "type": "string",+ "minLength": 1,+ "maxLength": 80+ },+ "model": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "providerSessionId": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "providerRequestId": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 240+ },+ "cumulative": {+ "$ref": "#/$defs/measurement"+ },+ "runDelta": {+ "$ref": "#/$defs/measurement"+ }+ },+ "additionalProperties": false,+ "$defs": {+ "measurement": {+ "type": "object",+ "required": [+ "inputTokens",+ "outputTokens",+ "cacheReadTokens",+ "cacheWriteTokens",+ "activeSeconds",+ "requests",+ "providerCostUsd"+ ],+ "properties": {+ "inputTokens": {+ "type": "integer",+ "minimum": 0+ },+ "outputTokens": {+ "type": "integer",+ "minimum": 0+ },+ "cacheReadTokens": {+ "type": "integer",+ "minimum": 0+ },+ "cacheWriteTokens": {+ "type": "integer",+ "minimum": 0+ },+ "activeSeconds": {+ "type": "number",+ "minimum": 0+ },+ "requests": {+ "type": "integer",+ "minimum": 0+ },+ "providerCostUsd": {+ "type": "number",+ "minimum": 0+ }+ },+ "additionalProperties": false+ }+ }+} as const;++export const stopReasonSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/stop-reason.schema.json",+ "title": "PRP terminal stop reason receipt",+ "type": "object",+ "required": [+ "schema",+ "schemaVersion",+ "receiptId",+ "kind",+ "code",+ "retryable",+ "decisionId",+ "limitClass",+ "aggregate"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.stop_reason.v1"+ },+ "schemaVersion": {+ "const": 1+ },+ "receiptId": {+ "$ref": "#/$defs/stableId"+ },+ "kind": {+ "enum": [+ "budget",+ "cost"+ ]+ },+ "code": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160,+ "pattern": "^[a-z][a-z0-9_.:-]*$"+ },+ "retryable": {+ "type": "boolean"+ },+ "decisionId": {+ "$ref": "#/$defs/stableId"+ },+ "limitClass": {+ "enum": [+ "company_monthly",+ "actor_monthly",+ "project_monthly",+ "run_cost",+ "provider_quota"+ ]+ },+ "aggregate": {+ "type": "object",+ "required": [+ "unit",+ "observed",+ "limit",+ "window"+ ],+ "properties": {+ "unit": {+ "enum": [+ "cents",+ "usd_micros",+ "tokens"+ ]+ },+ "observed": {+ "type": "integer",+ "minimum": 0+ },+ "limit": {+ "type": "integer",+ "minimum": 0+ },+ "window": {+ "enum": [+ "run",+ "monthly_utc",+ "provider_window"+ ]+ }+ },+ "additionalProperties": true+ },+ "relatedReceiptIds": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/stableId"+ },+ "uniqueItems": true+ }+ },+ "additionalProperties": true,+ "$defs": {+ "stableId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 240,+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"+ }+ }+} as const;++export const terminalSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/terminal.schema.json",+ "title": "PRP run terminal state",+ "type": "object",+ "required": [+ "schema",+ "turnTerminalState",+ "runTerminalState",+ "reportedWorkDisposition"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.terminal.v1"+ },+ "turnTerminalState": {+ "enum": [+ "completed",+ "failed",+ "interrupted",+ "cancelled"+ ]+ },+ "runTerminalState": {+ "enum": [+ "succeeded",+ "failed",+ "cancelled"+ ]+ },+ "reportedWorkDisposition": {+ "enum": [+ "done",+ "blocked",+ "needs_review",+ "yielded"+ ]+ },+ "workAssessmentId": {+ "type": "string",+ "minLength": 1+ },+ "statusDecisionId": {+ "type": "string",+ "minLength": 1+ },+ "stopReason": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/stop-reason.schema.json"+ }+ },+ "additionalProperties": true+} as const;++export const questionSetSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/question-set.schema.json",+ "title": "Paperclip question set",+ "type": "object",+ "required": [+ "schema",+ "questions"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.question_set.v1"+ },+ "title": {+ "type": "string",+ "maxLength": 1000+ },+ "description": {+ "type": "string",+ "maxLength": 4000+ },+ "submitLabel": {+ "type": "string",+ "maxLength": 200+ },+ "questions": {+ "type": "array",+ "minItems": 1,+ "maxItems": 64,+ "items": {+ "$ref": "#/$defs/question"+ }+ }+ },+ "$defs": {+ "option": {+ "type": "object",+ "required": [+ "id",+ "label"+ ],+ "properties": {+ "id": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "label": {+ "type": "string",+ "minLength": 1,+ "maxLength": 1000+ },+ "description": {+ "type": "string",+ "maxLength": 4000+ }+ },+ "additionalProperties": false+ },+ "customAnswer": {+ "type": "object",+ "required": [+ "enabled"+ ],+ "properties": {+ "enabled": {+ "const": true+ },+ "label": {+ "type": "string",+ "maxLength": 1000+ },+ "placeholder": {+ "type": "string",+ "maxLength": 1000+ }+ },+ "additionalProperties": false+ },+ "textValidation": {+ "type": "object",+ "properties": {+ "minLength": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100000+ },+ "maxLength": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100000+ },+ "pattern": {+ "type": "string",+ "maxLength": 1000+ },+ "inputType": {+ "enum": [+ "text",+ "number",+ "integer"+ ]+ },+ "minimum": {+ "type": "number"+ },+ "maximum": {+ "type": "number"+ }+ },+ "additionalProperties": false+ },+ "question": {+ "type": "object",+ "required": [+ "id",+ "prompt",+ "required",+ "answerMode"+ ],+ "properties": {+ "id": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "header": {+ "type": "string",+ "maxLength": 1000+ },+ "prompt": {+ "type": "string",+ "minLength": 1,+ "maxLength": 4000+ },+ "helpText": {+ "type": "string",+ "maxLength": 4000+ },+ "required": {+ "type": "boolean"+ },+ "answerMode": {+ "enum": [+ "single_select",+ "multi_select",+ "text"+ ]+ },+ "options": {+ "type": "array",+ "maxItems": 128,+ "items": {+ "$ref": "#/$defs/option"+ }+ },+ "customAnswer": {+ "$ref": "#/$defs/customAnswer"+ },+ "textValidation": {+ "$ref": "#/$defs/textValidation"+ }+ },+ "allOf": [+ {+ "if": {+ "properties": {+ "answerMode": {+ "const": "text"+ }+ },+ "required": [+ "answerMode"+ ]+ },+ "then": {+ "properties": {+ "options": {+ "type": "array",+ "maxItems": 0+ }+ },+ "not": {+ "required": [+ "customAnswer"+ ]+ }+ }+ },+ {+ "if": {+ "properties": {+ "answerMode": {+ "enum": [+ "single_select",+ "multi_select"+ ]+ }+ },+ "required": [+ "answerMode"+ ]+ },+ "then": {+ "required": [+ "options"+ ],+ "properties": {+ "options": {+ "type": "array",+ "minItems": 1+ }+ }+ }+ }+ ],+ "additionalProperties": false+ }+ },+ "additionalProperties": false+} as const;++export const questionResponseSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/question-response.schema.json",+ "title": "Paperclip question response",+ "type": "object",+ "required": [+ "schema",+ "answers"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.question_response.v1"+ },+ "answers": {+ "type": "object",+ "propertyNames": {+ "minLength": 1,+ "maxLength": 160+ },+ "additionalProperties": {+ "type": "object",+ "properties": {+ "selectedOptionIds": {+ "type": "array",+ "uniqueItems": true,+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ }+ },+ "text": {+ "type": "string",+ "maxLength": 100000+ },+ "customText": {+ "type": "string",+ "maxLength": 100000+ }+ },+ "additionalProperties": false+ }+ }+ },+ "additionalProperties": false+} as const;++export const questionAdapterFixtureSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/question-adapter-fixture.schema.json",+ "title": "Harness question adapter conformance fixture",+ "type": "object",+ "required": [+ "schema",+ "adapter",+ "nativeRequest",+ "canonicalQuestionSet",+ "canonicalResponse",+ "nativeResponse"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.question_adapter_fixture.v1"+ },+ "adapter": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "nativeRequest": {},+ "canonicalQuestionSet": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/question-set.schema.json"+ },+ "canonicalResponse": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/question-response.schema.json"+ },+ "nativeResponse": {}+ },+ "additionalProperties": false+} as const;++export const requestSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/request.schema.json",+ "title": "PRP request",+ "oneOf": [+ {+ "type": "object",+ "required": [+ "schema",+ "requestKind",+ "requestId",+ "type",+ "status",+ "prompt",+ "input"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.runtime_request.v2"+ },+ "requestKind": {+ "const": "runtime"+ },+ "requestId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "type": {+ "const": "input"+ },+ "status": {+ "enum": [+ "pending",+ "resolved",+ "expired",+ "cancelled"+ ]+ },+ "prompt": {+ "type": "string",+ "minLength": 1,+ "maxLength": 4000+ },+ "input": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/question-set.schema.json"+ },+ "origin": {+ "type": "object",+ "required": [+ "adapter"+ ],+ "properties": {+ "adapter": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "provider": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "method": {+ "type": "string",+ "minLength": 1,+ "maxLength": 500+ }+ },+ "additionalProperties": false+ },+ "turnId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "itemId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ }+ },+ "additionalProperties": false+ },+ {+ "type": "object",+ "required": [+ "schema",+ "requestKind",+ "requestId",+ "type",+ "status",+ "prompt"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.runtime_request.v1"+ },+ "requestKind": {+ "const": "runtime"+ },+ "requestId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "type": {+ "enum": [+ "permission",+ "input"+ ]+ },+ "status": {+ "enum": [+ "pending",+ "resolved",+ "expired",+ "cancelled"+ ]+ },+ "prompt": {+ "type": "string",+ "minLength": 1,+ "maxLength": 4000+ },+ "choices": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "key",+ "label"+ ],+ "properties": {+ "key": {+ "type": "string",+ "minLength": 1+ },+ "label": {+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": true+ }+ }+ },+ "additionalProperties": true+ },+ {+ "type": "object",+ "required": [+ "schema",+ "requestKind",+ "requestId",+ "kind",+ "blocking",+ "payload"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.interaction_request.v1"+ },+ "requestKind": {+ "const": "issue_thread"+ },+ "requestId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "kind": {+ "enum": [+ "request_confirmation",+ "request_checkbox_confirmation",+ "request_item_verdicts",+ "ask_user_questions",+ "suggest_tasks"+ ]+ },+ "blocking": {+ "type": "boolean"+ },+ "payload": {+ "type": "object",+ "additionalProperties": true+ }+ },+ "additionalProperties": true+ }+ ]+} as const;++export const resultSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/result.schema.json",+ "title": "PRP structured run result",+ "type": "object",+ "required": [+ "schema",+ "reportedWorkDisposition",+ "summary",+ "completionClaim",+ "evidence",+ "verification",+ "attentionRequests",+ "artifacts"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.run_result.v1"+ },+ "reportedWorkDisposition": {+ "enum": [+ "done",+ "blocked",+ "needs_review",+ "yielded"+ ]+ },+ "summary": {+ "type": "string",+ "minLength": 1,+ "maxLength": 12000+ },+ "completionClaim": {+ "type": "object",+ "required": [+ "contractRevision",+ "objectiveSatisfied",+ "criteria",+ "remainingWork"+ ],+ "properties": {+ "contractRevision": {+ "type": "string",+ "minLength": 1+ },+ "objectiveSatisfied": {+ "type": "boolean"+ },+ "criteria": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "criterionId",+ "status",+ "evidenceRefs"+ ],+ "properties": {+ "criterionId": {+ "type": "string",+ "minLength": 1+ },+ "status": {+ "enum": [+ "satisfied",+ "not_satisfied",+ "unknown"+ ]+ },+ "evidenceRefs": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "explanation": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "remainingWork": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "description",+ "blocksCompletion"+ ],+ "properties": {+ "description": {+ "type": "string",+ "minLength": 1+ },+ "blocksCompletion": {+ "type": "boolean"+ }+ },+ "additionalProperties": true+ }+ }+ },+ "additionalProperties": true+ },+ "evidence": {+ "type": "array",+ "items": {+ "type": "object"+ }+ },+ "verification": {+ "type": "array",+ "description": "Checks used to verify the work. Use failed only when the check actually ran and found a defect in the work. If a check could not run or complete because the environment, tool, dependency, permission, credential, policy, external service, or budget was unavailable, use not_run with reasonCode even when the attempted command exited non-zero.",+ "items": {+ "type": "object",+ "required": [+ "commandOrCheck",+ "status"+ ],+ "properties": {+ "commandOrCheck": {+ "type": "string",+ "minLength": 1+ },+ "status": {+ "enum": [+ "passed",+ "failed",+ "not_run"+ ],+ "description": "passed means the check ran and succeeded; failed means it ran to a meaningful verdict and found the work incorrect; not_run means no meaningful verdict was possible because the check was not attempted or could not complete."+ },+ "reasonCode": {+ "description": "Required for not_run; identify why the check had no meaningful verdict.",+ "enum": [+ "environment_unavailable",+ "tool_unavailable",+ "dependency_missing",+ "permission_denied",+ "credential_missing",+ "policy_restricted",+ "external_service_unavailable",+ "budget_exhausted",+ "other"+ ]+ },+ "detail": {+ "type": "string"+ },+ "artifactRef": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "blocker": {+ "type": "object",+ "required": [+ "reasonCode",+ "owner",+ "unblockAction",+ "scope"+ ],+ "properties": {+ "reasonCode": {+ "type": "string",+ "minLength": 1+ },+ "owner": {+ "type": "object",+ "additionalProperties": true+ },+ "unblockAction": {+ "type": "string",+ "minLength": 1+ },+ "scope": {+ "enum": [+ "current_track",+ "task_wide"+ ]+ }+ },+ "additionalProperties": true+ },+ "attentionRequests": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "kind": {+ "type": "string",+ "minLength": 1+ },+ "summary": {+ "type": "string",+ "minLength": 1+ },+ "ownerClass": {+ "enum": [+ "human",+ "agent",+ "external_system"+ ]+ },+ "targetAgentId": {+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": true+ }+ },+ "artifacts": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "kind",+ "ref"+ ],+ "properties": {+ "kind": {+ "type": "string",+ "minLength": 1+ },+ "ref": {+ "type": "string",+ "minLength": 1+ },+ "title": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "continuation": {+ "type": "object",+ "required": [+ "kind",+ "summary",+ "idempotencyKey"+ ],+ "properties": {+ "kind": {+ "enum": [+ "same_agent",+ "retry",+ "delegated_issue",+ "response_wake",+ "monitor"+ ]+ },+ "summary": {+ "type": "string",+ "minLength": 1+ },+ "idempotencyKey": {+ "type": "string",+ "minLength": 1+ }+ },+ "additionalProperties": true+ }+ },+ "allOf": [+ {+ "if": {+ "properties": {+ "reportedWorkDisposition": {+ "const": "blocked"+ }+ }+ },+ "then": {+ "required": [+ "blocker"+ ]+ }+ },+ {+ "if": {+ "properties": {+ "reportedWorkDisposition": {+ "const": "yielded"+ }+ }+ },+ "then": {+ "required": [+ "continuation"+ ]+ }+ }+ ],+ "additionalProperties": true+} as const;++export const eventSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/event.schema.json",+ "title": "PRP native event",+ "type": "object",+ "required": [+ "schema",+ "sourceEventId",+ "sourceSeq",+ "sourceInstanceId",+ "sourceKind",+ "runId",+ "eventType",+ "schemaVersion",+ "priority",+ "emittedAt",+ "payload"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.event.v1"+ },+ "sourceEventId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "sourceSeq": {+ "type": "integer",+ "minimum": 1,+ "maximum": 9007199254740991+ },+ "sourceInstanceId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "sourceKind": {+ "enum": [+ "runner",+ "control_plane"+ ]+ },+ "runId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "normalizedSessionId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "turnId": {+ "type": "string",+ "minLength": 1,+ "maxLength": 160+ },+ "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",+ "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",+ "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",+ "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",+ "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",+ "run.attached",+ "run.detached",+ "run.result.proposed",+ "run.result.accepted",+ "run.result.rejected",+ "attention.request.proposed",+ "attention.request.routed",+ "attention.request.resolved",+ "attention.request.expired",+ "attention.request.superseded",+ "work.assessment.recorded",+ "issue.status.decision.recorded",+ "issue.status.decision.applied",+ "issue.status.decision.rejected",+ "issue.status.decision.superseded",+ "run.terminal"+ ]+ },+ "schemaVersion": {+ "const": 1+ },+ "priority": {+ "enum": [+ 0,+ 1,+ 2+ ]+ },+ "emittedAt": {+ "type": "string",+ "format": "date-time"+ },+ "observedAt": {+ "type": "string",+ "format": "date-time"+ },+ "payload": {+ "type": "object",+ "properties": {+ "channel": {+ "enum": [+ "progress",+ "final",+ "summary",+ "detail",+ "unknown"+ ]+ },+ "providerPhase": {+ "type": "string"+ },+ "providerMethod": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "debug": {+ "type": "object",+ "additionalProperties": true+ }+ },+ "allOf": [+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "plan.updated"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/plan"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "tool.execution.started",+ "tool.execution.progressed",+ "tool.execution.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/toolExecution"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "research.started",+ "research.progressed",+ "research.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/research"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "delegation.started",+ "delegation.updated",+ "delegation.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/delegation"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "model.route.changed"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/modelRoute"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "model.verification.updated"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/modelVerification"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "context.compacted"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/contextCompacted"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "artifact.viewed"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/artifactViewed"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "artifact.generated"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/artifactGenerated"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "review.mode.changed"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/reviewMode"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "hook.started",+ "hook.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/hook"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "memory.citation.referenced"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/memoryCitation"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "safety.review.started",+ "safety.review.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/safetyReview"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "terminal.input.sent"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/terminalInput"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "wait.started",+ "wait.completed"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/wait"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "provider.notice.recorded"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json#/$defs/providerNotice"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "workspace.file.referenced"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/workspace-file-reference.schema.json"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "workspace.change.updated",+ "workspace.diff.recorded"+ ]+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/workspace-diff.schema.json"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "workspace.diff.recorded"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "allOf": [+ {+ "$ref": "https://paperclip.dev/schemas/prp/v1/workspace-diff.schema.json"+ },+ {+ "type": "object",+ "properties": {+ "complete": {+ "const": true+ }+ }+ }+ ]+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "semantic_tool.input",+ "mcp_app.tool_input"+ ]+ }+ }+ },+ "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": "input"+ }+ }+ }+ ]+ }+ },+ "additionalProperties": true+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "enum": [+ "semantic_tool.result",+ "mcp_app.tool_result"+ ]+ }+ }+ },+ "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": "result"+ }+ }+ }+ ]+ }+ },+ "additionalProperties": true+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "run.terminal"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/terminal.schema.json"+ }+ }+ }+ },+ {+ "if": {+ "properties": {+ "eventType": {+ "const": "run.result.proposed"+ }+ }+ },+ "then": {+ "properties": {+ "payload": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/result.schema.json"+ }+ }+ }+ }+ ],+ "additionalProperties": true+} as const;++export const fixtureSchema = {+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/fixture.schema.json",+ "title": "PRP scripted replay fixture",+ "type": "object",+ "required": [+ "schema",+ "fixtureVersion",+ "protocolVersion",+ "name",+ "description",+ "identity",+ "capabilities",+ "commands",+ "events",+ "result"+ ],+ "properties": {+ "schema": {+ "const": "paperclip.prp.fixture.v1"+ },+ "fixtureVersion": {+ "const": 1+ },+ "protocolVersion": {+ "const": 1+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 120+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 1000+ },+ "identity": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/identity.schema.json"+ },+ "capabilities": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/capabilities.schema.json"+ },+ "commands": {+ "type": "array",+ "items": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/command.schema.json"+ }+ },+ "events": {+ "type": "array",+ "minItems": 1,+ "items": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/event.schema.json"+ }+ },+ "requests": {+ "type": "array",+ "items": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/request.schema.json"+ }+ },+ "result": {+ "$ref": "https://paperclip.dev/schemas/prp/v1/result.schema.json"+ }+ },+ "additionalProperties": true+} as const;++export const prpSchemaBundle = {+ "identity": identitySchema,+ "capabilities": capabilitiesSchema,+ "command": commandSchema,+ "provider-descriptor": providerDescriptorSchema,+ "provider-event": providerEventSchema,+ "workspace-diff": workspaceDiffSchema,+ "workspace-file-reference": workspaceFileReferenceSchema,+ "semantic-tool": semanticToolSchema,+ "usage": usageSchema,+ "stop-reason": stopReasonSchema,+ "terminal": terminalSchema,+ "question-set": questionSetSchema,+ "question-response": questionResponseSchema,+ "question-adapter-fixture": questionAdapterFixtureSchema,+ "request": requestSchema,+ "result": resultSchema,+ "event": eventSchema,+ "fixture": fixtureSchema,+} as const;diff --git a/packages/paperclip-runner/src/protocol/replay-contract.test.ts b/packages/paperclip-runner/src/protocol/replay-contract.test.tsnew file mode 100644index 0000000000..5cb2f31f41--- /dev/null+++ b/packages/paperclip-runner/src/protocol/replay-contract.test.ts@@ -0,0 +1,172 @@+import { readFile } from "node:fs/promises";++import { describe, expect, it } from "vitest";++import {+ negotiateProtocolVersion,+ parsePrpFixtureText,+ PRP_PROTOCOL_VERSION,+} from "./replay-contract.js";++const fixtureDirectory = new URL(+ "../../protocol/fixtures/replay/",+ import.meta.url,+);+const validFixtures = [+ "happy-path.json",+ "failed-run.json",+ "interrupted-run.json",+ "duplicate-event.json",+ "source-gap.json",+ "unknown-optional-fields.json",+];++async function readFixture(+ name = "happy-path.json",+): Promise<Record<string, unknown>> {+ return JSON.parse(+ await readFile(new URL(name, fixtureDirectory), "utf8"),+ ) as Record<string, unknown>;+}++describe("PRP v1 JSON Schema contract", () => {+ for (const fixtureName of validFixtures) {+ it(`validates ${fixtureName}`, async () => {+ const result = parsePrpFixtureText(+ await readFile(new URL(fixtureName, fixtureDirectory), "utf8"),+ );+ expect(result.ok).toBe(true);+ });+ }++ it("preserves unknown optional fields for forward compatibility", async () => {+ const result = parsePrpFixtureText(+ await readFile(+ new URL("unknown-optional-fields.json", fixtureDirectory),+ "utf8",+ ),+ );+ expect(result.ok).toBe(true);+ if (result.ok) {+ expect(result.fixture.futureFixtureHint).toEqual({+ producerVersion: "1.1-preview",+ });+ expect(result.fixture.events[0]?.futureEnvelopeField).toBe(42);+ }+ });++ it("fails closed on an unsupported required protocol version", async () => {+ const result = parsePrpFixtureText(+ await readFile(+ new URL("unsupported-required-version.json", fixtureDirectory),+ "utf8",+ ),+ );+ expect(result).toMatchObject({+ ok: false,+ issues: [+ {+ code: "unsupported_required_version",+ path: "/protocolVersion",+ },+ ],+ });+ });++ it("fails closed on unsupported nested required schema versions", async () => {+ const fixture = await readFixture();+ const events = fixture.events as Array<Record<string, unknown>>;+ events[0]!.schemaVersion = 2;+ expect(parsePrpFixtureText(JSON.stringify(fixture))).toMatchObject({+ ok: false,+ issues: [+ {+ code: "unsupported_required_version",+ path: "/events/0/schemaVersion",+ },+ ],+ });+ });++ it("rejects source sequences that cannot be represented exactly", async () => {+ const fixture = await readFixture();+ const events = fixture.events as Array<Record<string, unknown>>;+ events[0]!.sourceSeq = Number.MAX_SAFE_INTEGER + 1;+ expect(parsePrpFixtureText(JSON.stringify(fixture))).toMatchObject({+ ok: false,+ issues: [+ {+ code: "schema_validation",+ path: "/events/0/sourceSeq",+ },+ ],+ });+ });++ it("requires the declared result to match the replayed result event", async () => {+ const fixture = await readFixture();+ const result = fixture.result as Record<string, unknown>;+ result.summary = "A contradictory expected result.";+ expect(parsePrpFixtureText(JSON.stringify(fixture))).toMatchObject({+ ok: false,+ issues: [+ {+ code: "binding_mismatch",+ path: "/result",+ },+ ],+ });+ });++ it("rejects a duplicate event id carrying different content", async () => {+ const fixture = await readFixture("duplicate-event.json");+ const events = fixture.events as Array<Record<string, unknown>>;+ const payload = events[3]!.payload as Record<string, unknown>;+ payload.text = "A mutated duplicate.";+ expect(parsePrpFixtureText(JSON.stringify(fixture))).toMatchObject({+ ok: false,+ issues: [+ {+ code: "binding_mismatch",+ path: "/events/3/sourceEventId",+ },+ ],+ });+ });++ it("requires exactly one unique terminal event", async () => {+ const fixture = await readFixture();+ const events = fixture.events as Array<Record<string, unknown>>;+ fixture.events = events.filter(+ (event) => event.eventType !== "run.terminal",+ );+ expect(parsePrpFixtureText(JSON.stringify(fixture))).toMatchObject({+ ok: false,+ issues: [+ {+ code: "binding_mismatch",+ path: "/events",+ },+ ],+ });+ });++ it("reports invalid JSON without throwing", () => {+ expect(parsePrpFixtureText("{")).toMatchObject({+ ok: false,+ issues: [{ code: "invalid_json", path: "/" }],+ });+ });++ it("selects only an overlapping supported protocol version", () => {+ expect(+ negotiateProtocolVersion(+ { min: 1, max: PRP_PROTOCOL_VERSION },+ { min: 1, max: 2 },+ ),+ ).toBe(1);+ expect(+ negotiateProtocolVersion({ min: 2, max: 3 }, { min: 1, max: 1 }),+ ).toBeNull();+ });+});diff --git a/packages/paperclip-runner/src/protocol/replay-contract.ts b/packages/paperclip-runner/src/protocol/replay-contract.tsnew file mode 100644index 0000000000..2b3764ff75--- /dev/null+++ b/packages/paperclip-runner/src/protocol/replay-contract.ts@@ -0,0 +1,457 @@+import { Ajv2020 } from "ajv/dist/2020.js";+import type { ErrorObject, ValidateFunction } from "ajv/dist/2020.js";+import type { FromSchema } from "json-schema-to-ts";++import {+ capabilitiesSchema,+ commandSchema,+ eventSchema,+ fixtureSchema,+ identitySchema,+ questionSetSchema,+ requestSchema,+ resultSchema,+ semanticToolSchema,+ stopReasonSchema,+ terminalSchema,+ prpSchemaBundle,+} from "./generated/schema-bundle.js";+import { normalizeLegacyPrpStructuredRunResult } from "./result-normalization.js";++export const PRP_PROTOCOL_NAME = "paperclip.runner";+export const PRP_PROTOCOL_VERSION = 1;+export const PRP_FIXTURE_SCHEMA = "paperclip.prp.fixture.v1";++type TerminalReferences = [typeof stopReasonSchema];+type EventReferences = [+ typeof semanticToolSchema,+ typeof stopReasonSchema,+ typeof terminalSchema,+ typeof resultSchema,+];+export type PrpIdentity = FromSchema<typeof identitySchema>;+export type PrpCapabilities = FromSchema<typeof capabilitiesSchema>;+export type PrpCommand = FromSchema<typeof commandSchema>;+export type PrpSemanticToolEnvelope = FromSchema<typeof semanticToolSchema>;+export type PrpStopReason = FromSchema<typeof stopReasonSchema>;+export type PrpTerminalState = FromSchema<+ typeof terminalSchema,+ { references: TerminalReferences }+>;+type RequestReferences = [typeof questionSetSchema];+export type PrpRequest = FromSchema<+ typeof requestSchema,+ { references: RequestReferences }+>;+export type PrpStructuredRunResult = FromSchema<typeof resultSchema>;+export type PrpEvent = FromSchema<+ typeof eventSchema,+ { references: EventReferences }+>;+/** Runtime-validated composition of the JSON-Schema-derived contract types. */+export interface PrpFixture {+ schema: typeof PRP_FIXTURE_SCHEMA;+ fixtureVersion: 1;+ protocolVersion: typeof PRP_PROTOCOL_VERSION;+ name: string;+ description: string;+ identity: PrpIdentity;+ capabilities: PrpCapabilities;+ commands: PrpCommand[];+ events: PrpEvent[];+ requests?: PrpRequest[];+ result: PrpStructuredRunResult;+ [key: string]: unknown;+}++export type ProtocolValidationIssueCode =+ | "invalid_json"+ | "schema_validation"+ | "unsupported_required_version"+ | "binding_mismatch";++export interface ProtocolValidationIssue {+ code: ProtocolValidationIssueCode;+ path: string;+ message: string;+}++export type ProtocolValidationResult =+ | { ok: true; fixture: PrpFixture; issues: [] }+ | { ok: false; fixture: null; issues: ProtocolValidationIssue[] };++export interface ProtocolVersionRange {+ min: number;+ max: number;+}++// Runtime validation compiles the same checked-in schemas used to generate+// the public TypeScript types. Browser/CSP-specific precompiled validators are+// intentionally deferred until the browser SDK package boundary is introduced.+const ajv = new Ajv2020({+ allErrors: true,+ strict: true,+ strictRequired: false,+ formats: {+ "date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/,+ },+});+for (const schema of Object.values(prpSchemaBundle)) ajv.addSchema(schema);++function validatorFor<T>(schemaId: string): ValidateFunction<T> {+ const validator = ajv.getSchema<T>(schemaId);+ if (validator === undefined) {+ throw new Error(`Missing generated PRP validator for ${schemaId}`);+ }+ return validator;+}++const fixtureValidator = validatorFor<PrpFixture>(fixtureSchema.$id);+const eventValidator = validatorFor<PrpEvent>(eventSchema.$id);+const resultValidator = validatorFor<PrpStructuredRunResult>(resultSchema.$id);++function asRecord(value: unknown): Record<string, unknown> | null {+ return typeof value === "object" && value !== null && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : null;+}++function canonicalJson(value: unknown): string {+ if (Array.isArray(value)) {+ return `[${value.map(canonicalJson).join(",")}]`;+ }+ const object = asRecord(value);+ if (object !== null) {+ return `{${Object.keys(object)+ .sort()+ .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)+ .join(",")}}`;+ }+ return JSON.stringify(value) ?? "undefined";+}++function versionIssues(value: unknown): ProtocolValidationIssue[] {+ const fixture = asRecord(value);+ if (fixture === null) {+ return [];+ }++ const issues: ProtocolValidationIssue[] = [];+ for (const [field, supported] of [+ ["fixtureVersion", 1],+ ["protocolVersion", PRP_PROTOCOL_VERSION],+ ] as const) {+ const actual = fixture[field];+ if (typeof actual === "number" && actual !== supported) {+ issues.push({+ code: "unsupported_required_version",+ path: `/${field}`,+ message: `${field} ${actual} is unsupported; this implementation requires ${supported}`,+ });+ }+ }++ if (Array.isArray(fixture.events)) {+ fixture.events.forEach((entry, index) => {+ const event = asRecord(entry);+ const actual = event?.schemaVersion;+ if (typeof actual === "number" && actual !== 1) {+ issues.push({+ code: "unsupported_required_version",+ path: `/events/${index}/schemaVersion`,+ message: `event schemaVersion ${actual} is unsupported; this implementation requires 1`,+ });+ }+ const payload = asRecord(event?.payload);+ const semanticTool = asRecord(payload?.semantic_tool);+ const semanticToolVersion = semanticTool?.schemaVersion;+ if (+ typeof semanticToolVersion === "number" &&+ semanticToolVersion !== 1+ ) {+ issues.push({+ code: "unsupported_required_version",+ path: `/events/${index}/payload/semantic_tool/schemaVersion`,+ message: `semantic_tool schemaVersion ${semanticToolVersion} is unsupported; this implementation requires 1`,+ });+ }+ const stopReason = asRecord(payload?.stopReason);+ const stopReasonVersion = stopReason?.schemaVersion;+ if (typeof stopReasonVersion === "number" && stopReasonVersion !== 1) {+ issues.push({+ code: "unsupported_required_version",+ path: `/events/${index}/payload/stopReason/schemaVersion`,+ message: `stopReason schemaVersion ${stopReasonVersion} is unsupported; this implementation requires 1`,+ });+ }+ });+ }+ const capabilities = asRecord(fixture.capabilities);+ const semanticTools = asRecord(capabilities?.semanticTools);+ const semanticToolsVersion = semanticTools?.schemaVersion;+ if (typeof semanticToolsVersion === "number" && semanticToolsVersion !== 1) {+ issues.push({+ code: "unsupported_required_version",+ path: "/capabilities/semanticTools/schemaVersion",+ message: `semanticTools schemaVersion ${semanticToolsVersion} is unsupported; this implementation requires 1`,+ });+ }+ return issues;+}++function ajvIssue(error: ErrorObject): ProtocolValidationIssue {+ return {+ code: "schema_validation",+ path: error.instancePath || "/",+ message: error.message ?? "does not match the PRP schema",+ };+}++function bindingIssues(fixture: PrpFixture): ProtocolValidationIssue[] {+ const issues: ProtocolValidationIssue[] = [];+ const uniqueEvents = new Map<string, PrpEvent>();+ const semanticCalls = new Map<+ string,+ {+ input?: { envelope: PrpSemanticToolEnvelope; index: number };+ result?: { envelope: PrpSemanticToolEnvelope; index: number };+ }+ >();+ fixture.events.forEach((event, index) => {+ if (event.runId !== fixture.identity.runId) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${index}/runId`,+ message: "event runId must match identity.runId",+ });+ }+ if (+ event.normalizedSessionId !== undefined &&+ event.normalizedSessionId !== fixture.identity.normalizedSessionId+ ) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${index}/normalizedSessionId`,+ message:+ "event normalizedSessionId must match identity.normalizedSessionId",+ });+ }+ const existing = uniqueEvents.get(event.sourceEventId);+ if (existing === undefined) {+ uniqueEvents.set(event.sourceEventId, event);+ } else {+ if (canonicalJson(existing) !== canonicalJson(event)) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${index}/sourceEventId`,+ message: "duplicate sourceEventId deliveries must be byte-equivalent",+ });+ }+ // At-least-once source delivery is not a second semantic invocation.+ return;+ }+ const payload = asRecord(event.payload);+ const semanticTool = asRecord(+ payload?.semantic_tool,+ ) as PrpSemanticToolEnvelope | null;+ if (semanticTool !== null) {+ const correlation = asRecord(semanticTool.correlation);+ for (const [field, actual, expected] of [+ ["runId", correlation?.runId, event.runId],+ [+ "normalizedSessionId",+ correlation?.normalizedSessionId,+ event.normalizedSessionId,+ ],+ ["turnId", correlation?.turnId, event.turnId],+ ["itemId", correlation?.itemId, event.itemId],+ ] as const) {+ if (actual !== expected) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${index}/payload/semantic_tool/correlation/${field}`,+ message: `semantic_tool correlation ${field} must match the containing event`,+ });+ }+ }+ const call = semanticCalls.get(semanticTool.callId) ?? {};+ const phase = semanticTool.phase;+ if (call[phase] !== undefined) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${index}/payload/semantic_tool/callId`,+ message: `semantic_tool call ${semanticTool.callId} must contain exactly one ${phase} envelope`,+ });+ } else {+ call[phase] = { envelope: semanticTool, index };+ semanticCalls.set(semanticTool.callId, call);+ }+ }+ });++ for (const [callId, call] of semanticCalls) {+ if (call.input === undefined || call.result === undefined) {+ const present = call.input ?? call.result;+ issues.push({+ code: "binding_mismatch",+ path: `/events/${present?.index ?? 0}/payload/semantic_tool/callId`,+ message: `semantic_tool call ${callId} must contain one input and one result envelope`,+ });+ continue;+ }+ for (const field of ["operationId", "idempotencyKey"] as const) {+ if (+ canonicalJson(call.input.envelope[field]) !==+ canonicalJson(call.result.envelope[field])+ ) {+ issues.push({+ code: "binding_mismatch",+ path: `/events/${call.result.index}/payload/semantic_tool/${field}`,+ message: `semantic_tool result ${field} must match its input envelope`,+ });+ }+ }+ }++ fixture.commands.forEach((command, index) => {+ if (command.controllerSeq !== index + 1) {+ issues.push({+ code: "binding_mismatch",+ path: `/commands/${index}/controllerSeq`,+ message: `controllerSeq must be ${index + 1} in a scripted fixture`,+ });+ }+ });++ const distinctEvents = [...uniqueEvents.values()];+ const proposedResults = distinctEvents.filter(+ (event) => event.eventType === "run.result.proposed",+ );+ if (proposedResults.length !== 1) {+ issues.push({+ code: "binding_mismatch",+ path: "/events",+ message:+ "scripted fixtures must contain exactly one unique run.result.proposed event",+ });+ } else if (+ canonicalJson(proposedResults[0]?.payload) !== canonicalJson(fixture.result)+ ) {+ issues.push({+ code: "binding_mismatch",+ path: "/result",+ message:+ "fixture result must match the run.result.proposed event payload",+ });+ }++ const terminalEvents = distinctEvents.filter(+ (event) => event.eventType === "run.terminal",+ );+ if (terminalEvents.length !== 1) {+ issues.push({+ code: "binding_mismatch",+ path: "/events",+ message:+ "scripted fixtures must contain exactly one unique run.terminal event",+ });+ }+ return issues;+}++export function validatePrpFixture(value: unknown): ProtocolValidationResult {+ const unsupported = versionIssues(value);+ if (unsupported.length > 0) {+ return { ok: false, fixture: null, issues: unsupported };+ }+ if (!fixtureValidator(value)) {+ return {+ ok: false,+ fixture: null,+ issues: (fixtureValidator.errors ?? []).map(ajvIssue),+ };+ }++ const bindings = bindingIssues(value);+ return bindings.length === 0+ ? { ok: true, fixture: value, issues: [] }+ : { ok: false, fixture: null, issues: bindings };+}++export function parsePrpFixtureText(text: string): ProtocolValidationResult {+ try {+ return validatePrpFixture(JSON.parse(text) as unknown);+ } catch (error) {+ return {+ ok: false,+ fixture: null,+ issues: [+ {+ code: "invalid_json",+ path: "/",+ message:+ error instanceof Error+ ? error.message+ : "fixture is not valid JSON",+ },+ ],+ };+ }+}++export type EventValidationResult =+ | { ok: true; event: PrpEvent; issues: [] }+ | { ok: false; event: null; issues: ProtocolValidationIssue[] };++export function validatePrpEvent(value: unknown): EventValidationResult {+ const record = asRecord(value);+ const schemaVersion = record?.schemaVersion;+ if (typeof schemaVersion === "number" && schemaVersion !== 1) {+ return {+ ok: false,+ event: null,+ issues: [+ {+ code: "unsupported_required_version",+ path: "/schemaVersion",+ message: `event schemaVersion ${schemaVersion} is unsupported; this implementation requires 1`,+ },+ ],+ };+ }+ if (!eventValidator(value)) {+ return {+ ok: false,+ event: null,+ issues: (eventValidator.errors ?? []).map(ajvIssue),+ };+ }+ return { ok: true, event: value, issues: [] };+}++export type StructuredResultValidationResult =+ | { ok: true; result: PrpStructuredRunResult; issues: [] }+ | { ok: false; result: null; issues: ProtocolValidationIssue[] };++/** Validate a semantic completion independently from a complete replay fixture. */+export function validatePrpStructuredRunResult(+ value: unknown,+): StructuredResultValidationResult {+ const normalized = normalizeLegacyPrpStructuredRunResult(value);+ if (!resultValidator(normalized)) {+ return {+ ok: false,+ result: null,+ issues: (resultValidator.errors ?? []).map(ajvIssue),+ };+ }+ return { ok: true, result: normalized, issues: [] };+}++export function negotiateProtocolVersion(+ runner: ProtocolVersionRange,+ controller: ProtocolVersionRange,+): number | null {+ const selected = Math.min(runner.max, controller.max);+ return selected >= Math.max(runner.min, controller.min) ? selected : null;+}diff --git a/packages/paperclip-runner/src/protocol/replay-loader.ts b/packages/paperclip-runner/src/protocol/replay-loader.tsnew file mode 100644index 0000000000..4b5994c9f1--- /dev/null+++ b/packages/paperclip-runner/src/protocol/replay-loader.ts@@ -0,0 +1,32 @@+import { readFile } from "node:fs/promises";++import {+ parsePrpFixtureText,+ type ProtocolValidationIssue,+ type PrpFixture,+} from "./replay-contract.js";++export const replayHappyFixtureUrl = new URL(+ "../../protocol/fixtures/replay/happy-path.json",+ import.meta.url,+);++export class PrpFixtureValidationError extends Error {+ readonly issues: ProtocolValidationIssue[];++ constructor(issues: ProtocolValidationIssue[]) {+ super(issues.map((issue) => `${issue.path}: ${issue.message}`).join("; "));+ this.name = "PrpFixtureValidationError";+ this.issues = issues;+ }+}++export async function loadPrpFixture(+ url: URL = replayHappyFixtureUrl,+): Promise<PrpFixture> {+ const result = parsePrpFixtureText(await readFile(url, "utf8"));+ if (!result.ok) {+ throw new PrpFixtureValidationError(result.issues);+ }+ return result.fixture;+}diff --git a/packages/paperclip-runner/src/protocol/result-normalization.test.ts b/packages/paperclip-runner/src/protocol/result-normalization.test.tsnew file mode 100644index 0000000000..cf68d2977d--- /dev/null+++ b/packages/paperclip-runner/src/protocol/result-normalization.test.ts@@ -0,0 +1,274 @@+import { describe, expect, it } from "vitest";+import {+ normalizeLegacyPrpStructuredRunResult,+ normalizePrpResultSignals,+} from "./result-normalization.js";+import { validatePrpStructuredRunResult } from "./replay-contract.js";++describe("normalizePrpResultSignals", () => {+ it("accepts legacy completion aliases as one canonical PRP result", () => {+ const legacy = {+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "completed",+ summary: "Implemented and verified the utility.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ {+ criterionId: "objective",+ status: "satisfied",+ evidenceRefs: ["file:a"],+ },+ ],+ remainingWork: [],+ },+ evidence: [{ ref: "file:a" }],+ verification: [+ {+ command: "node --test",+ cwd: "fixture",+ status: "passed",+ result: "4 passed",+ },+ ],+ };++ expect(normalizeLegacyPrpStructuredRunResult(legacy)).toMatchObject({+ reportedWorkDisposition: "done",+ attentionRequests: [],+ artifacts: [],+ verification: [+ { commandOrCheck: "node --test", status: "passed", detail: "4 passed" },+ ],+ });+ expect(validatePrpStructuredRunResult(legacy)).toMatchObject({+ ok: true,+ result: { reportedWorkDisposition: "done" },+ });+ });++ it("restores the canonical schema discriminator omitted by a provider tool caller", () => {+ const withoutSchema = {+ reportedWorkDisposition: "done",+ summary: "Completed the requested work.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ { criterionId: "objective", status: "satisfied", evidenceRefs: [] },+ ],+ remainingWork: [],+ },+ evidence: [],+ verification: [],+ };+ expect(validatePrpStructuredRunResult(withoutSchema)).toMatchObject({+ ok: true,+ result: { schema: "paperclip.run_result.v1" },+ });+ });++ it("normalizes unambiguous completion aliases emitted by smaller tool callers", () => {+ const toolShaped = {+ schema: "paperclip_paperclip_finish",+ reportedWorkDisposition: "completed",+ summary: "Answered the question.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ { criterionId: "objective", status: "passed", evidenceRefs: [] },+ ],+ remainingWork: [],+ },+ evidence: [],+ verification: [],+ };+ expect(validatePrpStructuredRunResult(toolShaped)).toMatchObject({+ ok: true,+ result: {+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "done",+ completionClaim: {+ criteria: [{ status: "satisfied" }],+ },+ },+ });+ });++ it("normalizes unambiguous verification aliases from smaller tool callers", () => {+ expect(+ validatePrpStructuredRunResult({+ reportedWorkDisposition: "completed",+ summary: "Answered the question.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ { criterionId: "objective", status: "pass", evidenceRefs: [] },+ ],+ remainingWork: [],+ },+ evidence: [],+ verification: [{ commandOrCheck: "model check", status: "success" }],+ }),+ ).toMatchObject({+ ok: true,+ result: {+ verification: [{ commandOrCheck: "model check", status: "passed" }],+ },+ });+ });++ it("turns legacy environment_constraint attention into a verification caveat", () => {+ const normalized = normalizePrpResultSignals({+ verification: [+ {+ commandOrCheck: "Run npm test",+ status: "not_run",+ },+ ],+ attentionRequests: [+ {+ kind: "environment_constraint",+ summary: "Node and npm are unavailable in this sandbox.",+ },+ ],+ });++ expect(normalized.actionableAttentionRequests).toEqual([]);+ expect(normalized.verification).toEqual([+ expect.objectContaining({+ commandOrCheck: "Run npm test",+ status: "not_run",+ reasonCode: "tool_unavailable",+ detail: "Node and npm are unavailable in this sandbox.",+ }),+ ]);+ expect(normalized.ignoredAttentionRequests).toEqual([+ expect.objectContaining({+ sourceKind: "environment_constraint",+ disposition: "verification_caveat",+ reasonCode: "legacy_environment_constraint_normalized",+ }),+ ]);++ const canonical = normalizeLegacyPrpStructuredRunResult({+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "done",+ summary: "Work is complete; local verification was unavailable.",+ completionClaim: {+ contractRevision: "1",+ objectiveSatisfied: true,+ criteria: [+ { criterionId: "objective", status: "satisfied", evidenceRefs: [] },+ ],+ remainingWork: [],+ },+ evidence: [],+ verification: [+ {+ command: "npm test",+ status: "blocked",+ result: "Node is unavailable.",+ },+ ],+ attentionRequests: [+ {+ kind: "environment_constraint",+ summary: "Node and npm are unavailable in this sandbox.",+ },+ ],+ });+ expect(canonical).toMatchObject({+ attentionRequests: [],+ verification: [+ {+ commandOrCheck: "npm test",+ status: "not_run",+ reasonCode: "tool_unavailable",+ detail:+ "Node is unavailable.\nNode and npm are unavailable in this sandbox.",+ },+ ],+ });+ expect(validatePrpStructuredRunResult(canonical)).toMatchObject({+ ok: true,+ });+ });++ it("normalizes an unavailable command reported as failed into a not-run caveat", () => {+ const normalized = normalizePrpResultSignals({+ verification: [+ {+ commandOrCheck: "tsc --noEmit",+ status: "failed",+ reasonCode: "dependency_missing",+ detail:+ "Repository dependencies are not installed, so the compiler could not start.",+ },+ ],+ });++ expect(normalized.verification).toEqual([+ expect.objectContaining({+ commandOrCheck: "tsc --noEmit",+ status: "not_run",+ reasonCode: "dependency_missing",+ }),+ ]);+ });++ it("preserves typed actionable requests and legacy review requests", () => {+ const normalized = normalizePrpResultSignals({+ attentionRequests: [+ {+ kind: "approval",+ summary: "Approve publication",+ ownerClass: "human",+ },+ { kind: "review", summary: "Review the result" },+ ],+ });++ expect(normalized.actionableAttentionRequests).toEqual([+ expect.objectContaining({+ kind: "approval",+ ownerClass: "human",+ legacy: false,+ }),+ expect.objectContaining({+ kind: "review",+ ownerClass: "human",+ legacy: true,+ }),+ ]);+ });++ it("records unknown and malformed attention as diagnostics instead of throwing", () => {+ const normalized = normalizePrpResultSignals({+ attentionRequests: [+ { kind: "future_provider_value", summary: "Unknown request" },+ { kind: "approval" },+ null,+ ],+ });++ expect(normalized.actionableAttentionRequests).toEqual([]);+ expect(normalized.ignoredAttentionRequests).toEqual([+ expect.objectContaining({+ disposition: "ignored",+ reasonCode: "attention_request_kind_unsupported",+ }),+ expect.objectContaining({+ disposition: "rejected",+ reasonCode: "attention_request_malformed",+ }),+ expect.objectContaining({+ disposition: "rejected",+ reasonCode: "attention_request_malformed",+ }),+ ]);+ });+});diff --git a/packages/paperclip-runner/src/protocol/result-normalization.ts b/packages/paperclip-runner/src/protocol/result-normalization.tsnew file mode 100644index 0000000000..a172358c7b--- /dev/null+++ b/packages/paperclip-runner/src/protocol/result-normalization.ts@@ -0,0 +1,410 @@+import {+ PRP_ACTIONABLE_ATTENTION_KINDS,+ PRP_ATTENTION_OWNER_CLASSES,+ PRP_VERIFICATION_REASON_CODES,+} from "../contracts/completion-result.js";++export type PrpVerificationReasonCode =+ (typeof PRP_VERIFICATION_REASON_CODES)[number];+export type PrpActionableAttentionKind =+ (typeof PRP_ACTIONABLE_ATTENTION_KINDS)[number];+export type PrpAttentionOwnerClass =+ (typeof PRP_ATTENTION_OWNER_CLASSES)[number];++export interface PrpNormalizedVerification {+ commandOrCheck: string;+ status: "passed" | "failed" | "not_run";+ reasonCode: PrpVerificationReasonCode | null;+ detail: string | null;+ artifactRef: string | null;+ sourceIndex: number;+}++export interface PrpNormalizedAttentionRequest {+ kind: PrpActionableAttentionKind;+ summary: string;+ ownerClass: PrpAttentionOwnerClass;+ targetAgentId: string | null;+ sourceIndex: number;+ sourceKind: string;+ legacy: boolean;+}++export interface PrpIgnoredAttentionRequest {+ sourceIndex: number;+ sourceKind: string | null;+ summary: string | null;+ disposition: "verification_caveat" | "ignored" | "rejected";+ reasonCode: string;+}++export interface PrpResultSignals {+ verification: PrpNormalizedVerification[];+ actionableAttentionRequests: PrpNormalizedAttentionRequest[];+ ignoredAttentionRequests: PrpIgnoredAttentionRequest[];+}++const verificationReasonCodes = new Set<string>(PRP_VERIFICATION_REASON_CODES);+const unavailableVerificationReasonCodes = new Set<string>(+ PRP_VERIFICATION_REASON_CODES.filter((reasonCode) => reasonCode !== "other"),+);+const attentionKinds = new Set<string>(PRP_ACTIONABLE_ATTENTION_KINDS);+const ownerClasses = new Set<string>(PRP_ATTENTION_OWNER_CLASSES);++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): string | null {+ return typeof value === "string" && value.trim().length > 0+ ? value.trim()+ : null;+}++function inferVerificationReason(value: string): PrpVerificationReasonCode {+ const lower = value.toLowerCase();+ if (/budget|quota|token limit/.test(lower)) return "budget_exhausted";+ if (+ /credential|api key|secret|login|auth(?:entication)? required/.test(lower)+ )+ return "credential_missing";+ if (/permission|denied|forbidden|not allowed/.test(lower))+ return "permission_denied";+ if (/policy|governance|approval policy/.test(lower))+ return "policy_restricted";+ if (/external|service|upstream|network|offline|dns/.test(lower))+ return "external_service_unavailable";+ if (/dependency|package|module|library/.test(lower))+ return "dependency_missing";+ if (/tool|command|binary|node|npm|sandbox/.test(lower))+ return "tool_unavailable";+ if (/environment|runtime|platform/.test(lower))+ return "environment_unavailable";+ return "other";+}++function normalizeVerification(+ result: Record<string, unknown>,+): PrpNormalizedVerification[] {+ const entries = Array.isArray(result.verification) ? result.verification : [];+ return entries.map((value, sourceIndex) => {+ const entry = record(value);+ const rawStatus = String(entry.status);+ const reportedStatus: PrpNormalizedVerification["status"] = [+ "pass",+ "success",+ "succeeded",+ ].includes(rawStatus)+ ? "passed"+ : rawStatus === "fail"+ ? "failed"+ : ["passed", "failed", "not_run"].includes(rawStatus)+ ? (rawStatus as PrpNormalizedVerification["status"])+ : "not_run";+ const detail = text(entry.detail) ?? text(entry.result);+ const commandOrCheck =+ text(entry.commandOrCheck) ??+ text(entry.command) ??+ `verification-${sourceIndex + 1}`;+ const reportedReason = text(entry.reasonCode);+ const normalizedReportedReason =+ reportedReason && verificationReasonCodes.has(reportedReason)+ ? (reportedReason as PrpVerificationReasonCode)+ : null;+ // Provider models sometimes report an unavailable command as `failed`+ // because the shell returned non-zero, while also supplying a reason code+ // that explicitly says no meaningful verification verdict was possible.+ // The reason code is the stronger semantic signal: reserve `failed` for a+ // check that actually ran and found the work incorrect.+ const status =+ reportedStatus === "failed" &&+ normalizedReportedReason &&+ unavailableVerificationReasonCodes.has(normalizedReportedReason)+ ? "not_run"+ : reportedStatus;+ const reasonCode =+ normalizedReportedReason ??+ (status === "not_run"+ ? inferVerificationReason(`${commandOrCheck} ${detail ?? ""}`)+ : null);+ return {+ commandOrCheck,+ status,+ reasonCode,+ detail,+ artifactRef: text(entry.artifactRef),+ sourceIndex,+ };+ });+}++/** Normalize accepted PRP v1 aliases before strict canonical validation. */+export function normalizeLegacyPrpStructuredRunResult(value: unknown): unknown {+ const source = record(value);+ if (Object.keys(source).length === 0) return value;+ const normalized: Record<string, unknown> = { ...source };+ // Provider tool-callers do not consistently echo constant discriminator+ // fields even when they are present in the advertised JSON schema. The+ // transport already selected the semantic-result tool, so adding its+ // canonical discriminator here is deterministic rather than inferential.+ const reportedSchema = text(normalized.schema);+ if (+ reportedSchema === null ||+ [+ "paperclip_finish",+ "paperclip_paperclip_finish",+ "paperclip_finish.v1",+ ].includes(reportedSchema)+ ) {+ normalized.schema = "paperclip.run_result.v1";+ }+ const signals = normalizePrpResultSignals(source);+ if (+ ["complete", "completed"].includes(+ String(normalized.reportedWorkDisposition),+ )+ ) {+ normalized.reportedWorkDisposition = "done";+ }+ const completionClaim = record(normalized.completionClaim);+ if (Array.isArray(completionClaim.criteria)) {+ normalized.completionClaim = {+ ...completionClaim,+ criteria: completionClaim.criteria.map((value) => {+ const criterion = record(value);+ const reportedStatus = text(criterion.status);+ const status =+ reportedStatus &&+ ["pass", "passed", "complete", "completed"].includes(reportedStatus)+ ? "satisfied"+ : reportedStatus &&+ ["fail", "failed", "incomplete"].includes(reportedStatus)+ ? "not_satisfied"+ : criterion.status;+ return { ...criterion, status };+ }),+ };+ }+ normalized.attentionRequests = signals.actionableAttentionRequests.map(+ (entry) => ({+ kind: entry.kind,+ summary: entry.summary,+ ownerClass: entry.ownerClass,+ ...(entry.targetAgentId ? { targetAgentId: entry.targetAgentId } : {}),+ }),+ );+ normalized.artifacts = Array.isArray(source.artifacts)+ ? source.artifacts+ : [];+ normalized.verification = signals.verification.map((entry) => ({+ commandOrCheck: entry.commandOrCheck,+ status: entry.status,+ ...(entry.reasonCode ? { reasonCode: entry.reasonCode } : {}),+ ...(entry.detail ? { detail: entry.detail } : {}),+ ...(entry.artifactRef ? { artifactRef: entry.artifactRef } : {}),+ }));+ return normalized;+}++function legacyAttentionRequest(+ entry: Record<string, unknown>,+ sourceIndex: number,+ sourceKind: string,+ summary: string,+): PrpNormalizedAttentionRequest | null {+ const target = record(entry.target);+ const targetAgentId = text(entry.targetAgentId) ?? text(target.agentId);+ const ownerClass = text(entry.ownerClass) ?? text(target.ownerClass);+ const requiredAuthority = text(entry.requiredAuthority);+ switch (sourceKind) {+ case "credential_grant":+ return {+ kind: "credential",+ summary,+ ownerClass: "human",+ targetAgentId: null,+ sourceIndex,+ sourceKind,+ legacy: true,+ };+ case "governed_approval":+ return {+ kind: "approval",+ summary,+ ownerClass: "human",+ targetAgentId: null,+ sourceIndex,+ sourceKind,+ legacy: true,+ };+ case "subjective_decision":+ return {+ kind: "human_input",+ summary,+ ownerClass: "human",+ targetAgentId: null,+ sourceIndex,+ sourceKind,+ legacy: true,+ };+ case "domain_expertise":+ return targetAgentId+ ? {+ kind: "agent_handoff",+ summary,+ ownerClass: "agent",+ targetAgentId,+ sourceIndex,+ sourceKind,+ legacy: true,+ }+ : null;+ case "external_action":+ return {+ kind: "external_action",+ summary,+ ownerClass:+ ownerClass === "external_system" || requiredAuthority === "external"+ ? "external_system"+ : "human",+ targetAgentId: null,+ sourceIndex,+ sourceKind,+ legacy: true,+ };+ default:+ return null;+ }+}++/**+ * Normalize model-authored result signals without rewriting the immutable PRP result.+ * Unknown legacy attention is diagnostic data, never a finalization exception.+ */+export function normalizePrpResultSignals(value: unknown): PrpResultSignals {+ const result = record(value);+ const verification = normalizeVerification(result);+ const actionableAttentionRequests: PrpNormalizedAttentionRequest[] = [];+ const ignoredAttentionRequests: PrpIgnoredAttentionRequest[] = [];+ const requests = Array.isArray(result.attentionRequests)+ ? result.attentionRequests+ : [];++ requests.forEach((value, sourceIndex) => {+ const entry = record(value);+ const sourceKind = text(entry.kind) ?? text(entry.requestedCapability);+ const summary = text(entry.summary);+ if (!sourceKind || !summary) {+ ignoredAttentionRequests.push({+ sourceIndex,+ sourceKind,+ summary,+ disposition: "rejected",+ reasonCode: "attention_request_malformed",+ });+ return;+ }++ if (sourceKind === "environment_constraint") {+ const target = verification.find(+ (candidate) => candidate.status === "not_run",+ );+ if (target) {+ target.detail = target.detail+ ? target.detail.includes(summary)+ ? target.detail+ : `${target.detail}\n${summary}`+ : summary;+ target.reasonCode = inferVerificationReason(+ `${target.commandOrCheck} ${target.detail}`,+ );+ }+ ignoredAttentionRequests.push({+ sourceIndex,+ sourceKind,+ summary,+ disposition: "verification_caveat",+ reasonCode: target+ ? "legacy_environment_constraint_normalized"+ : "legacy_environment_constraint_unbound",+ });+ return;+ }++ if (attentionKinds.has(sourceKind) && text(entry.ownerClass)) {+ const ownerClass = text(entry.ownerClass);+ const targetAgentId = text(entry.targetAgentId);+ if (+ !ownerClass ||+ !ownerClasses.has(ownerClass) ||+ (ownerClass === "agent" && !targetAgentId)+ ) {+ ignoredAttentionRequests.push({+ sourceIndex,+ sourceKind,+ summary,+ disposition: "rejected",+ reasonCode: "attention_request_owner_invalid",+ });+ return;+ }+ actionableAttentionRequests.push({+ kind: sourceKind as PrpActionableAttentionKind,+ summary,+ ownerClass: ownerClass as PrpAttentionOwnerClass,+ targetAgentId,+ sourceIndex,+ sourceKind,+ legacy: false,+ });+ return;+ }++ if (sourceKind === "review") {+ actionableAttentionRequests.push({+ kind: "review",+ summary,+ ownerClass: "human",+ targetAgentId: null,+ sourceIndex,+ sourceKind,+ legacy: true,+ });+ return;+ }++ const legacy = legacyAttentionRequest(+ entry,+ sourceIndex,+ sourceKind,+ summary,+ );+ if (legacy) {+ actionableAttentionRequests.push(legacy);+ return;+ }++ ignoredAttentionRequests.push({+ sourceIndex,+ sourceKind,+ summary,+ disposition: "ignored",+ reasonCode: [+ "context_lookup",+ "retry",+ "duplicate",+ "alternate_track",+ ].includes(sourceKind)+ ? "attention_request_internal_capability_not_provider_actionable"+ : "attention_request_kind_unsupported",+ });+ });++ return {+ verification,+ actionableAttentionRequests,+ ignoredAttentionRequests,+ };+}diff --git a/packages/paperclip-runner/src/reducer/session-reducer.test.ts b/packages/paperclip-runner/src/reducer/session-reducer.test.tsnew file mode 100644index 0000000000..ed5c81807f--- /dev/null+++ b/packages/paperclip-runner/src/reducer/session-reducer.test.ts@@ -0,0 +1,147 @@+import { readFile } from "node:fs/promises";++import { describe, expect, it } from "vitest";++import {+ parsePrpFixtureText,+ type PrpEvent,+ type PrpFixture,+} from "../protocol/replay-contract.js";+import {+ createSessionSnapshot,+ MAX_RECORDED_MISSING_SEQUENCES,+ reducePrpFixture,+ reduceSessionEvents,+ type SessionSnapshot,+} from "./session-reducer.js";++const fixtureDirectory = new URL(+ "../../protocol/fixtures/replay/",+ import.meta.url,+);+const fixtureNames = [+ "happy-path",+ "failed-run",+ "interrupted-run",+ "duplicate-event",+ "source-gap",+ "unknown-optional-fields",+];++async function loadFixture(name: string): Promise<PrpFixture> {+ const result = parsePrpFixtureText(+ await readFile(new URL(`${name}.json`, fixtureDirectory), "utf8"),+ );+ if (!result.ok) {+ throw new Error(result.issues.map((issue) => issue.message).join("; "));+ }+ return result.fixture;+}++async function loadGolden(name: string): Promise<SessionSnapshot> {+ return JSON.parse(+ await readFile(+ new URL(`golden/${name}.snapshot.json`, fixtureDirectory),+ "utf8",+ ),+ ) as SessionSnapshot;+}++describe("deterministic PRP session reducer", () => {+ for (const fixtureName of fixtureNames) {+ it(`matches the ${fixtureName} golden snapshot`, async () => {+ expect(reducePrpFixture(await loadFixture(fixtureName))).toEqual(+ await loadGolden(fixtureName),+ );+ });+ }++ it("is deterministic and idempotent when the same batch is replayed", async () => {+ const fixture = await loadFixture("happy-path");+ const first = reducePrpFixture(fixture);+ expect(reducePrpFixture(fixture)).toEqual(first);+ expect(reduceSessionEvents(first, fixture.events)).toEqual(first);+ });++ it("deduplicates at-least-once delivery before projection effects", async () => {+ const snapshot = reducePrpFixture(await loadFixture("duplicate-event"));+ expect(snapshot.duplicateEventIds).toEqual(["event_duplicate_03"]);+ expect(snapshot.items).toHaveLength(1);+ expect(snapshot.timeline).toHaveLength(6);+ });++ it("records a source cursor gap without inventing the missing event", async () => {+ const snapshot = reducePrpFixture(await loadFixture("source-gap"));+ expect(snapshot.integrity).toBe("gap_detected");+ expect(snapshot.gaps).toEqual([+ {+ sourceKey: "runner:runner_replay",+ expected: 3,+ received: 4,+ missingCount: 1,+ missing: [3],+ truncated: false,+ },+ ]);+ });++ it("bounds sequence-gap details for an untrusted large cursor jump", async () => {+ const fixture = await loadFixture("source-gap");+ const event: PrpEvent = {+ ...fixture.events[0]!,+ sourceEventId: "event_large_gap",+ sourceSeq: Number.MAX_SAFE_INTEGER,+ };++ const snapshot = reduceSessionEvents(createSessionSnapshot(fixture), [+ event,+ ]);++ expect(snapshot.gaps).toHaveLength(1);+ expect(snapshot.gaps[0]).toMatchObject({+ expected: 1,+ received: Number.MAX_SAFE_INTEGER,+ missingCount: Number.MAX_SAFE_INTEGER - 1,+ truncated: true,+ });+ expect(snapshot.gaps[0]?.missing).toHaveLength(+ MAX_RECORDED_MISSING_SEQUENCES,+ );+ expect(snapshot.gaps[0]?.missing.at(-1)).toBe(+ MAX_RECORDED_MISSING_SEQUENCES,+ );+ });++ it("summarizes runtime request creation and resolution with type and prompt", async () => {+ const fixture = await loadFixture("interrupted-run");+ const fixtureRequest = fixture.events.find(+ (event) => event.eventType === "runtime_request.created",+ );+ if (fixtureRequest === undefined) {+ throw new Error("interrupted-run fixture must create a runtime request");+ }+ const created: PrpEvent = {+ ...fixtureRequest,+ sourceEventId: "event_request_summary_01",+ sourceSeq: 1,+ };+ const resolved: PrpEvent = {+ ...fixtureRequest,+ sourceEventId: "event_request_summary_02",+ sourceSeq: 2,+ eventType: "runtime_request.resolved",+ payload: { requestId: "request_interrupted_permission" },+ };++ const snapshot = reduceSessionEvents(createSessionSnapshot(fixture), [+ created,+ resolved,+ ]);++ expect(snapshot.requests[0]).toMatchObject({ type: "permission" });+ expect(snapshot.timeline.map((entry) => entry.summary)).toEqual([+ "permission: Allow the fake command?",+ "Resolved permission: Allow the fake command?",+ ]);+ });+});diff --git a/packages/paperclip-runner/src/reducer/session-reducer.ts b/packages/paperclip-runner/src/reducer/session-reducer.tsnew file mode 100644index 0000000000..88d7c1eb57--- /dev/null+++ b/packages/paperclip-runner/src/reducer/session-reducer.ts@@ -0,0 +1,440 @@+import type {+ PrpCapabilities,+ PrpEvent,+ PrpFixture,+ PrpIdentity,+ PrpStructuredRunResult,+ PrpTerminalState,+} from "../protocol/replay-contract.js";++export interface SessionTimelineEntry {+ position: number;+ sourceEventId: string;+ sourceSeq: number;+ eventType: PrpEvent["eventType"];+ emittedAt: string;+ itemId?: string;+ summary: string;+}++export interface SessionItemSnapshot {+ itemId: string;+ kind: string;+ status: "running" | "completed" | "failed";+ text: string;+}++export interface SessionRequestSnapshot {+ requestId: string;+ requestKind: string;+ type: string;+ status: string;+ prompt: string;+}++export interface SequenceGap {+ sourceKey: string;+ expected: number;+ received: number;+ missingCount: number;+ missing: number[];+ truncated: boolean;+}++export const MAX_RECORDED_MISSING_SEQUENCES = 256;++export interface SessionSnapshot {+ schema: "paperclip.prp.session-snapshot.v1";+ fixtureName: string;+ identity: PrpIdentity;+ capabilities: PrpCapabilities;+ runPhase: string;+ sessionState: "not_started" | "running" | "closed" | "failed";+ turnState:+ | "not_started"+ | "running"+ | "completed"+ | "failed"+ | "interrupted"+ | "cancelled";+ activeTurnId: string | null;+ items: SessionItemSnapshot[];+ requests: SessionRequestSnapshot[];+ proposedResult: PrpStructuredRunResult | null;+ terminal: PrpTerminalState | null;+ timeline: SessionTimelineEntry[];+ sourceCursors: Record<string, number>;+ processedEventIds: string[];+ duplicateEventIds: string[];+ outOfOrderEventIds: string[];+ gaps: SequenceGap[];+ integrity: "complete" | "gap_detected";+}++function record(value: unknown): Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value)+ ? (value as Record<string, unknown>)+ : {};+}++function stringValue(value: unknown, fallback = ""): string {+ return typeof value === "string" ? value : fallback;+}++function sourceKey(event: PrpEvent): string {+ return `${event.sourceKind}:${event.sourceInstanceId}`;+}++function humanizeProtocolValue(value: string): string {+ return value.replaceAll("_", " ");+}++function sentenceCase(value: string): string {+ return value.length === 0+ ? value+ : `${value[0]?.toUpperCase()}${value.slice(1)}`;+}++function requestSummary(type: string, prompt: string, action?: string): string {+ const detail = prompt.length > 0 ? `${type}: ${prompt}` : `${type} request`;+ return action === undefined ? detail : `${action} ${detail}`;+}++function timelineSummary(snapshot: SessionSnapshot, event: PrpEvent): string {+ const payload = record(event.payload);+ if (event.eventType === "runtime.phase.changed") {+ return `Phase changed to ${humanizeProtocolValue(stringValue(payload.phase, "unknown"))}`;+ }+ if (event.eventType === "item.started") {+ return `Started ${stringValue(payload.kind, "item")}`;+ }+ if (event.eventType === "item.delta") {+ return stringValue(payload.text, "Item updated");+ }+ if (event.eventType === "item.completed") {+ return `Completed ${stringValue(payload.kind, "item")}`;+ }+ if (event.eventType === "item.failed") {+ return stringValue(payload.message, "Item failed");+ }+ if (event.eventType === "run.result.proposed") {+ return stringValue(payload.summary, "Structured result proposed");+ }+ if (event.eventType === "run.terminal") {+ return `Run ${stringValue(payload.runTerminalState, "terminal")}`;+ }+ if (+ event.eventType === "runner.diagnostic" ||+ event.eventType === "harness.diagnostic"+ ) {+ const message = stringValue(payload.message);+ if (message.length > 0) {+ return message;+ }+ const code = stringValue(payload.code);+ if (code.length > 0) {+ return sentenceCase(humanizeProtocolValue(code));+ }+ }+ if (event.eventType === "runtime_request.created") {+ const request = record(payload.request ?? payload);+ return requestSummary(+ stringValue(request.type, "runtime"),+ stringValue(request.prompt),+ );+ }+ if (+ event.eventType === "runtime_request.resolved" ||+ event.eventType === "runtime_request.expired" ||+ event.eventType === "runtime_request.cancelled"+ ) {+ const requestId = stringValue(payload.requestId);+ const request = snapshot.requests.find(+ (candidate) => candidate.requestId === requestId,+ );+ const action = sentenceCase(+ humanizeProtocolValue(event.eventType.split(".").at(-1) ?? "updated"),+ );+ return request === undefined+ ? `${action} runtime request ${requestId}`.trim()+ : requestSummary(request.type, request.prompt, action);+ }+ return event.eventType.replaceAll(".", " ");+}++function upsertItem(+ items: SessionItemSnapshot[],+ event: PrpEvent,+ status: SessionItemSnapshot["status"],+): void {+ if (event.itemId === undefined) {+ return;+ }+ const payload = record(event.payload);+ const existing = items.find((item) => item.itemId === event.itemId);+ const text = stringValue(payload.text);+ if (existing === undefined) {+ items.push({+ itemId: event.itemId,+ kind: stringValue(payload.kind, "diagnostic"),+ status,+ text,+ });+ return;+ }+ existing.kind = stringValue(payload.kind, existing.kind);+ existing.status = status;+ if (event.eventType === "item.delta") {+ existing.text += text;+ } else if (text.length > 0) {+ existing.text = text;+ }+}++function applyProjection(snapshot: SessionSnapshot, event: PrpEvent): void {+ const payload = record(event.payload);+ switch (event.eventType) {+ case "runtime.phase.changed":+ snapshot.runPhase = stringValue(payload.phase, snapshot.runPhase);+ break;+ case "session.started":+ case "session.resumed":+ snapshot.sessionState = "running";+ break;+ case "session.closed":+ snapshot.sessionState = "closed";+ break;+ case "session.failed":+ snapshot.sessionState = "failed";+ break;+ case "turn.started":+ snapshot.turnState = "running";+ snapshot.activeTurnId = event.turnId ?? null;+ break;+ case "turn.completed":+ snapshot.turnState = "completed";+ snapshot.activeTurnId = null;+ break;+ case "turn.failed":+ snapshot.turnState = "failed";+ snapshot.activeTurnId = null;+ break;+ case "turn.interrupted":+ snapshot.turnState = "interrupted";+ snapshot.activeTurnId = null;+ break;+ case "turn.cancelled":+ snapshot.turnState = "cancelled";+ snapshot.activeTurnId = null;+ break;+ case "item.started":+ case "item.delta":+ upsertItem(snapshot.items, event, "running");+ break;+ case "item.completed":+ upsertItem(snapshot.items, event, "completed");+ break;+ case "item.failed":+ upsertItem(snapshot.items, event, "failed");+ break;+ case "runtime_request.created": {+ const request = record(payload.request ?? payload);+ const requestId = stringValue(request.requestId);+ if (+ requestId.length > 0 &&+ !snapshot.requests.some(+ (candidate) => candidate.requestId === requestId,+ )+ ) {+ snapshot.requests.push({+ requestId,+ requestKind: stringValue(request.requestKind, "runtime"),+ type: stringValue(request.type, "runtime"),+ status: stringValue(request.status, "pending"),+ prompt: stringValue(request.prompt),+ });+ }+ break;+ }+ case "runtime_request.resolved":+ case "runtime_request.expired":+ case "runtime_request.cancelled": {+ const requestId = stringValue(payload.requestId);+ const request = snapshot.requests.find(+ (candidate) => candidate.requestId === requestId,+ );+ if (request !== undefined) {+ request.status = event.eventType.split(".").at(-1) ?? request.status;+ }+ break;+ }+ case "run.result.proposed":+ snapshot.proposedResult = structuredClone(+ event.payload as PrpStructuredRunResult,+ );+ break;+ case "run.terminal":+ snapshot.terminal = structuredClone(event.payload as PrpTerminalState);+ snapshot.runPhase = "terminal";+ break;+ }+}++function addGap(+ snapshot: SessionSnapshot,+ event: PrpEvent,+ expected: number,+): void {+ const key = sourceKey(event);+ if (+ snapshot.gaps.some(+ (gap) =>+ gap.sourceKey === key &&+ gap.expected === expected &&+ gap.received === event.sourceSeq,+ )+ ) {+ return;+ }+ const missingCount = event.sourceSeq - expected;+ const recordedCount = Math.min(missingCount, MAX_RECORDED_MISSING_SEQUENCES);+ snapshot.gaps.push({+ sourceKey: key,+ expected,+ received: event.sourceSeq,+ missingCount,+ missing: Array.from(+ { length: recordedCount },+ (_, index) => expected + index,+ ),+ truncated: recordedCount < missingCount,+ });+}++export function createSessionSnapshot(fixture: PrpFixture): SessionSnapshot {+ return createSessionSnapshotFromMetadata({+ fixtureName: fixture.name,+ identity: fixture.identity,+ capabilities: fixture.capabilities,+ });+}++export function createSessionSnapshotFromMetadata(input: {+ fixtureName: string;+ identity: PrpIdentity;+ capabilities: PrpCapabilities;+}): SessionSnapshot {+ return {+ schema: "paperclip.prp.session-snapshot.v1",+ fixtureName: input.fixtureName,+ identity: structuredClone(input.identity),+ capabilities: structuredClone(input.capabilities),+ runPhase: "queued",+ sessionState: "not_started",+ turnState: "not_started",+ activeTurnId: null,+ items: [],+ requests: [],+ proposedResult: null,+ terminal: null,+ timeline: [],+ sourceCursors: {},+ processedEventIds: [],+ duplicateEventIds: [],+ outOfOrderEventIds: [],+ gaps: [],+ integrity: "complete",+ };+}++export function applyPrpEvent(+ current: SessionSnapshot,+ event: PrpEvent,+): SessionSnapshot {+ if (current.processedEventIds.includes(event.sourceEventId)) {+ return current;+ }++ const snapshot = structuredClone(current);+ const key = sourceKey(event);+ const cursor = snapshot.sourceCursors[key] ?? 0;+ const expected = cursor + 1;+ if (event.sourceSeq <= cursor) {+ if (!snapshot.outOfOrderEventIds.includes(event.sourceEventId)) {+ snapshot.outOfOrderEventIds.push(event.sourceEventId);+ }+ snapshot.integrity = "gap_detected";+ return snapshot;+ }+ if (event.sourceSeq > expected) {+ addGap(snapshot, event, expected);+ }++ snapshot.sourceCursors[key] = event.sourceSeq;+ snapshot.processedEventIds.push(event.sourceEventId);+ snapshot.timeline.push({+ position: snapshot.timeline.length + 1,+ sourceEventId: event.sourceEventId,+ sourceSeq: event.sourceSeq,+ eventType: event.eventType,+ emittedAt: event.emittedAt,+ ...(event.itemId === undefined ? {} : { itemId: event.itemId }),+ summary: timelineSummary(snapshot, event),+ });+ applyProjection(snapshot, event);+ snapshot.integrity =+ snapshot.gaps.length > 0 || snapshot.outOfOrderEventIds.length > 0+ ? "gap_detected"+ : "complete";+ return snapshot;+}++export function reduceSessionEvents(+ current: SessionSnapshot,+ events: readonly PrpEvent[],+): SessionSnapshot {+ const counts = new Map<string, number>();+ for (const event of events) {+ counts.set(event.sourceEventId, (counts.get(event.sourceEventId) ?? 0) + 1);+ }++ let snapshot = structuredClone(current);+ for (const [eventId, count] of counts) {+ if (count > 1 && !snapshot.duplicateEventIds.includes(eventId)) {+ snapshot.duplicateEventIds.push(eventId);+ }+ }+ snapshot.duplicateEventIds.sort();+ for (const event of events) {+ snapshot = applyPrpEvent(snapshot, event);+ }+ return snapshot;+}++export function reducePrpFixture(fixture: PrpFixture): SessionSnapshot {+ return reduceSessionEvents(createSessionSnapshot(fixture), fixture.events);+}++export interface ReplayParitySummary {+ runId: string;+ integrity: SessionSnapshot["integrity"];+ timelineCount: number;+ duplicateEventIds: string[];+ gaps: SequenceGap[];+ turnTerminalState: string | null;+ runTerminalState: string | null;+}++export function replayParitySummary(+ snapshot: SessionSnapshot,+): ReplayParitySummary {+ return {+ runId: snapshot.identity.runId,+ integrity: snapshot.integrity,+ timelineCount: snapshot.timeline.length,+ duplicateEventIds: [...snapshot.duplicateEventIds],+ gaps: structuredClone(snapshot.gaps),+ turnTerminalState: snapshot.terminal?.turnTerminalState ?? null,+ runTerminalState: snapshot.terminal?.runTerminalState ?? null,+ };+}diff --git a/packages/paperclip-runner/src/tracer/replay.test.ts b/packages/paperclip-runner/src/tracer/replay.test.tsnew file mode 100644index 0000000000..0917e8a471--- /dev/null+++ b/packages/paperclip-runner/src/tracer/replay.test.ts@@ -0,0 +1,26 @@+import { readFile } from "node:fs/promises";++import { describe, expect, it } from "vitest";++import { formatReplayResult, replayFixtureText } from "./replay.js";++describe("Replay tracer", () => {+ it("formats the validated reducer snapshot for CLI consumers", async () => {+ const source = await readFile(+ new URL(+ "../../protocol/fixtures/replay/happy-path.json",+ import.meta.url,+ ),+ "utf8",+ );+ const result = replayFixtureText(source);+ expect(result.ok).toBe(true);+ expect(JSON.parse(formatReplayResult(result))).toMatchObject({+ ok: true,+ snapshot: {+ integrity: "complete",+ terminal: { runTerminalState: "succeeded" },+ },+ });+ });+});diff --git a/packages/paperclip-runner/src/tracer/replay.ts b/packages/paperclip-runner/src/tracer/replay.tsnew file mode 100644index 0000000000..5a16ced024--- /dev/null+++ b/packages/paperclip-runner/src/tracer/replay.ts@@ -0,0 +1,28 @@+import {+ parsePrpFixtureText,+ type ProtocolValidationIssue,+} from "../protocol/replay-contract.js";+import {+ reducePrpFixture,+ type SessionSnapshot,+} from "../reducer/session-reducer.js";++export type ReplayResult =+ | { ok: true; snapshot: SessionSnapshot; issues: [] }+ | { ok: false; snapshot: null; issues: ProtocolValidationIssue[] };++export function replayFixtureText(text: string): ReplayResult {+ const validation = parsePrpFixtureText(text);+ if (!validation.ok) {+ return { ok: false, snapshot: null, issues: validation.issues };+ }+ return {+ ok: true,+ snapshot: reducePrpFixture(validation.fixture),+ issues: [],+ };+}++export function formatReplayResult(result: ReplayResult): string {+ return JSON.stringify(result, null, 2);+}diff --git a/packages/paperclip-runner/tsconfig.json b/packages/paperclip-runner/tsconfig.jsonnew file mode 100644index 0000000000..fd2a166a3c--- /dev/null+++ b/packages/paperclip-runner/tsconfig.json@@ -0,0 +1,10 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "lib": ["ES2023"],+ "outDir": "dist",+ "rootDir": "src"+ },+ "include": ["src/**/*.ts"],+ "exclude": ["src/**/*.test.ts"]+}diff --git a/packages/paperclip-runner/vitest.config.ts b/packages/paperclip-runner/vitest.config.tsnew file mode 100644index 0000000000..c1433e6ef3--- /dev/null+++ b/packages/paperclip-runner/vitest.config.ts@@ -0,0 +1,8 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ environment: "node",+ include: ["src/**/*.test.ts"],+ },+});