README.md

title	ARCP Java SDK
sdk	java
spec_sections
kind	index
since	1.0.0

ARCP Java SDK

The Agent Runtime Control Protocol (ARCP) is a JSON-over-WebSocket protocol that lets a client submit jobs to a runtime, observe their events, enforce per-job leases (filesystem, network, tool, model, budget), and reattach to work after a disconnect. The full spec lives at ../spec/docs/draft-arcp-1.1.md.

This SDK is a JDK 21+ reference implementation. It ships ten published Maven artifacts, twenty-four runnable examples and recipes, and a reusable conformance suite (arcp-tck) that downstream JVM implementations can extend.

Start here

Document	What it covers
Getting started	Prerequisites, Gradle/Maven install, 60-line in-process example, WebSocket swap, bearer auth
Architecture	Envelope shape, sessions, jobs, leases, errors, wire taxonomy
Transports	MemoryTransport, WebSocketTransport, Jetty server, Spring Boot, Jakarta, Vert.x, stdio
Conformance	Spec §-keyed implementation status table
Troubleshooting	Common error codes, causes, and fixes
Recipes	Copy-paste solutions for idempotent retry, streaming, delegation, OTel

Guides

Guide	Spec §§
Sessions	§6 — handshake, capability negotiation, heartbeats, ack, resume
Authentication	§6.1 — bearer tokens, BearerVerifier SPI, custom verifiers
Resume	§6.3 — resume tokens, ResumeBuffer, reconnect flow
Jobs	§7 — submit, idempotency, cancel, timeouts, list, subscribe, cost budgets, agent versions
Job events	§8 — event kinds, progress, result streaming, vendor extensions
Leases	§9 — namespaces, glob matching, expiration, model use
Delegation	§10 — sub-agent jobs, lease subset enforcement
Errors	§12 — all 15 error codes, retryability, retry helper pattern
Observability	§11 — OpenTelemetry span-per-envelope, trace propagation
Vendor extensions	§8.5 — extensions payload field, custom event kinds
Credentials	§9.8 / §14 — CredentialProvisioner SPI, lifecycle, confidentiality

Modules

Module	Purpose
arcp	Umbrella artifact: re-exports arcp-client + arcp-runtime
arcp-core	Wire types, envelope, ids, lease, sealed message/event taxonomies, errors, Transport SPI
arcp-client	ArcpClient, JobHandle, ResultStream, WebSocketTransport
arcp-runtime	ArcpRuntime, session FSM, job FSM, LeaseGuard, BudgetCounters, resume buffer
arcp-runtime-jetty	Embedded Jetty 12 WebSocket server
arcp-middleware-jakarta	Jakarta WebSocket ServerEndpointConfig adapter
arcp-middleware-spring-boot	Spring Boot 3.x auto-configuration
arcp-middleware-vertx	Vert.x 5 Handler<ServerWebSocket>
arcp-otel	OpenTelemetry transport wrapper
arcp-tck	Reusable JUnit 5 conformance suite

Reference

• Wire format — Envelope, 17 message types, 10 event kinds, ArcpMapper config
• Error codes — 15 canonical codes, sealed ArcpException hierarchy
• CONFORMANCE.md — spec §-keyed implementation status with file:line references
• CHANGELOG.md — release history
• Examples — runnable subprojects covering every feature

Diagrams

Six Graphviz diagrams under diagrams/ with light and dark variants. Regenerate with make -C docs/diagrams.