Files
PaperClipAI/packages/paperclip-runner/protocol/schemas/command-v3.schema.json
T
Nicky LeachandClaude Opus 5.5 1332ab987f feat(prp): declare the contract for provider-started turns (#21422)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner runs Claude Code through the ACPX sidecar.
> - Claude can start a shell command in the background and end its turn.
When the command finishes, Claude Code starts a cycle of its own to
continue. Today the Runner stops Claude at the end of the turn, so the
command stops and the run fails with `native_finalization_missing`.
> - A stack of pull requests lets the Runner accept that cycle as a new
turn of the same run, when a controller asks for it.
> - The Runner, its sidecar and the controller speak two protocols with
schemas: PRP between the controller and the Runner, and the sidecar
protocol between `paperclip-runnerd` and the ACPX sidecar.
> - A turn that the provider starts needs new fields and one new command
in those protocols.
> - This pull request declares them and generates the readers again. It
changes no behavior.
> - The benefit is that the next two pull requests show behavior only,
with the contract already in review.

## Linked Issues or Issue Description

No public issue exists. The issue is described here.

This pull request is one part of a change that was first opened as one
large pull request (#21316). The parts, in stack order after #21311:

1. #21419: sidecar preparation (a refactor).
2. #21420: converter for raw ACP session updates.
3. #21421: cycle stream at the adapter.
4. #21422: contract for provider-started turns.
5. #21423: `paperclip-runnerd` waits for a provider-started turn.
6. #21316: the sidecar adopts a cycle.

This is part 4. Its base branch is `feat/claude-provider-cycle-stream`.
After each part, a production run does the same as today, because no
controller sends the opt-in. Refs #19912 (design).

**What existing behavior does this improve?**

Nothing in production. The protocol schemas.

**Subsystem affected**

Paperclip Runner: `protocol/` and the generated TypeScript and Rust
contract code.

**Current behavior**

- PRP has no way to say that a turn was started by the provider, or that
the Runner waits for such a turn.
- The sidecar protocol has no command to arm the sidecar and no event
for a turn that the provider starts.

**Proposed behavior**

- PRP (`schemas/provider-turn.schema.json`, new): `providerStartedTurns`
(boolean) in the payload of `turn.start`, `origin: "provider"` on
`turn.started`, and `awaitingProviderTurn: true` on `turn.completed`.
`command-v3` and `event-v3` refer to it.
- Sidecar protocol (`provider-schemas/acpx-sidecar.schema.json`): the
command `session.provider_turn` with `{ turnId, armed }`, the event
`runtime.turn_started` with `{ origin: "provider" }`, and the payload of
the diagnostic for a lost provider. The schema enforces that payload for
a `runtime.diagnostic` with the code `ACPX_PROVIDER_PROCESS_LOST`.
Diagnostics with other codes keep their open payload.
- `paperclip-runnerd` decodes `runtime.turn_started` and refuses it. No
sidecar sends it yet. The Runner of today refuses an unknown event too.
- No controller, Runner or sidecar uses the new fields in this pull
request.

**Reason and benefit**

The repository rule for Runner contracts says that new fields must be in
the schema with generated readers. A separate pull request lets a
reviewer read the contract alone.

## What Changed

- `protocol/schemas/provider-turn.schema.json` (new),
`command-v3.schema.json`, `event-v3.schema.json`,
`protocol/provider-schemas/acpx-sidecar.schema.json`,
`protocol/manifest.json`.
- `scripts/generate-acpx-sidecar-contract.mjs` and
`scripts/generate-protocol-schema-module.mjs`.
- Generated: `src/drivers/acpx/generated-sidecar-contract.ts`,
`src/protocol/generated/schema-bundle.ts`,
`src/protocol/generated/standalone-validators.ts`,
`runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs`.
- `runner/crates/runner-core/src/acpx_event_payload.rs` (3 lines): the
Rust `match` on the event type must name the new event to compile.
- `test/protocol-contract.test.mjs`.
- The contract digests of the pack change (`prp.acpx-sidecar`,
`prp.command-v3`, `prp.event-v3`, `rust`, and the new
`prp.provider-turn`). No stored file refers to these digests. No
provider `commandDigest` and no profile version changes.

## Verification

At the head of this branch, from `packages/paperclip-runner`:

- `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p
tsconfig.test.json`, `pnpm run typecheck:typescript`, `pnpm run
build:typescript`, `node --test test/acpx-sidecar-contract.test.mjs
test/protocol-contract.test.mjs`, the server check `node
scripts/verify-runner-vendor-dependencies.mjs`, `node --test
scripts/__tests__/runner-release-crate-cache.test.mjs`, `cargo fmt
--check` and `cargo build -p paperclip-runner-core --bins` (no new
warning): all passed. The contract tests: 32 passed.
- The sidecar suite and the tracker tests: 141 passed.

Not run: the full suite. CI supplies that coverage.

## Risks

- **The pack contract digest changes.** Older image packs are not used
again.
- **The opt-in field is accepted by the schema but has no effect yet.**
A controller that sends it before part 5 gets the behavior of today.
- **State saved by the previous release:** this pull request changes no
persisted shape.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the
change and the split, reviewed the diff, and ran a part of the
verification again.
- Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with
tool use (shell, file edits, local test runs), wrote the change and the
tests and cut this slice from the full change.

## 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 either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 00:20:45 +00:00

549 lines
13 KiB
JSON

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://paperclip.dev/schemas/prp/v3/command.schema.json",
"title": "PRP v3 runner command",
"type": "object",
"required": [
"schema",
"commandId",
"controllerSeq",
"type",
"issuedAt",
"payload"
],
"properties": {
"schema": {
"const": "paperclip.prp.command.v3"
},
"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",
"session.goal.get",
"session.goal.set",
"session.goal.clear",
"external_provider.operation",
"runner.attachment.download"
]
},
"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
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "session.goal.set"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"objective": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"status": {
"enum": [
"active",
"paused"
]
},
"tokenBudget": {
"type": [
"integer",
"null"
],
"minimum": 1
}
},
"additionalProperties": true
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"type": "object",
"required": [
"requestId",
"bindingId",
"runId",
"normalizedSessionId",
"turnId",
"bindingGeneration",
"assignmentRevision",
"digest",
"action",
"input"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"bindingId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"runId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"normalizedSessionId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"turnId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"bindingGeneration": {
"type": "integer",
"minimum": 1
},
"assignmentRevision": {
"type": "integer",
"minimum": 1
},
"digest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
"action": {
"enum": [
"accept",
"tool",
"progress",
"finish",
"renew",
"request_user_input",
"consume_input"
]
},
"input": {
"type": "object"
}
},
"additionalProperties": false
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "accept"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "tool"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"arguments": {
"type": "object"
}
},
"required": [
"name",
"arguments"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "progress"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 12000
}
},
"required": [
"text"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "finish"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"result": {
"type": "object"
}
},
"required": [
"result"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "renew"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"expiresAtUnixMs": {
"type": "integer",
"minimum": 1
}
},
"required": [
"expiresAtUnixMs"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "request_user_input"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"questionSet": {
"$ref": "https://paperclip.dev/schemas/prp/v1/question-set.schema.json"
}
},
"required": [
"requestId",
"questionSet"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "external_provider.operation"
},
"payload": {
"properties": {
"action": {
"const": "consume_input"
}
},
"type": "object"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"properties": {
"input": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"inputDigest": {
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
}
},
"required": [
"requestId",
"inputDigest"
],
"additionalProperties": false
}
},
"type": "object"
}
},
"type": "object"
}
},
{
"if": {
"properties": {
"type": {
"const": "turn.start"
}
},
"type": "object"
},
"then": {
"properties": {
"payload": {
"type": "object",
"properties": {
"providerStartedTurns": {
"$ref": "https://paperclip.dev/schemas/prp/v3/provider-turn.schema.json#/$defs/controllerOptIn"
}
},
"additionalProperties": true
}
},
"type": "object"
}
}
],
"additionalProperties": true
}