Files
PaperClipAI/packages/paperclip-runner/protocol
DottaandClaude Opus 5.5 bcadbde449 feat(runner): record the OpenRouter host that served each OpenCode model call (#21298)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - OpenCode agents can use models through OpenRouter, and the Runner
proxies those model calls
> - OpenRouter routes one model across many hosts, and these hosts use
different quantizations (fp4, mxfp4, fp8)
> - Chat evaluations with identical prompts behave very differently
between runs, but the run log does not record which host served a call
> - The run usage shows `provider: "deepseek"` and `biller:
"openrouter"`, and `providerRequestId` is always `null`
> - This pull request records the serving host and the OpenRouter
generation ID for each model call in the run log
> - The benefit is that we can compare evaluation cohorts by host, and
the cost event names a real OpenRouter generation

## Linked Issues or Issue Description

**Subsystem affected**
Runner OpenCode provider proxy, runnerd usage normalization, and native
run usage accounting.

**Problem or motivation**
OpenRouter's default routing sends a request to one of many hosts. Each
host can use a different quantization. Chat evaluation results change a
lot between runs with identical prompts. Paperclip does not record which
host served a call, so we cannot compare results by host.
`usageJson.providerRequestId` is always `null` for OpenCode runs.

**Proposed solution**
Every OpenRouter completion response has a top-level `provider` field
and an `id` (the generation ID). Each streamed chunk has them too. The
Runner proxy reads them from the first chunk after it forwards the
bytes. The Runner attaches them to the usage of that call. The values go
to the run log, and the run's first generation ID goes to
`usageJson.providerRequestId`.

**Alternatives considered**
A new PRP event type such as `provider.upstream.served` would need a new
event enum value. An older control plane rejects an unknown event type.
A `harness.diagnostic` event shows in the task chat as a diagnostic. The
usage payload already flows to every consumer, and older consumers
ignore extra fields. Thus this change uses the usage payload.

**Additional context**
Run-log change only (AGENTS.md section 7). The data stays in
`heartbeat_run_events` and `heartbeat_runs.usageJson`. It does not touch
`packages/shared/src/telemetry/` or OpenTelemetry.

## What Changed

- New `createUpstreamServedTap`
(`packages/paperclip-runner/src/drivers/opencode/upstream-served.ts`).
It is a pass-through stream. It pushes each chunk downstream first, then
it reads `provider` and `id` from the first SSE `data:` event (or from a
JSON body at its end). It scans at most 64 KiB of a stream and 1 MiB of
a JSON body. It skips encoded bodies and unknown content types. Any
parse problem or recorder error stops the scan and leaves the response
unchanged.
- `startOpenCodeProviderProxy` uses the tap only for 2xx responses. The
OpenCode session keeps the most recent served call. Each
`item.completed` usage payload and `session.usage()` now carry
`upstreamProvider` and `providerRequestId`. The usage dedupe fingerprint
does not include these fields, so the number of usage events does not
change.
- The OpenCode app-server proxy adds the two fields to
`thread/tokenUsage/updated`. Rust `usage.reported` now fills its
existing `providerRequestId` field and adds an optional
`upstreamProvider`. The TypeScript runnerd transport keeps both fields
when it rehydrates the usage notification. `usage.schema.json` documents
`upstreamProvider` (the protocol manifest and schema bundle are
regenerated).
- Server native turn accounting keeps the first generation ID the run
reports. The usage checkpoint and the native adapter result carry it as
`providerRequestId`, so `usageJson.providerRequestId` and the final cost
event name it.
- `doc/run-log-events.md` documents the fields in a new "OpenRouter
serving host" section.

## Verification

- Red/green: `opencode-server-driver.test.ts` "passes OpenRouter's
stream through unchanged and records the host that served it on the
turn's usage". The test sends a streamed fixture with a comment line, a
host chunk, a malformed chunk, and `[DONE]` through the proxy. It checks
that the bytes are identical and that the turn's usage names `Novita`
and the generation ID. The test fails without the proxy wiring.
- `upstream-served.test.ts`: streamed fixture, chunk split inside a
multibyte character, non-streamed JSON, malformed chunks, a truncated
JSON body, an encoded body, the 64 KiB limit, and a recorder that
throws.
- `opencode-proxy-usage.test.ts`, `runnerd-codex-transport.test.ts`
(rehydration), Rust
`provider_events::tests::carries_the_serving_host_and_generation_on_proxy_usage`,
and server `native-usage-accounting.test.ts` (first generation ID stays
stable across turns).
- Local: OpenCode driver, OpenCode proxy, and runnerd transport suites
(31 files, 596 tests) pass. `cargo test -p paperclip-runner-core` passes
(one timing test failed once under load and passed alone). Runner and
server `tsc --noEmit` pass. Protocol manifest, type, and coverage checks
pass.
- Latency: a local benchmark proxied a 400-chunk SSE stream 200 times
with the tap and 200 times without it. The median time to first byte was
292 µs with the tap and 259 µs without it (+33 µs, which is the extra
stream stage). The total stream time changed from 491.4 ms to 492.5 ms.
The tap spends about 5.5 µs of CPU to inspect the first chunk, after it
has forwarded that chunk. OpenRouter time to first token is hundreds of
milliseconds.
- Paid evidence: one single-case run of
`chat-features.runner-opencode.local.skills.fork-read-only` on this
branch. The result is in a comment on this pull request.

## Risks

- Low risk. All new fields are optional and additive. An older control
plane ignores the extra usage fields. `usage.schema.json` is not bound
by the event schema, and no validator enforces it on `usage.reported`.
- Saved state from the previous release: this change adds no persisted
run, session, checkpoint, or launch state. A saved session resumes
unchanged. A run that is in flight during a deploy reports usage without
the new fields until its Runner is new. `usageJson.providerRequestId`
then stays `null`, as before.
- `providerRequestId` on the run and its cost event is the run's first
generation ID, not each call's ID. The value is stable, so a late usage
receipt still matches the posted charge. Per-call IDs and hosts are in
the run log.
- If OpenCode starts a new model call before it reports the usage of the
previous call, a usage event can name the newer call. OpenCode reports a
message's usage when its step ends, so this is not expected.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code as an agent with tool use (shell, file edits, test runs). Extended
reasoning was on.

## 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-13 00:15:53 -06:00
..

PRP v1/v2 Contract

The JSON Schema files in schemas/ are the language-neutral source of truth for Paperclip Runner Protocol versions 1 and 2. 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.
  • Peers negotiate the highest mutually supported protocol version. Existing v1 runners remain compatible but cannot receive v2-only session-goal commands.

The unknown-optional-fields.json fixture must be accepted. The unsupported-required-version.json fixture must be rejected.

Session goals (v2)

PRP v2 adds a provider-neutral durable session-goal lifecycle. Every v2 capability snapshot includes sessionGoals, even when its availability is unsupported or policy_disabled. Paperclip sends controls only when the negotiated capability advertises the corresponding action.

Commands:

  • session.goal.get
  • session.goal.set for objective, status, and optional token budget changes
  • session.goal.clear

Events:

  • session.capabilities.updated
  • session.goal.snapshot
  • session.goal.updated
  • session.goal.cleared

Goal state is separate from Paperclip's company/business goal hierarchy. The snapshot distinguishes the durable status from workingNow, because an active goal can be idle between autonomous turns. A runner emits the full capability and authoritative snapshot after every session open or resume. Missing v1 capability is unsupported; clients do not infer support from an adapter name.

Harness credential updates

auth.credentials.updated is a P0 runner event available in the v1, v2, and v3 event schemas. Its payload uses paperclip.auth.credentials.updated.v1 and contains only provider, bindingId, revision, and detection. No tokens, account identifiers, credential paths, or credential fingerprints are permitted.

An updated consumer opts in with observeCredentials: true in run.prepare, before session.open. The bundled runner transport opts in for fresh sessions; set its observeCredentials option to false to disable observation for a fresh session. Older hosts that omit the field receive no new event. Consumers must update their schemas before opting in: an event-enum addition is not an unknown optional property. Existing runner binaries ignore the optional flag and do not provide observation; absence of an event does not establish support.

The current Unix runner observes native Codex's managed CODEX_HOME/auth.json and the Codex/Grok ACPX session homes. It uses a non-recursive directory watch plus a one-second polling fallback, so atomic file replacement is handled. Grok's initial inline subscription credential is the baseline, allowing a refresh during launcher startup to be detected. A first valid credential file without a prior baseline establishes the baseline without claiming a refresh. Account identity changes also emit updates, even when token values stay the same, and establish the baseline for later refreshes on the new account. Hosts must evaluate the current credential through their private credential channel and account checks; the event does not authorize an account switch. Metadata-only changes, partial writes, and deletion do not emit updates. Unsupported harnesses and refreshes retained only in memory need their own observer or native-hook integration; adding this event does not make them observable.

bindingId: "harness-auth" identifies the selected harness authentication within the envelope's normalized session. Revisions increase for that binding and survive runner restarts and warm run attachments. The baseline fingerprint and pending event are persisted together in a private runner state file. Source retries retain the same event identity until the durable PRP outbox accepts it. Hosts should commit an idempotent reaction or durable work item through onCommittedEvent before returning and advancing the cumulative ACK. The bundled transport exposes onCredentialsUpdated(event) for this commit. It awaits the callback before ACK, including during warm idle, attachment, and provider cleanup. Callback failures leave delivery unacknowledged for retry; callbacks must therefore deduplicate by the original source event identity. When configured, credential updates bypass the turn notification queue. Paperclip commits them directly to the run log in a separate credential source namespace, preserving the original PRP envelope and avoiding collisions with the driver's normalized event sequence. A turn-only notification consumer cannot reliably handle idle or cleanup updates; use this callback instead.

detection: "credential_store" reports an observed credential change, not proof that an OAuth refresh succeeded. Multiple changes between observations can be coalesced; this is not an audit of every refresh exchange. The schema also allows native_hook for integrations with an explicit signal. Observation continues during warm idle and checks at turn terminal and close boundaries, including Grok's private refresh handoff after live-store cleanup. Retained runner observations enter the durable outbox before a suspend or shutdown command completes, without draining the provider backlog. A final check after provider cleanup also enters the outbox and waits for the host ACK. The runner retains its terminal recovery fence if that delivery fails.

The event authorizes no credential access or write on its own. A host that needs rotated token values must use a separately authorized handoff with its existing account-identity and freshness safeguards. The default Paperclip credential copy-back behavior remains in place.

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.

The files in fixtures/replay/golden/ are deterministic reducer oracles. Each accepted replay fixture has a complete session snapshot and a compact parity summary. pnpm generate:replay-goldens updates them after an intentional reducer change; package build and CI fail when they drift.

The files in fixtures/local-runner/scripts/ drive the package-local fake harness. They cover successful, failed, interrupted, interactive, duplicate terminal, process-cleanup, and oversized-frame behavior without starting a production adapter.

runtime.activity.recorded is a P1 Runner event in v1, v2 and v3 with exactly { namespace, activityKey }. Both opaque identifiers contain 1–160 Unicode code points and exclude C0 controls and DEL. namespace groups a producer's activity types; activityKey names an activity within that group. Consumers use the pair to select a response to activity in the run. The authenticated outer envelope provides run and session identity, source sequence and emission time. Core resolves the run's company, task and agent through its existing authorized run binding; callers cannot supply those identities in the payload. Recording activity does not independently verify the reported action or grant access to any resource. The event uses the ordinary durable outbox, acknowledgement and replay contract.

Local clients capture an opaque context with paperclip-runnerd notification-context before an operation and invoke record-activity CONTEXT NAMESPACE ACTIVITY_KEY after success. Runner publishes its matching absolute executable as host-owned PAPERCLIP_RUNTIME_NOTIFICATION_HELPER and the stable endpoint descriptor path as PAPERCLIP_RUNTIME_NOTIFICATION_CONTEXT. Configured task environment cannot override either value. Context is invalidated on warm attachment and process recovery, so a caller cannot attribute a later completion to a different run.

Runner attachment downloads

For native workspace providers, the authenticated controller can send runner.attachment.download as a PRP v3 command after provider preparation. The controller authorizes the source and sends turnId, an HTTPS url with no query or fragment, a short-lived opaque bearer token, byteSize, sha256 (lowercase hex), and contentType. The controller must choose the tenant download endpoint and issue a grant redeemable for only the admitted file during that turn. Keep grants in private controller state.

Runner starts a bounded HTTPS GET with the grant in the Authorization header and returns { status: "pending", downloadId }. Runner can process Stop while the GET runs. Runner emits one runner.attachment.settled event with the same downloadId and a ready or failed status. A ready event includes the local path only after Runner verifies the complete file. The path is local to the Runner, uses a random filename, and is valid only during the bound turn. Runner clears its private download directory on turn settlement, authority rotation, and shutdown. The next use of that Runner state directory also clears residue from interrupted processes. The command supports files through 10 MiB and limits live downloads to 128 files or 128 MiB per turn. Providers should receive only the path and file metadata.

The authenticated session.snapshot result advertises this command with attachmentDownloadVersion: 1. The tenant controller uses this capability before issuing a grant. Attachment admission and issuance of grants belong to the tenant app.