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
feat(runner): add PRP v1 schemas and fixtures (#12087)
Dottafdbc69172d6e
diff --git a/Dockerfile b/Dockerfileindex c41520df32..0e984a1640 100644--- a/Dockerfile+++ b/Dockerfile@@ -24,6 +24,7 @@ COPY packages/adapter-utils/package.json packages/adapter-utils/COPY packages/google-sheets-mcp-server/package.json packages/google-sheets-mcp-server/COPY packages/kv-demo-mcp-server/package.json packages/kv-demo-mcp-server/COPY packages/mcp-server/package.json packages/mcp-server/+COPY packages/paperclip-runner/package.json packages/paperclip-runner/COPY packages/skills-catalog/package.json packages/skills-catalog/COPY packages/tailscale-https-broker/package.json packages/tailscale-https-broker/COPY packages/teams-catalog/package.json packages/teams-catalog/diff --git a/packages/paperclip-runner/README.md b/packages/paperclip-runner/README.mdnew file mode 100644index 0000000000..efb874ce07--- /dev/null+++ b/packages/paperclip-runner/README.md@@ -0,0 +1,27 @@+# Paperclip Runner++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 first provider scope is Codex. The protocol contains provider-neutral event+and semantic receipt shapes, but their presence does not authorize a tool or+enable a provider.++Run the protocol gate with:++```sh+pnpm --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.++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.diff --git a/packages/paperclip-runner/package.json b/packages/paperclip-runner/package.jsonnew file mode 100644index 0000000000..c289744ee4--- /dev/null+++ b/packages/paperclip-runner/package.json@@ -0,0 +1,21 @@+{+ "name": "@paperclipai/paperclip-runner",+ "version": "0.0.0",+ "private": true,+ "license": "MIT",+ "engines": {+ "node": ">=24.11.0"+ },+ "type": "module",+ "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",+ "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"+ },+ "devDependencies": {+ "ajv": "^8.20.0"+ }+}diff --git a/packages/paperclip-runner/protocol/README.md b/packages/paperclip-runner/protocol/README.mdnew file mode 100644index 0000000000..405c2bbd34--- /dev/null+++ b/packages/paperclip-runner/protocol/README.md@@ -0,0 +1,32 @@+# PRP v1 Contract++The JSON Schema files in `schemas/` are the language-neutral source of truth for+Paperclip Runner Protocol version 1. The fixtures in `fixtures/` define accepted+and rejected compatibility cases.++## Compatibility++- `protocolVersion`, `fixtureVersion`, and `event.schemaVersion` are required.+- A consumer fails closed when a required version or schema discriminator is+ not supported.+- A v1 envelope can contain an unknown optional property when its schema marks+ that object as extensible.+- A consumer ignores an unknown optional property until a later contract gives+ it meaning.+- A required field, enum value, or typed structured-input field is not optional.+- Question and answer identifiers are stable across the provider boundary.++The `unknown-optional-fields.json` fixture must be accepted. The+`unsupported-required-version.json` fixture must be rejected.++## Scope++The first provider descriptor and adapter fixture cover Codex only. The schemas+for provider-neutral events and semantic receipts do not enable those actions.+Discovery and authorization are separate contracts.++The conformance manifest records every source file and its SHA-256 digest. Run+`pnpm generate:protocol-manifest` from this package after a source change. CI+runs the same generator with `--check` to reject drift. This check also compiles+the JSON Schemas and validates every replay, question, and cross-language+conformance fixture against its declared schema.diff --git a/packages/paperclip-runner/protocol/fixtures/conformance-expected-output.json b/packages/paperclip-runner/protocol/fixtures/conformance-expected-output.jsonnew file mode 100644index 0000000000..6dc9bc9aff--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/conformance-expected-output.json@@ -0,0 +1 @@+{"schemaVersion":"paperclip.runner.conformance.output.v1","runIdentity":{"runId":"run_conformance_0001","sessionId":"session_conformance_0001"},"result":{"status":"succeeded","summary":"Standalone Conformance fixture accepted."}}diff --git a/packages/paperclip-runner/protocol/fixtures/conformance-minimal-run.json b/packages/paperclip-runner/protocol/fixtures/conformance-minimal-run.jsonnew file mode 100644index 0000000000..ad6a9fc579--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/conformance-minimal-run.json@@ -0,0 +1,29 @@+{+ "schemaVersion": "paperclip.runner.conformance.fixture.v1",+ "run": {+ "runId": "run_conformance_0001",+ "sessionId": "session_conformance_0001",+ "companyId": "company_conformance",+ "issueId": "issue_conformance",+ "agentId": "agent_conformance"+ },+ "events": [+ {+ "eventId": "event_conformance_0001",+ "runId": "run_conformance_0001",+ "sequence": 1,+ "type": "run.started"+ },+ {+ "eventId": "event_conformance_0002",+ "runId": "run_conformance_0001",+ "sequence": 2,+ "type": "run.completed"+ }+ ],+ "result": {+ "runId": "run_conformance_0001",+ "status": "succeeded",+ "summary": "Standalone Conformance fixture accepted."+ }+}diff --git a/packages/paperclip-runner/protocol/fixtures/questions/codex.json b/packages/paperclip-runner/protocol/fixtures/questions/codex.jsonnew file mode 100644index 0000000000..d1ec06850f--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/questions/codex.json@@ -0,0 +1,40 @@+{+ "schema": "paperclip.question_adapter_fixture.v1",+ "adapter": "codex",+ "nativeRequest": {+ "method": "item/tool/requestUserInput",+ "params": {+ "title": "Deployment input",+ "questions": [{+ "id": "environment",+ "header": "Environment",+ "question": "Where should we deploy?",+ "options": [+ { "label": "Staging", "description": "Deploy to staging first." },+ { "label": "Production", "description": "Deploy directly to production." }+ ]+ }]+ }+ },+ "canonicalQuestionSet": {+ "schema": "paperclip.question_set.v1",+ "title": "Deployment input",+ "submitLabel": "Submit answers",+ "questions": [{+ "id": "environment",+ "header": "Environment",+ "prompt": "Where should we deploy?",+ "required": true,+ "answerMode": "single_select",+ "options": [+ { "id": "option-1", "label": "Staging", "description": "Deploy to staging first." },+ { "id": "option-2", "label": "Production", "description": "Deploy directly to production." }+ ]+ }]+ },+ "canonicalResponse": {+ "schema": "paperclip.question_response.v1",+ "answers": { "environment": { "selectedOptionIds": ["option-1"] } }+ },+ "nativeResponse": { "answers": { "environment": { "answers": ["Staging"] } } }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/duplicate-event.json b/packages/paperclip-runner/protocol/fixtures/replay/duplicate-event.jsonnew file mode 100644index 0000000000..4555eb448a--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/duplicate-event.json@@ -0,0 +1,30 @@+{+ "schema": "paperclip.prp.fixture.v1", "fixtureVersion": 1, "protocolVersion": 1,+ "name": "Duplicate event", "description": "At-least-once delivery repeats one source event without repeating its effect.",+ "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+ },+ "commands": [+ { "schema": "paperclip.prp.command.v1", "commandId": "command_duplicate_prepare", "controllerSeq": 1, "type": "run.prepare", "issuedAt": "2026-08-07T12:30:00.000Z", "payload": {} }+ ],+ "events": [+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_01", "sourceSeq": 1, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "eventType": "session.started", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:30:00.010Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_02", "sourceSeq": 2, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "turnId": "turn_replay_duplicate", "eventType": "turn.started", "schemaVersion": 1, "priority": 1, "emittedAt": "2026-08-07T12:30:00.020Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_03", "sourceSeq": 3, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "turnId": "turn_replay_duplicate", "itemId": "item_replay_duplicate", "eventType": "item.completed", "schemaVersion": 1, "priority": 1, "emittedAt": "2026-08-07T12:30:00.030Z", "payload": { "kind": "assistant_message", "text": "Exactly one projection." } },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_03", "sourceSeq": 3, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "turnId": "turn_replay_duplicate", "itemId": "item_replay_duplicate", "eventType": "item.completed", "schemaVersion": 1, "priority": 1, "emittedAt": "2026-08-07T12:30:00.030Z", "payload": { "kind": "assistant_message", "text": "Exactly one projection." } },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_04", "sourceSeq": 4, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "eventType": "run.result.proposed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:30:00.040Z",+ "payload": { "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": [] }+ },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_05", "sourceSeq": 5, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "turnId": "turn_replay_duplicate", "eventType": "turn.completed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:30:00.050Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_duplicate_06", "sourceSeq": 6, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_duplicate", "normalizedSessionId": "session_replay_duplicate", "eventType": "run.terminal", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:30:00.060Z", "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "completed", "runTerminalState": "succeeded", "reportedWorkDisposition": "done" } }+ ],+ "requests": [],+ "result": { "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": [] }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/failed-run.json b/packages/paperclip-runner/protocol/fixtures/replay/failed-run.jsonnew file mode 100644index 0000000000..8327cd5f5d--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/failed-run.json@@ -0,0 +1,106 @@+{+ "schema": "paperclip.prp.fixture.v1",+ "fixtureVersion": 1,+ "protocolVersion": 1,+ "name": "Failed run",+ "description": "The driver reports an item and turn failure before the run terminalizes.",+ "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+ },+ "commands": [+ {+ "schema": "paperclip.prp.command.v1",+ "commandId": "command_failed_prepare",+ "controllerSeq": 1,+ "type": "run.prepare",+ "issuedAt": "2026-08-07T12:10:00.000Z",+ "payload": {}+ },+ {+ "schema": "paperclip.prp.command.v1",+ "commandId": "command_failed_turn",+ "controllerSeq": 2,+ "type": "turn.start",+ "issuedAt": "2026-08-07T12:10:00.010Z",+ "payload": { "text": "Run failing scenario" }+ }+ ],+ "events": [+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_01", "sourceSeq": 1,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "eventType": "session.started", "schemaVersion": 1,+ "priority": 0, "emittedAt": "2026-08-07T12:10:00.020Z", "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_02", "sourceSeq": 2,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "turnId": "turn_replay_failed",+ "eventType": "turn.started", "schemaVersion": 1, "priority": 1,+ "emittedAt": "2026-08-07T12:10:00.030Z", "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_03", "sourceSeq": 3,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "turnId": "turn_replay_failed", "itemId": "item_failed_command",+ "eventType": "item.failed", "schemaVersion": 1, "priority": 0,+ "emittedAt": "2026-08-07T12:10:00.040Z", "payload": { "kind": "command", "message": "Command exited with code 1" }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_04", "sourceSeq": 4,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "turnId": "turn_replay_failed",+ "eventType": "run.result.proposed", "schemaVersion": 1, "priority": 0,+ "emittedAt": "2026-08-07T12:10:00.050Z",+ "payload": {+ "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" }+ }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_05", "sourceSeq": 5,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "turnId": "turn_replay_failed",+ "eventType": "turn.failed", "schemaVersion": 1, "priority": 0,+ "emittedAt": "2026-08-07T12:10:00.060Z", "payload": { "message": "Fake driver failure" }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_failed_06", "sourceSeq": 6,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_failed",+ "normalizedSessionId": "session_replay_failed", "eventType": "run.terminal", "schemaVersion": 1,+ "priority": 0, "emittedAt": "2026-08-07T12:10:00.070Z",+ "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "failed", "runTerminalState": "failed", "reportedWorkDisposition": "yielded" }+ }+ ],+ "requests": [],+ "result": {+ "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" }+ }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/happy-path.json b/packages/paperclip-runner/protocol/fixtures/replay/happy-path.jsonnew file mode 100644index 0000000000..c5f656d22e--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/happy-path.json@@ -0,0 +1,230 @@+{+ "schema": "paperclip.prp.fixture.v1",+ "fixtureVersion": 1,+ "protocolVersion": 1,+ "name": "Happy path",+ "description": "A typed assistant message completes and the run proposes a successful result.",+ "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": []+ },+ "commands": [+ {+ "schema": "paperclip.prp.command.v1",+ "commandId": "command_happy_prepare",+ "controllerSeq": 1,+ "type": "run.prepare",+ "issuedAt": "2026-08-07T12:00:00.000Z",+ "payload": { "workspace": "fixture" }+ },+ {+ "schema": "paperclip.prp.command.v1",+ "commandId": "command_happy_session",+ "controllerSeq": 2,+ "type": "session.open",+ "issuedAt": "2026-08-07T12:00:00.010Z",+ "payload": { "reuse": "new_per_run" }+ },+ {+ "schema": "paperclip.prp.command.v1",+ "commandId": "command_happy_turn",+ "controllerSeq": 3,+ "type": "turn.start",+ "issuedAt": "2026-08-07T12:00:00.020Z",+ "payload": { "text": "Inspect the fixture" }+ }+ ],+ "events": [+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_01",+ "sourceSeq": 1,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "eventType": "runtime.phase.changed",+ "schemaVersion": 1,+ "priority": 1,+ "emittedAt": "2026-08-07T12:00:00.030Z",+ "payload": { "phase": "workspace_preparing" }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_02",+ "sourceSeq": 2,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "eventType": "session.started",+ "schemaVersion": 1,+ "priority": 0,+ "emittedAt": "2026-08-07T12:00:00.040Z",+ "payload": { "driverSessionId": "driver_replay_happy" }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_03",+ "sourceSeq": 3,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "eventType": "turn.started",+ "schemaVersion": 1,+ "priority": 1,+ "emittedAt": "2026-08-07T12:00:00.050Z",+ "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_04",+ "sourceSeq": 4,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "itemId": "item_replay_message",+ "eventType": "item.started",+ "schemaVersion": 1,+ "priority": 1,+ "emittedAt": "2026-08-07T12:00:00.060Z",+ "payload": { "kind": "assistant_message", "text": "" }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_05",+ "sourceSeq": 5,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "itemId": "item_replay_message",+ "eventType": "item.delta",+ "schemaVersion": 1,+ "priority": 2,+ "emittedAt": "2026-08-07T12:00:00.070Z",+ "payload": { "text": "Validated fixture. " }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_06",+ "sourceSeq": 6,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "itemId": "item_replay_message",+ "eventType": "item.completed",+ "schemaVersion": 1,+ "priority": 1,+ "emittedAt": "2026-08-07T12:00:00.080Z",+ "payload": { "kind": "assistant_message", "text": "Validated fixture. Replay complete." }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_07",+ "sourceSeq": 7,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "eventType": "run.result.proposed",+ "schemaVersion": 1,+ "priority": 0,+ "emittedAt": "2026-08-07T12:00:00.090Z",+ "payload": {+ "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": []+ }+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_08",+ "sourceSeq": 8,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "turnId": "turn_replay_happy",+ "eventType": "turn.completed",+ "schemaVersion": 1,+ "priority": 0,+ "emittedAt": "2026-08-07T12:00:00.100Z",+ "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1",+ "sourceEventId": "event_happy_09",+ "sourceSeq": 9,+ "sourceInstanceId": "runner_replay",+ "sourceKind": "runner",+ "runId": "run_replay_happy",+ "normalizedSessionId": "session_replay_happy",+ "eventType": "run.terminal",+ "schemaVersion": 1,+ "priority": 0,+ "emittedAt": "2026-08-07T12:00:00.110Z",+ "payload": {+ "schema": "paperclip.prp.terminal.v1",+ "turnTerminalState": "completed",+ "runTerminalState": "succeeded",+ "reportedWorkDisposition": "done",+ "workAssessmentId": "assessment_replay_happy",+ "statusDecisionId": "decision_replay_happy"+ }+ }+ ],+ "requests": [],+ "result": {+ "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": []+ }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/interrupted-run.json b/packages/paperclip-runner/protocol/fixtures/replay/interrupted-run.jsonnew file mode 100644index 0000000000..26bf4ed3aa--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/interrupted-run.json@@ -0,0 +1,90 @@+{+ "schema": "paperclip.prp.fixture.v1",+ "fixtureVersion": 1,+ "protocolVersion": 1,+ "name": "Interrupted run",+ "description": "A pending runtime permission request is followed by an explicit turn interruption.",+ "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+ },+ "commands": [+ {+ "schema": "paperclip.prp.command.v1", "commandId": "command_interrupted_prepare", "controllerSeq": 1,+ "type": "run.prepare", "issuedAt": "2026-08-07T12:20:00.000Z", "payload": {}+ },+ {+ "schema": "paperclip.prp.command.v1", "commandId": "command_interrupted_turn", "controllerSeq": 2,+ "type": "turn.start", "issuedAt": "2026-08-07T12:20:00.010Z", "payload": { "text": "Wait for interruption" }+ },+ {+ "schema": "paperclip.prp.command.v1", "commandId": "command_interrupted_interrupt", "controllerSeq": 3,+ "type": "turn.interrupt", "issuedAt": "2026-08-07T12:20:00.050Z", "payload": { "reason": "operator" }+ }+ ],+ "events": [+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_01", "sourceSeq": 1,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "eventType": "session.started", "schemaVersion": 1,+ "priority": 0, "emittedAt": "2026-08-07T12:20:00.020Z", "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_02", "sourceSeq": 2,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "turnId": "turn_replay_interrupted",+ "eventType": "turn.started", "schemaVersion": 1, "priority": 1,+ "emittedAt": "2026-08-07T12:20:00.030Z", "payload": {}+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_03", "sourceSeq": 3,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "turnId": "turn_replay_interrupted",+ "eventType": "runtime_request.created", "schemaVersion": 1, "priority": 0,+ "emittedAt": "2026-08-07T12:20:00.040Z",+ "payload": { "request": { "schema": "paperclip.runtime_request.v1", "requestKind": "runtime", "requestId": "request_interrupted_permission", "type": "permission", "status": "pending", "prompt": "Allow the fake command?" } }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_04", "sourceSeq": 4,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "turnId": "turn_replay_interrupted",+ "eventType": "turn.interrupted", "schemaVersion": 1, "priority": 0,+ "emittedAt": "2026-08-07T12:20:00.060Z", "payload": { "reason": "operator" }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_05", "sourceSeq": 5,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "eventType": "run.result.proposed", "schemaVersion": 1,+ "priority": 0, "emittedAt": "2026-08-07T12:20:00.070Z",+ "payload": {+ "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" }+ }+ },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_interrupted_06", "sourceSeq": 6,+ "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_interrupted",+ "normalizedSessionId": "session_replay_interrupted", "eventType": "run.terminal", "schemaVersion": 1,+ "priority": 0, "emittedAt": "2026-08-07T12:20:00.080Z",+ "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "interrupted", "runTerminalState": "cancelled", "reportedWorkDisposition": "yielded" }+ }+ ],+ "requests": [+ { "schema": "paperclip.runtime_request.v1", "requestKind": "runtime", "requestId": "request_interrupted_permission", "type": "permission", "status": "pending", "prompt": "Allow the fake command?" }+ ],+ "result": {+ "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" }+ }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/source-gap.json b/packages/paperclip-runner/protocol/fixtures/replay/source-gap.jsonnew file mode 100644index 0000000000..130e88e22d--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/source-gap.json@@ -0,0 +1,19 @@+{+ "schema": "paperclip.prp.fixture.v1", "fixtureVersion": 1, "protocolVersion": 1,+ "name": "Source sequence gap", "description": "The runner stream skips source sequence 3 and replay records the missing cursor.",+ "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 },+ "commands": [{ "schema": "paperclip.prp.command.v1", "commandId": "command_gap_prepare", "controllerSeq": 1, "type": "run.prepare", "issuedAt": "2026-08-07T12:40:00.000Z", "payload": {} }],+ "events": [+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_gap_01", "sourceSeq": 1, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_gap", "normalizedSessionId": "session_replay_gap", "eventType": "session.started", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:40:00.010Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_gap_02", "sourceSeq": 2, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_gap", "normalizedSessionId": "session_replay_gap", "turnId": "turn_replay_gap", "eventType": "turn.started", "schemaVersion": 1, "priority": 1, "emittedAt": "2026-08-07T12:40:00.020Z", "payload": {} },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_gap_04", "sourceSeq": 4, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_gap", "normalizedSessionId": "session_replay_gap", "eventType": "run.result.proposed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:40:00.040Z",+ "payload": { "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": [] }+ },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_gap_05", "sourceSeq": 5, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_gap", "normalizedSessionId": "session_replay_gap", "turnId": "turn_replay_gap", "eventType": "turn.completed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:40:00.050Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_gap_06", "sourceSeq": 6, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_gap", "normalizedSessionId": "session_replay_gap", "eventType": "run.terminal", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:40:00.060Z", "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "completed", "runTerminalState": "succeeded", "reportedWorkDisposition": "needs_review" } }+ ],+ "requests": [],+ "result": { "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": [] }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/unknown-optional-fields.json b/packages/paperclip-runner/protocol/fixtures/replay/unknown-optional-fields.jsonnew file mode 100644index 0000000000..0a51d2ab44--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/unknown-optional-fields.json@@ -0,0 +1,19 @@+{+ "schema": "paperclip.prp.fixture.v1", "fixtureVersion": 1, "protocolVersion": 1,+ "name": "Unknown optional fields", "description": "A future producer adds optional fields that a PRP v1 consumer preserves and ignores safely.",+ "futureFixtureHint": { "producerVersion": "1.1-preview" },+ "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" } },+ "commands": [{ "schema": "paperclip.prp.command.v1", "commandId": "command_future_prepare", "controllerSeq": 1, "type": "run.prepare", "issuedAt": "2026-08-07T12:50:00.000Z", "payload": {}, "futureDeadlineMode": "soft" }],+ "events": [+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_future_01", "sourceSeq": 1, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_future", "normalizedSessionId": "session_replay_future", "eventType": "session.started", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:50:00.010Z", "payload": { "futureSessionDetail": "ignored" }, "futureEnvelopeField": 42 },+ {+ "schema": "paperclip.prp.event.v1", "sourceEventId": "event_future_02", "sourceSeq": 2, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_future", "normalizedSessionId": "session_replay_future", "eventType": "run.result.proposed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:50:00.020Z",+ "payload": { "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 } }+ },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_future_03", "sourceSeq": 3, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_future", "normalizedSessionId": "session_replay_future", "turnId": "turn_replay_future", "eventType": "turn.completed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:50:00.030Z", "payload": {} },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_future_04", "sourceSeq": 4, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_future", "normalizedSessionId": "session_replay_future", "eventType": "run.terminal", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T12:50:00.040Z", "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "completed", "runTerminalState": "succeeded", "reportedWorkDisposition": "done", "futureTerminalReason": "optional" } }+ ],+ "requests": [],+ "result": { "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 } }+}diff --git a/packages/paperclip-runner/protocol/fixtures/replay/unsupported-required-version.json b/packages/paperclip-runner/protocol/fixtures/replay/unsupported-required-version.jsonnew file mode 100644index 0000000000..f8c63b4e46--- /dev/null+++ b/packages/paperclip-runner/protocol/fixtures/replay/unsupported-required-version.json@@ -0,0 +1,13 @@+{+ "schema": "paperclip.prp.fixture.v1", "fixtureVersion": 1, "protocolVersion": 2,+ "name": "Unsupported required version", "description": "A fixture that requires PRP v2 must fail closed in a PRP v1 consumer.",+ "identity": { "schema": "paperclip.prp.identity.v1", "companyId": "company_replay", "issueId": "issue_replay_v2", "runId": "run_replay_v2", "environmentLeaseId": "lease_replay_v2", "runnerInstanceId": "runner_replay", "normalizedSessionId": "session_replay_v2", "driverSessionId": "driver_replay_v2" },+ "capabilities": { "schema": "paperclip.prp.capabilities.v1", "sessionReusePolicy": "new_per_run", "driver": { "kind": "future", "version": "2.0.0" }, "steer": true, "interrupt": true, "resume": true, "runtimeRequests": true, "structuredResult": true, "typedEvents": true },+ "commands": [{ "schema": "paperclip.prp.command.v1", "commandId": "command_v2_prepare", "controllerSeq": 1, "type": "run.prepare", "issuedAt": "2026-08-07T13:00:00.000Z", "payload": {} }],+ "events": [+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_v2_01", "sourceSeq": 1, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_v2", "normalizedSessionId": "session_replay_v2", "eventType": "run.result.proposed", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T13:00:00.010Z", "payload": { "schema": "paperclip.run_result.v1", "reportedWorkDisposition": "done", "summary": "This result requires PRP v2.", "completionClaim": { "contractRevision": "replay-contract-v2", "objectiveSatisfied": true, "criteria": [], "remainingWork": [] }, "evidence": [], "verification": [], "attentionRequests": [], "artifacts": [] } },+ { "schema": "paperclip.prp.event.v1", "sourceEventId": "event_v2_02", "sourceSeq": 2, "sourceInstanceId": "runner_replay", "sourceKind": "runner", "runId": "run_replay_v2", "normalizedSessionId": "session_replay_v2", "eventType": "run.terminal", "schemaVersion": 1, "priority": 0, "emittedAt": "2026-08-07T13:00:00.020Z", "payload": { "schema": "paperclip.prp.terminal.v1", "turnTerminalState": "completed", "runTerminalState": "succeeded", "reportedWorkDisposition": "done" } }+ ],+ "requests": [],+ "result": { "schema": "paperclip.run_result.v1", "reportedWorkDisposition": "done", "summary": "This result requires PRP v2.", "completionClaim": { "contractRevision": "replay-contract-v2", "objectiveSatisfied": true, "criteria": [], "remainingWork": [] }, "evidence": [], "verification": [], "attentionRequests": [], "artifacts": [] }+}diff --git a/packages/paperclip-runner/protocol/manifest.json b/packages/paperclip-runner/protocol/manifest.jsonnew file mode 100644index 0000000000..7aded07243--- /dev/null+++ b/packages/paperclip-runner/protocol/manifest.json@@ -0,0 +1,173 @@+{+ "schema": "paperclip.prp.contract_manifest.v1",+ "protocolVersion": 1,+ "fixtureVersion": 1,+ "generatedFrom": [+ "protocol/schemas",+ "protocol/fixtures"+ ],+ "schemas": [+ {+ "path": "schemas/capabilities.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/capabilities.schema.json",+ "sha256": "e62a80328e5edde136b35463033280922ac2220575a83046b07fe034d233db88"+ },+ {+ "path": "schemas/command.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/command.schema.json",+ "sha256": "fc813e6b4d5b7e6890b496bd69848ada25dba58adbf7cf04163ca9e9bf2bcb79"+ },+ {+ "path": "schemas/conformance-fixture.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/conformance-fixture.schema.json",+ "sha256": "0febc66d128da1f251f9e932d78353a67f47ee60b7427e0a347c287bb6b7ea79"+ },+ {+ "path": "schemas/conformance-output.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/conformance-output.schema.json",+ "sha256": "96f78846dffc4a8300184751b9943214506f32ee1f393c6c0c453b666cf12d59"+ },+ {+ "path": "schemas/event.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/event.schema.json",+ "sha256": "b930af4a187c26312b4fff66813498b95332cb4e972f8b9282cdceafdf0de32c"+ },+ {+ "path": "schemas/fixture.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/fixture.schema.json",+ "sha256": "8ac87c2d8c639981277b5f72b9757a95badf85ff482d11596e4c63e01c616cba"+ },+ {+ "path": "schemas/identity.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/identity.schema.json",+ "sha256": "8a8a1943f14c739284daa241c5189f3b8026c050472c4f9909897456da506f48"+ },+ {+ "path": "schemas/provider-descriptor.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/provider-descriptor.schema.json",+ "sha256": "26e8af9314f1ca49578bfbacdcc111332225b422ea4ff68918a25ddac59129a6"+ },+ {+ "path": "schemas/provider-event.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/provider-event.schema.json",+ "sha256": "84521ea87ae782a7c07d1ef68b70f87fc4c436e79951a8076b7ba55e923fa88b"+ },+ {+ "path": "schemas/question-adapter-fixture.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/question-adapter-fixture.schema.json",+ "sha256": "002062abb4df9a98c92003eb4af43afbe8bdedd15d08b8697ad221fcc28ad9c7"+ },+ {+ "path": "schemas/question-response.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/question-response.schema.json",+ "sha256": "dec308b0daa4d882deb3878a1ad6ae5360f3342060f63ca636d65d1d9af1e055"+ },+ {+ "path": "schemas/question-set.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/question-set.schema.json",+ "sha256": "3bda40311ae3153bbf9d4a8c59f716680e17d711a4db3570193963918359751c"+ },+ {+ "path": "schemas/request.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/request.schema.json",+ "sha256": "bd41f01c00eddc1b635d3131a7183ddb616ff8fe68d5e348ddd9593a674c8d8e"+ },+ {+ "path": "schemas/result.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/result.schema.json",+ "sha256": "90f02c0a96e8ab9f75970fd788b61c18ccbd9abbd005bedfba280701729adce0"+ },+ {+ "path": "schemas/semantic-tool.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/semantic-tool.schema.json",+ "sha256": "f53f6832c0d65caaccf540662fdb08cf62d9bab45a18def7b559c4068ef54efc"+ },+ {+ "path": "schemas/stop-reason.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/stop-reason.schema.json",+ "sha256": "ed0c0807904ff1198273458057e1a565e828dba499372c0c80e2c69a1d600a13"+ },+ {+ "path": "schemas/terminal.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/terminal.schema.json",+ "sha256": "e9093399ac6422e77b060269910ffaba9a3d574ed578832821e310a0582edffd"+ },+ {+ "path": "schemas/usage.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/usage.schema.json",+ "sha256": "28fdbb3202095144649dddc438e6270c66d599c6f7e86838687f58d644726456"+ },+ {+ "path": "schemas/workspace-diff.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/workspace-diff.schema.json",+ "sha256": "f71b21f41cfc4c40aeaa503d1981d29355b4dd8b15036fcf3d8df5c35f8b8f6f"+ },+ {+ "path": "schemas/workspace-file-reference.schema.json",+ "id": "https://paperclip.dev/schemas/prp/v1/workspace-file-reference.schema.json",+ "sha256": "0ab57e76c9710f520ed9d15cc5d0f25c68176beff3aff556ad62dba9b922eb23"+ }+ ],+ "fixtures": [+ {+ "path": "fixtures/conformance-expected-output.json",+ "sha256": "5a643639c9df0a2925ba95c5c5dfa2217605018bfa0dd3954ab4aca5fcfdc2c6",+ "expectation": "accept",+ "compatibilityCase": "cross-language-output"+ },+ {+ "path": "fixtures/conformance-minimal-run.json",+ "sha256": "1e4304bcb51c3d7aa0575cf47b1ff3901700a254a60cf7432003ce9af0175e3a",+ "expectation": "accept",+ "compatibilityCase": "cross-language-input"+ },+ {+ "path": "fixtures/questions/codex.json",+ "sha256": "ad673b6f9d70b74b53656e622d15fad1a66430f39d62b9ef71479d194a198bd6",+ "expectation": "accept",+ "compatibilityCase": "codex-structured-input"+ },+ {+ "path": "fixtures/replay/duplicate-event.json",+ "sha256": "779c146966d2825ffcde88bfff8b1fb238c162d40c578980ad3bd1a7def405d7",+ "expectation": "accept",+ "compatibilityCase": "canonical"+ },+ {+ "path": "fixtures/replay/failed-run.json",+ "sha256": "59281021b6ff11e4765213043580fc91eca8a02bedb3fe0c012bef9ad807da12",+ "expectation": "accept",+ "compatibilityCase": "canonical"+ },+ {+ "path": "fixtures/replay/happy-path.json",+ "sha256": "dfe0aeb4e7a217f8d375afe6e6d1ab0151bb8e81921b07ae0aaa6c4d0b8f8a1d",+ "expectation": "accept",+ "compatibilityCase": "canonical"+ },+ {+ "path": "fixtures/replay/interrupted-run.json",+ "sha256": "2056789605ffde847b3272e751226ce4be61527f6aaa4fe3f5557a621af0ad5c",+ "expectation": "accept",+ "compatibilityCase": "canonical"+ },+ {+ "path": "fixtures/replay/source-gap.json",+ "sha256": "d8a3eb2861e8198226360e666e5296ff5d7215f81d255a273b21d2bfe7dcc2ef",+ "expectation": "accept",+ "compatibilityCase": "canonical"+ },+ {+ "path": "fixtures/replay/unknown-optional-fields.json",+ "sha256": "4dbc4b70c299fe21791ca66949f3cb189c8f76514b62c52f5f40a489a84515c4",+ "expectation": "accept",+ "compatibilityCase": "additive-optional-fields"+ },+ {+ "path": "fixtures/replay/unsupported-required-version.json",+ "sha256": "60ac964d2cf49dc80ada0cb9c946b25952f3e2be10719801d3f2f8bd98d27699",+ "expectation": "reject",+ "compatibilityCase": "unknown-required-version"+ }+ ]+}diff --git a/packages/paperclip-runner/protocol/schemas/capabilities.schema.json b/packages/paperclip-runner/protocol/schemas/capabilities.schema.jsonnew file mode 100644index 0000000000..fdaf331bb5--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/capabilities.schema.json@@ -0,0 +1,98 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/command.schema.json b/packages/paperclip-runner/protocol/schemas/command.schema.jsonnew file mode 100644index 0000000000..b6ae97cca7--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/command.schema.json@@ -0,0 +1,48 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/conformance-fixture.schema.json b/packages/paperclip-runner/protocol/schemas/conformance-fixture.schema.jsonnew file mode 100644index 0000000000..cae7cd0b4b--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/conformance-fixture.schema.json@@ -0,0 +1,51 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/conformance-fixture.schema.json",+ "title": "Paperclip Runner cross-language conformance fixture",+ "type": "object",+ "required": ["schemaVersion", "run", "events", "result"],+ "properties": {+ "schemaVersion": { "const": "paperclip.runner.conformance.fixture.v1" },+ "run": {+ "type": "object",+ "required": ["runId", "sessionId", "companyId", "issueId", "agentId"],+ "properties": {+ "runId": { "$ref": "#/$defs/id" },+ "sessionId": { "$ref": "#/$defs/id" },+ "companyId": { "$ref": "#/$defs/id" },+ "issueId": { "$ref": "#/$defs/id" },+ "agentId": { "$ref": "#/$defs/id" }+ },+ "additionalProperties": true+ },+ "events": {+ "type": "array",+ "minItems": 1,+ "items": {+ "type": "object",+ "required": ["eventId", "runId", "sequence", "type"],+ "properties": {+ "eventId": { "$ref": "#/$defs/id" },+ "runId": { "$ref": "#/$defs/id" },+ "sequence": { "type": "integer", "minimum": 1 },+ "type": { "enum": ["run.started", "run.completed"] }+ },+ "additionalProperties": true+ }+ },+ "result": {+ "type": "object",+ "required": ["runId", "status", "summary"],+ "properties": {+ "runId": { "$ref": "#/$defs/id" },+ "status": { "enum": ["succeeded", "failed", "interrupted"] },+ "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }+ },+ "additionalProperties": true+ }+ },+ "$defs": {+ "id": { "type": "string", "minLength": 1, "maxLength": 160 }+ },+ "additionalProperties": true+}diff --git a/packages/paperclip-runner/protocol/schemas/conformance-output.schema.json b/packages/paperclip-runner/protocol/schemas/conformance-output.schema.jsonnew file mode 100644index 0000000000..e348c75e4a--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/conformance-output.schema.json@@ -0,0 +1,32 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/prp/v1/conformance-output.schema.json",+ "title": "Paperclip Runner cross-language conformance output",+ "type": "object",+ "required": ["schemaVersion", "runIdentity", "result"],+ "properties": {+ "schemaVersion": { "const": "paperclip.runner.conformance.output.v1" },+ "runIdentity": {+ "type": "object",+ "required": ["runId", "sessionId"],+ "properties": {+ "runId": { "$ref": "#/$defs/id" },+ "sessionId": { "$ref": "#/$defs/id" }+ },+ "additionalProperties": true+ },+ "result": {+ "type": "object",+ "required": ["status", "summary"],+ "properties": {+ "status": { "enum": ["succeeded", "failed", "interrupted"] },+ "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }+ },+ "additionalProperties": true+ }+ },+ "$defs": {+ "id": { "type": "string", "minLength": 1, "maxLength": 160 }+ },+ "additionalProperties": true+}diff --git a/packages/paperclip-runner/protocol/schemas/event.schema.json b/packages/paperclip-runner/protocol/schemas/event.schema.jsonnew file mode 100644index 0000000000..332e70b396--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/event.schema.json@@ -0,0 +1,173 @@+{+ "$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 },+ "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+}diff --git a/packages/paperclip-runner/protocol/schemas/fixture.schema.json b/packages/paperclip-runner/protocol/schemas/fixture.schema.jsonnew file mode 100644index 0000000000..18d33ade54--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/fixture.schema.json@@ -0,0 +1,42 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/identity.schema.json b/packages/paperclip-runner/protocol/schemas/identity.schema.jsonnew file mode 100644index 0000000000..8279ef857c--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/identity.schema.json@@ -0,0 +1,36 @@+{+ "$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._:-]*$"+ }+ }+}diff --git a/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json b/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.jsonnew file mode 100644index 0000000000..3bfbb66a06--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/provider-descriptor.schema.json@@ -0,0 +1,17 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/provider-event.schema.json b/packages/paperclip-runner/protocol/schemas/provider-event.schema.jsonnew file mode 100644index 0000000000..8af5200ddf--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/provider-event.schema.json@@ -0,0 +1,167 @@+{+ "$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+ }+ }+}diff --git a/packages/paperclip-runner/protocol/schemas/question-adapter-fixture.schema.json b/packages/paperclip-runner/protocol/schemas/question-adapter-fixture.schema.jsonnew file mode 100644index 0000000000..04715dd336--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/question-adapter-fixture.schema.json@@ -0,0 +1,16 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/question-response.schema.json b/packages/paperclip-runner/protocol/schemas/question-response.schema.jsonnew file mode 100644index 0000000000..f089054853--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/question-response.schema.json@@ -0,0 +1,28 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/question-set.schema.json b/packages/paperclip-runner/protocol/schemas/question-set.schema.jsonnew file mode 100644index 0000000000..995bfa8f72--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/question-set.schema.json@@ -0,0 +1,90 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/request.schema.json b/packages/paperclip-runner/protocol/schemas/request.schema.jsonnew file mode 100644index 0000000000..78441bc7bf--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/request.schema.json@@ -0,0 +1,79 @@+{+ "$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+ }+ ]+}diff --git a/packages/paperclip-runner/protocol/schemas/result.schema.json b/packages/paperclip-runner/protocol/schemas/result.schema.jsonnew file mode 100644index 0000000000..62983b280e--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/result.schema.json@@ -0,0 +1,151 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/semantic-tool.schema.json b/packages/paperclip-runner/protocol/schemas/semantic-tool.schema.jsonnew file mode 100644index 0000000000..657a7e4e9f--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/semantic-tool.schema.json@@ -0,0 +1,164 @@+{+ "$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+ }+ }+}diff --git a/packages/paperclip-runner/protocol/schemas/stop-reason.schema.json b/packages/paperclip-runner/protocol/schemas/stop-reason.schema.jsonnew file mode 100644index 0000000000..183615f559--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/stop-reason.schema.json@@ -0,0 +1,65 @@+{+ "$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._:-]*$"+ }+ }+}diff --git a/packages/paperclip-runner/protocol/schemas/terminal.schema.json b/packages/paperclip-runner/protocol/schemas/terminal.schema.jsonnew file mode 100644index 0000000000..3538d20120--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/terminal.schema.json@@ -0,0 +1,26 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/usage.schema.json b/packages/paperclip-runner/protocol/schemas/usage.schema.jsonnew file mode 100644index 0000000000..68c912f2dc--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/usage.schema.json@@ -0,0 +1,32 @@+{+ "$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+ }+ }+}diff --git a/packages/paperclip-runner/protocol/schemas/workspace-diff.schema.json b/packages/paperclip-runner/protocol/schemas/workspace-diff.schema.jsonnew file mode 100644index 0000000000..ebf317dbae--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/workspace-diff.schema.json@@ -0,0 +1,49 @@+{+ "$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+}diff --git a/packages/paperclip-runner/protocol/schemas/workspace-file-reference.schema.json b/packages/paperclip-runner/protocol/schemas/workspace-file-reference.schema.jsonnew file mode 100644index 0000000000..e0dc8555d2--- /dev/null+++ b/packages/paperclip-runner/protocol/schemas/workspace-file-reference.schema.json@@ -0,0 +1,26 @@+{+ "$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+}diff --git a/packages/paperclip-runner/scripts/generate-protocol-manifest.mjs b/packages/paperclip-runner/scripts/generate-protocol-manifest.mjsnew file mode 100644index 0000000000..3bc3d59462--- /dev/null+++ b/packages/paperclip-runner/scripts/generate-protocol-manifest.mjs@@ -0,0 +1,114 @@+import { readFile, writeFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import {+ SUPPORTED_FIXTURE_VERSION,+ SUPPORTED_PROTOCOL_VERSION,+ assertCodexQuestionFixture,+ assertConformanceFixturePair,+ assertReplayFixtureCompatibility,+ assertSchemaInstance,+ compileProtocolValidators,+ listJsonFiles,+ loadSchemaCatalog,+ portableRelative,+ readJson,+ sha256,+} from "./protocol-contract.mjs";++const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+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";++export async function buildProtocolManifest() {+ const schemas = await loadSchemaCatalog(schemaDirectory);+ const validators = compileProtocolValidators(schemas);+ const fixtureFiles = await listJsonFiles(fixtureDirectory);+ const fixtures = [];+ const fixtureValues = new Map();++ for (const path of fixtureFiles) {+ const relativePath = portableRelative(protocolRoot, path);+ const { source, value } = await readJson(path);+ fixtureValues.set(relativePath, value);+ let expectation = "accept";+ let compatibilityCase = "canonical";++ if (relativePath.startsWith("fixtures/replay/")) {+ if (relativePath === expectedRejectedFixture) {+ expectation = "reject";+ compatibilityCase = "unknown-required-version";+ try {+ assertReplayFixtureCompatibility(value);+ throw new Error(`${relativePath} did not fail closed`);+ } catch (error) {+ if (!String(error.message).startsWith("unsupported_required_version:")) throw error;+ }+ assertSchemaInstance(validators.fixture, value, relativePath, false);+ } else {+ assertReplayFixtureCompatibility(value);+ assertSchemaInstance(validators.fixture, value, relativePath);+ if (relativePath.endsWith("unknown-optional-fields.json")) {+ compatibilityCase = "additive-optional-fields";+ }+ }+ } else if (relativePath === "fixtures/questions/codex.json") {+ assertCodexQuestionFixture(value);+ assertSchemaInstance(validators.questionAdapterFixture, value, relativePath);+ compatibilityCase = "codex-structured-input";+ } else if (relativePath === "fixtures/conformance-minimal-run.json") {+ assertSchemaInstance(validators.conformanceFixture, value, relativePath);+ compatibilityCase = "cross-language-input";+ } else if (relativePath === "fixtures/conformance-expected-output.json") {+ assertSchemaInstance(validators.conformanceOutput, value, relativePath);+ compatibilityCase = "cross-language-output";+ }++ fixtures.push({+ path: relativePath,+ sha256: sha256(source),+ expectation,+ compatibilityCase,+ });+ }++ assertConformanceFixturePair(+ fixtureValues.get("fixtures/conformance-minimal-run.json"),+ fixtureValues.get("fixtures/conformance-expected-output.json"),+ );++ return {+ schema: "paperclip.prp.contract_manifest.v1",+ protocolVersion: SUPPORTED_PROTOCOL_VERSION,+ fixtureVersion: SUPPORTED_FIXTURE_VERSION,+ generatedFrom: ["protocol/schemas", "protocol/fixtures"],+ schemas: schemas.map((record) => ({+ path: portableRelative(protocolRoot, record.path),+ id: record.value.$id,+ sha256: sha256(record.source),+ })),+ fixtures,+ };+}++async function main() {+ const encoded = `${JSON.stringify(await buildProtocolManifest(), null, 2)}\n`;+ 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.exitCode = 1;+ } else {+ process.stdout.write("The generated PRP contract manifest matches its sources.\n");+ }+ } else {+ await writeFile(outputPath, encoded);+ process.stdout.write(`Wrote ${outputPath}\n`);+ }+}++if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) await main();diff --git a/packages/paperclip-runner/scripts/protocol-contract.mjs b/packages/paperclip-runner/scripts/protocol-contract.mjsnew file mode 100644index 0000000000..35743d4c7d--- /dev/null+++ b/packages/paperclip-runner/scripts/protocol-contract.mjs@@ -0,0 +1,243 @@+import { createHash } from "node:crypto";+import { readdir, readFile } from "node:fs/promises";+import { relative, resolve, sep } from "node:path";++import Ajv2020 from "ajv/dist/2020.js";++export const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";+export const PRP_SCHEMA_ID_PREFIX = "https://paperclip.dev/schemas/prp/v1/";+export const SUPPORTED_FIXTURE_VERSION = 1;+export const SUPPORTED_PROTOCOL_VERSION = 1;+export const SUPPORTED_EVENT_SCHEMA_VERSION = 1;++function contractError(code, detail) {+ return new Error(`${code}: ${detail}`);+}++export async function readJson(path) {+ const source = await readFile(path, "utf8");+ try {+ return { source, value: JSON.parse(source) };+ } catch (error) {+ throw contractError("invalid_json", `${path}: ${error.message}`);+ }+}++export async function listJsonFiles(root) {+ const entries = await readdir(root, { recursive: true, withFileTypes: true });+ return entries+ .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))+ .map((entry) => resolve(entry.parentPath, entry.name))+ .sort();+}++export function portableRelative(root, path) {+ return relative(root, path).split(sep).join("/");+}++export function sha256(source) {+ return createHash("sha256").update(source).digest("hex");+}++function collectReferences(value, output = []) {+ if (Array.isArray(value)) {+ for (const item of value) collectReferences(item, output);+ return output;+ }+ if (value === null || typeof value !== "object") return output;+ for (const [key, child] of Object.entries(value)) {+ if (key === "$ref" && typeof child === "string") output.push(child);+ else collectReferences(child, output);+ }+ return output;+}++function resolveJsonPointer(value, fragment) {+ if (fragment === "") return value;+ if (!fragment.startsWith("/")) return undefined;+ return fragment+ .slice(1)+ .split("/")+ .map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))+ .reduce((current, part) => {+ if (current === null || typeof current !== "object") return undefined;+ return Object.hasOwn(current, part) ? current[part] : undefined;+ }, value);+}++export async function loadSchemaCatalog(schemaDirectory) {+ const files = await listJsonFiles(schemaDirectory);+ const records = await Promise.all(files.map(async (path) => ({ path, ...(await readJson(path)) })));+ const ids = new Map();++ for (const record of records) {+ const schema = record.value;+ if (schema.$schema !== JSON_SCHEMA_DIALECT) {+ throw contractError("unsupported_schema_dialect", portableRelative(schemaDirectory, record.path));+ }+ if (typeof schema.$id !== "string" || !schema.$id.startsWith(PRP_SCHEMA_ID_PREFIX)) {+ throw contractError("invalid_schema_id", portableRelative(schemaDirectory, record.path));+ }+ if (ids.has(schema.$id)) throw contractError("duplicate_schema_id", schema.$id);+ if (typeof schema.title !== "string" || schema.title.length === 0) {+ throw contractError("missing_schema_title", schema.$id);+ }+ ids.set(schema.$id, record);+ }++ for (const record of records) {+ for (const reference of collectReferences(record.value)) {+ const [targetId, fragment = ""] = reference.split("#", 2);+ const target = targetId === "" ? record : ids.get(targetId);+ if (target === undefined) {+ throw contractError("unresolved_schema_reference", `${record.value.$id} -> ${reference}`);+ }+ if (resolveJsonPointer(target.value, fragment) === undefined) {+ throw contractError("unresolved_schema_fragment", `${record.value.$id} -> ${reference}`);+ }+ }+ }++ return records;+}++export function compileProtocolValidators(schemaRecords) {+ 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 record of schemaRecords) ajv.addSchema(record.value);++ const get = (name) => {+ const id = `${PRP_SCHEMA_ID_PREFIX}${name}.schema.json`;+ const validator = ajv.getSchema(id);+ if (validator === undefined) throw contractError("missing_schema_validator", id);+ return validator;+ };+ return {+ conformanceFixture: get("conformance-fixture"),+ conformanceOutput: get("conformance-output"),+ fixture: get("fixture"),+ questionAdapterFixture: get("question-adapter-fixture"),+ };+}++export function assertSchemaInstance(validator, value, location, expectedValid = true) {+ const valid = validator(value);+ if (valid !== expectedValid) {+ const detail = (validator.errors ?? [])+ .slice(0, 8)+ .map((error) => `${error.instancePath || "/"} ${error.message}`)+ .join("; ");+ const expectation = expectedValid ? "accepted" : "rejected";+ throw contractError("schema_validation_failed", `${location} must be ${expectation}: ${detail || "no AJV error"}`);+ }+ return value;+}++function requireSchema(value, expected, location) {+ if (value?.schema !== expected) {+ throw contractError("unsupported_required_schema", `${location} requires ${String(value?.schema)}`);+ }+}++function requireVersion(value, expected, name) {+ if (value !== expected) {+ throw contractError("unsupported_required_version", `${name}=${String(value)}; supported=${expected}`);+ }+}++export function assertReplayFixtureCompatibility(fixture) {+ requireSchema(fixture, "paperclip.prp.fixture.v1", "fixture");+ requireVersion(fixture.fixtureVersion, SUPPORTED_FIXTURE_VERSION, "fixtureVersion");+ requireVersion(fixture.protocolVersion, SUPPORTED_PROTOCOL_VERSION, "protocolVersion");+ requireSchema(fixture.identity, "paperclip.prp.identity.v1", "identity");+ requireSchema(fixture.capabilities, "paperclip.prp.capabilities.v1", "capabilities");++ if (!Array.isArray(fixture.commands)) throw contractError("invalid_fixture", "commands must be an array");+ for (const [index, command] of fixture.commands.entries()) {+ requireSchema(command, "paperclip.prp.command.v1", `commands[${index}]`);+ }++ if (!Array.isArray(fixture.events) || fixture.events.length === 0) {+ throw contractError("invalid_fixture", "events must be a non-empty array");+ }+ for (const [index, event] of fixture.events.entries()) {+ requireSchema(event, "paperclip.prp.event.v1", `events[${index}]`);+ requireVersion(event.schemaVersion, SUPPORTED_EVENT_SCHEMA_VERSION, `events[${index}].schemaVersion`);+ }++ requireSchema(fixture.result, "paperclip.run_result.v1", "result");+ return fixture;+}++export function assertCodexQuestionFixture(fixture) {+ requireSchema(fixture, "paperclip.question_adapter_fixture.v1", "question fixture");+ if (fixture.adapter !== "codex") throw contractError("unsupported_provider", String(fixture.adapter));+ requireSchema(fixture.canonicalQuestionSet, "paperclip.question_set.v1", "canonicalQuestionSet");+ requireSchema(fixture.canonicalResponse, "paperclip.question_response.v1", "canonicalResponse");+ if (fixture.nativeRequest?.method !== "item/tool/requestUserInput") {+ throw contractError("invalid_codex_question_fixture", "native request method");+ }++ const questions = fixture.canonicalQuestionSet.questions;+ if (!Array.isArray(questions) || questions.length === 0) {+ throw contractError("invalid_codex_question_fixture", "questions must be non-empty");+ }+ const questionIds = new Set();+ const optionIdsByQuestion = new Map();+ for (const question of questions) {+ if (typeof question.id !== "string" || question.id.length === 0 || questionIds.has(question.id)) {+ throw contractError("invalid_codex_question_fixture", "question IDs must be unique");+ }+ questionIds.add(question.id);+ const optionIds = new Set();+ for (const option of question.options ?? []) {+ if (typeof option.id !== "string" || option.id.length === 0 || optionIds.has(option.id)) {+ throw contractError("invalid_codex_question_fixture", `option IDs for ${question.id} must be unique`);+ }+ optionIds.add(option.id);+ }+ optionIdsByQuestion.set(question.id, optionIds);+ }+ for (const [answerId, answer] of Object.entries(fixture.canonicalResponse.answers ?? {})) {+ if (!questionIds.has(answerId)) {+ throw contractError("invalid_codex_question_fixture", `answer has unknown question ID ${answerId}`);+ }+ for (const optionId of answer.selectedOptionIds ?? []) {+ if (!optionIdsByQuestion.get(answerId)?.has(optionId)) {+ throw contractError("invalid_codex_question_fixture", `answer has unknown option ID ${optionId}`);+ }+ }+ }+ return fixture;+}++export function assertConformanceFixturePair(fixture, output) {+ if (fixture?.schemaVersion !== "paperclip.runner.conformance.fixture.v1") {+ throw contractError("unsupported_required_schema", `conformance fixture requires ${String(fixture?.schemaVersion)}`);+ }+ if (output?.schemaVersion !== "paperclip.runner.conformance.output.v1") {+ throw contractError("unsupported_required_schema", `conformance output requires ${String(output?.schemaVersion)}`);+ }+ if (fixture.run?.runId !== output.runIdentity?.runId || fixture.run?.sessionId !== output.runIdentity?.sessionId) {+ throw contractError("conformance_identity_mismatch", "run or session identity differs");+ }+ for (const [index, event] of (fixture.events ?? []).entries()) {+ if (event.runId !== fixture.run.runId || event.sequence !== index + 1) {+ throw contractError("invalid_conformance_event", `events[${index}] does not match the run sequence`);+ }+ }+ if (+ fixture.result?.status !== output.result?.status+ || fixture.result?.summary !== output.result?.summary+ || fixture.result?.runId !== fixture.run.runId+ ) {+ throw contractError("conformance_result_mismatch", "expected output does not match the fixture result");+ }+ return { fixture, output };+}diff --git a/packages/paperclip-runner/test/protocol-contract.test.mjs b/packages/paperclip-runner/test/protocol-contract.test.mjsnew file mode 100644index 0000000000..523b79f5ac--- /dev/null+++ b/packages/paperclip-runner/test/protocol-contract.test.mjs@@ -0,0 +1,110 @@+import assert from "node:assert/strict";+import { readFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import test from "node:test";+import { fileURLToPath } from "node:url";++import { buildProtocolManifest } from "../scripts/generate-protocol-manifest.mjs";+import {+ assertCodexQuestionFixture,+ assertConformanceFixturePair,+ assertReplayFixtureCompatibility,+ assertSchemaInstance,+ compileProtocolValidators,+ loadSchemaCatalog,+ readJson,+} from "../scripts/protocol-contract.mjs";++const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const protocolRoot = resolve(packageRoot, "protocol");++async function fixture(relativePath) {+ return (await readJson(resolve(protocolRoot, "fixtures", relativePath))).value;+}++test("all schema IDs are unique and all external references resolve", async () => {+ const schemas = await loadSchemaCatalog(resolve(protocolRoot, "schemas"));+ assert.equal(schemas.length, 20);+ assert.doesNotThrow(() => compileProtocolValidators(schemas));+});++test("the generated manifest matches all checked-in schemas and fixtures", async () => {+ const expected = `${JSON.stringify(await buildProtocolManifest(), null, 2)}\n`;+ const actual = await readFile(resolve(protocolRoot, "manifest.json"), "utf8");+ assert.equal(actual, expected);+});++test("canonical replay fixtures use supported required versions", async () => {+ for (const name of [+ "duplicate-event.json",+ "failed-run.json",+ "happy-path.json",+ "interrupted-run.json",+ "source-gap.json",+ ]) {+ assert.equal(assertReplayFixtureCompatibility(await fixture(`replay/${name}`)).protocolVersion, 1);+ }+});++test("unknown additive fields remain compatible with PRP v1", async () => {+ const value = await fixture("replay/unknown-optional-fields.json");+ assert.equal(value.futureFixtureHint.producerVersion, "1.1-preview");+ assert.doesNotThrow(() => assertReplayFixtureCompatibility(value));+});++test("unknown required versions and schemas fail closed", async () => {+ const unsupported = await fixture("replay/unsupported-required-version.json");+ assert.throws(+ () => assertReplayFixtureCompatibility(unsupported),+ /unsupported_required_version: protocolVersion=2; supported=1/,+ );++ const eventVersion = structuredClone(await fixture("replay/happy-path.json"));+ eventVersion.events[0].schemaVersion = 2;+ assert.throws(() => assertReplayFixtureCompatibility(eventVersion), /unsupported_required_version/);++ const commandSchema = structuredClone(await fixture("replay/happy-path.json"));+ commandSchema.commands[0].schema = "paperclip.prp.command.v2";+ assert.throws(() => assertReplayFixtureCompatibility(commandSchema), /unsupported_required_schema/);+});++test("accepted fixtures satisfy the complete JSON Schemas", async () => {+ const schemas = await loadSchemaCatalog(resolve(protocolRoot, "schemas"));+ const validators = compileProtocolValidators(schemas);+ const happyPath = await fixture("replay/happy-path.json");+ assert.doesNotThrow(() => assertSchemaInstance(validators.fixture, happyPath, "happy-path"));++ const missingRequiredField = structuredClone(happyPath);+ delete missingRequiredField.commands[0].commandId;+ assert.throws(+ () => assertSchemaInstance(validators.fixture, missingRequiredField, "missing-command-id"),+ /schema_validation_failed: missing-command-id must be accepted: \/commands\/0 must have required property 'commandId'/,+ );++ const unsupported = await fixture("replay/unsupported-required-version.json");+ assert.doesNotThrow(() => assertSchemaInstance(validators.fixture, unsupported, "required-v2", false));+});++test("the Codex question fixture uses stable provider-neutral IDs", async () => {+ const value = await fixture("questions/codex.json");+ assert.doesNotThrow(() => assertCodexQuestionFixture(value));+ assert.deepEqual(Object.keys(value.canonicalResponse.answers), ["environment"]);+});++test("the cross-language conformance input and output have one stable identity", async () => {+ const input = await fixture("conformance-minimal-run.json");+ const output = await fixture("conformance-expected-output.json");+ const schemas = await loadSchemaCatalog(resolve(protocolRoot, "schemas"));+ const validators = compileProtocolValidators(schemas);+ assert.doesNotThrow(() => assertSchemaInstance(validators.conformanceFixture, input, "conformance-input"));+ assert.doesNotThrow(() => assertSchemaInstance(validators.conformanceOutput, output, "conformance-output"));+ assert.doesNotThrow(() => assertConformanceFixturePair(input, output));+ assert.equal(input.result.summary, output.result.summary);++ const missingSessionId = structuredClone(output);+ delete missingSessionId.runIdentity.sessionId;+ assert.throws(+ () => assertSchemaInstance(validators.conformanceOutput, missingSessionId, "missing-session-id"),+ /schema_validation_failed: missing-session-id must be accepted: \/runIdentity must have required property 'sessionId'/,+ );+});