docs(prx): ADR — Message Batches API as a second model-call transport#971
Draft
bdelanghe wants to merge 6 commits into
Draft
docs(prx): ADR — Message Batches API as a second model-call transport#971bdelanghe wants to merge 6 commits into
bdelanghe wants to merge 6 commits into
Conversation
Scopes the lift to route prx's single-shot classifier surfaces (triage type-pass, prioritize-bulk, eval fan-outs) through the async Message Batches API for the 50% discount and a collapsed serial wall-clock, behind an explicit submit/poll lifecycle. Frames batch against prx's artifact ratchet: because the pipeline advances on signed artifacts and humans are never inside the agentic loop, non-interactive legs are already async-queue-shaped; the near-term gate is transport, not the interaction model. Interactive surfaces stay on the agent SDK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
Contributor
Code Coverage OverviewLanguages: TypeScript TypeScript / unitThe overall coverage remains at 88%, unchanged from the branch. Updated |
Establishes empirically what a Claude Code on the web session can prove about itself (no TPM/SEV/IMDS root of trust; base image identifiable but not attestable) and specifies a broker protocol that gates a privileged write (e.g. filing a bead) on GitHub-verifiable proofs — branch control and private-repo read — with zero credentials in the box. Adds .claude/attest-box.sh, a git-tracked SessionStart hook that emits the attestation bundle; its bytes are pinned to the head commit the broker re-verifies, so the attestation and its producer share one anchor. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
The prior commit hand-edited .claude/settings.json to add the attest-box.sh hook, but that file is generated by buildOrgHarnessSettings and drift-gated. Add the hook (and update the ordering assertion) in the builder — the source of truth — so the checked-in settings match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
The settings-builder change is repo-internal harness config, not a change to released @bounded-systems/prx behavior, so record a no-release changeset to satisfy the changeset gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
Adds the multi-party attenuation model (a caveat chain: launch → box → artifact → broker → DoltHub, each verified by a different party — "more than the box, more than the cloud"), GitHub web-flow signing on the token's authority, passing a root of trust from the launch origin, and three concrete broker realizations (GitHub Actions + Environments, Cloudflare Worker/Tunnel, keeperd) with recommended sequencing. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
Records that bd is always the writer (cloud box holds no dolt): keeperd + dolt-box, or bd → a remote dolt sql-server; never the raw DoltHub HTTP SQL API (off-model, bypasses bd's ids/events/schema). Adds the bead-write broker contract (spec-as-schema, mirroring keeperd/contract.ts) and the fail-closed keeper-side verify → bd create → signed-push pipeline reusing the prx-b44y host-backed-secret path. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a proposed ADR —
docs/prx/batch-transport.md— scoping the lift to give prx the ability to use the Message Batches API.The ADR establishes that batch is a second, parallel model-call transport, not a flag on the existing path: everything prx sends today goes through
@anthropic-ai/claude-agent-sdk'squery(), whereasmessages.batches.*lives on the raw@anthropic-ai/sdk(a transitive peer dep, not a direct one). It then frames batch against prx's architecture:submit_plan→PlanArtifact,checks/v1, predicate-bundle members) and humans are never inside the agentic loop — so non-interactive legs are async-queue-shaped and the 24-hour batch window is a non-event for them.triage type-pass,triage prioritize-bulk, eval fan-outs) are the near-term win — already raw-Messages-shaped, tool-free, and running today as a synchronous sequential loop that batch replaces at 50% cost.session open,--interactive) stay onquery()unconditionally.Docs are generated from the project graph, so the new ADR is auto-discovered;
prx.jsonldand the.claude/context/project.mdindex were regenerated viabun run docs:render(drift gate green).Closes #972
Checklist
bun run docs:render;bun run docs:checkis green🤖 Generated with Claude Code
https://claude.ai/code/session_01Amt3X8s8CEdJW5civefipL