mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 10:26:26 +01:00
Dotta
b1cd261212
## Thinking Path > - The runner already persists PRP events, but provider-native activity needs one bounded, provider-neutral vocabulary before additional providers can be added safely. > - The protocol catalog must describe capabilities without enabling or authorizing a provider. > - Provider normalization must not require an ACPX runtime dependency merely to compile the shared event layer. > - This pull request adds the event contract and pure normalizers only; provider transports and production selection remain unchanged. ## Linked Issues or Issue Description This is the first follow-up stacked on #12321. Codex, OpenCode, and ACP runtimes expose different activity shapes. Without canonical normalization, downstream task threads and traces would need provider-specific branching and could retain unbounded or unsafe payloads. ## What Changed - Expand the PRP provider descriptor and canonical activity event families. - Add bounded Codex, OpenCode, and ACP event normalizers for plans, tools, research, delegation, artifacts, review, safety, waits, and notices. - Preserve strict schema validation and regenerate the checked-in schema bundle and manifest. - Use a structural ACP event input so the provider-neutral layer does not introduce or authorize an ACPX runtime dependency. - Export the provider-event contract from the existing package root. ## Verification - `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript` - `pnpm --filter @paperclipai/paperclip-runner test:typescript` — 11 files and 88 tests passed. - `pnpm -r typecheck` - `pnpm build` - `git diff --check` - The local full repository runner reached unrelated macOS workspace-path fixture failures; the affected runner suites pass and the repository CI shards are the handoff authority. - Diff against the declared base: 8 files. ## Compatibility Boundary - No provider transport, adapter, server route, feature flag, or runtime selection changes. - Catalog presence does not authorize discovery or execution. - Existing Codex execution continues through its current path. - No dependency, migration, workflow, or lockfile change. ## Risks The main risk is accepting malformed or unbounded provider payloads. Schema validation remains fail-closed, text/output fields are bounded and redacted, unsafe paths and URLs are discarded, and representative variants for every declared event family are covered by tests. ## Model Used OpenAI Codex, GPT-5 family. The client does not expose the exact deployment ID or context window. Agentic reasoning, tool use, and code execution were enabled. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have described the issue in-PR following the relevant template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal task identifier - [x] I have run the affected local tests and they pass - [x] I have added or updated tests where applicable - [x] I have updated the compatibility notes for this change - [x] I have considered and documented risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open actionable comments - [x] I will address all Greptile and reviewer comments before requesting merge
101 lines
4.2 KiB
JSON
101 lines
4.2 KiB
JSON
{
|
|
"$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": { "enum": ["codex", "opencode", "claude_managed", "aws_agentcore", "acpx"] },
|
|
"driver": { "enum": ["codex_app_server", "opencode_server", "claude_managed_agents_api", "aws_agentcore_harness_api", "acpx_runtime"] },
|
|
"model": { "type": ["string", "null"], "maxLength": 240 },
|
|
"executionKind": { "enum": ["local_process", "remote_service"] },
|
|
"providerVersion": { "type": "string", "minLength": 1, "maxLength": 120 },
|
|
"service": { "enum": ["anthropic_managed_agents", "aws_bedrock_agentcore_harness"] },
|
|
"providerSessionId": { "type": ["string", "null"], "maxLength": 240 },
|
|
"processId": { "type": ["integer", "null"], "minimum": 1 },
|
|
"agentProcessId": { "type": ["integer", "null"], "minimum": 1 },
|
|
"endpointArn": { "type": "string", "minLength": 1, "maxLength": 2048 },
|
|
"endpointQualifier": { "type": "string", "minLength": 1, "maxLength": 240 },
|
|
"memoryId": { "type": "string", "minLength": 1, "maxLength": 240 },
|
|
"eventExpiryDays": { "const": 90 },
|
|
"agent": { "enum": ["pi", "claude", "codex"] },
|
|
"requestedModel": { "type": "string", "minLength": 1, "maxLength": 240 },
|
|
"acpProtocolVersion": { "const": 1 },
|
|
"agentServerPackage": { "type": "string", "minLength": 1, "maxLength": 240 },
|
|
"agentServerVersion": { "type": "string", "minLength": 1, "maxLength": 120 },
|
|
"agentRuntimePackage": { "type": ["string", "null"], "maxLength": 240 },
|
|
"agentRuntimeVersion": { "type": ["string", "null"], "maxLength": 120 },
|
|
"acpxRecordId": { "type": ["string", "null"], "maxLength": 240 }
|
|
},
|
|
"allOf": [
|
|
{
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"provider": { "const": "codex" },
|
|
"driver": { "const": "codex_app_server" },
|
|
"executionKind": { "const": "local_process" }
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"provider": { "const": "opencode" },
|
|
"driver": { "const": "opencode_server" },
|
|
"executionKind": { "const": "local_process" }
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"provider": { "const": "claude_managed" },
|
|
"driver": { "const": "claude_managed_agents_api" },
|
|
"executionKind": { "const": "remote_service" }
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"provider": { "const": "aws_agentcore" },
|
|
"driver": { "const": "aws_agentcore_harness_api" },
|
|
"executionKind": { "const": "remote_service" }
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"provider": { "const": "acpx" },
|
|
"driver": { "const": "acpx_runtime" },
|
|
"executionKind": { "const": "local_process" }
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"if": { "properties": { "executionKind": { "const": "remote_service" } } },
|
|
"then": {
|
|
"required": ["service"],
|
|
"properties": { "processId": { "const": null } }
|
|
}
|
|
},
|
|
{
|
|
"if": { "properties": { "executionKind": { "const": "local_process" } } },
|
|
"then": { "properties": { "service": false } }
|
|
},
|
|
{
|
|
"if": { "properties": { "provider": { "const": "claude_managed" } }, "required": ["provider"] },
|
|
"then": { "properties": { "service": { "const": "anthropic_managed_agents" } }, "required": ["service"] }
|
|
},
|
|
{
|
|
"if": { "properties": { "provider": { "const": "aws_agentcore" } }, "required": ["provider"] },
|
|
"then": {
|
|
"properties": { "service": { "const": "aws_bedrock_agentcore_harness" } },
|
|
"required": ["service", "endpointArn", "endpointQualifier", "memoryId", "eventExpiryDays"]
|
|
}
|
|
},
|
|
{
|
|
"if": { "properties": { "provider": { "const": "acpx" } }, "required": ["provider"] },
|
|
"then": {
|
|
"required": ["agent", "requestedModel", "acpProtocolVersion", "agentServerPackage", "agentServerVersion", "acpxRecordId", "agentProcessId"]
|
|
}
|
|
}
|
|
],
|
|
"additionalProperties": false
|
|
}
|