ARCP — Swift SDK

Swift 6 reference implementation of the Agent Runtime Control Protocol (ARCP spec). Wire version: 1.1. SDK version: 1.1.0.

Status

v1.1.0 — full v1.1 protocol surface:

• ✅ Envelope, ids (ULID), errors, extension registry, SQLite event log
• ✅ Four-step handshake (RFC §8.1) with bearer, signed_jwt, none schemes
• ✅ Capability negotiation (RFC §7)
• ✅ Durable jobs with state machine, heartbeats, cooperative cancellation, interrupts
• ✅ Multi-kind streams (text, event, log, thought, metric, base64 binary) + backpressure
• ✅ Permission challenges + lease lifecycle (grant, refresh, revoke, expire sweep)
• ✅ Subscriptions with filter, backfill, subscription.backfill_complete boundary
• ✅ Inline-base64 artifacts with retention sweep
• ✅ Resume by after_message_id
• ✅ job.result_chunk wire messages, ResultChunkStream, and crash-and-resume
• ✅ lease_constraints.expires_at validation and in-handler expiry checks
• ✅ cost.budget cap, BUDGET_EXHAUSTED error, and per-charge metrics
• ✅ model.use parsing, matching, and runtime policy enforcement
• ✅ provisioned_credentials — issue / rotate / revoke lifecycle
• ✅ Transports: MemoryTransport (tests), StdioTransport (NDJSON), WebSocketTransport (client)

Out of scope for v1.1 (see CONFORMANCE.md): mTLS / OAuth2 auth, sidecar binary stream frames, scheduled jobs, multi-agent delegation/handoff, trust elevation, checkpoint-based resume, full WebSocket server (client transport works; server-side WebSocketKit initializer is internal — full server in v1.2).

Requirements

• Swift 6.0 toolchain or later (validated against 6.3.1)
• macOS 14+ or Linux (Ubuntu 22.04+ tested)

Quickstart

git clone <this repo>
cd swift-sdk
swift run sample-01-minimal-session

Expected output:

Sample 01 — minimal session (wire 1.1)
session opened: sess_01...
pong nonce: hello
session closed

The other samples — sample-02-tool-invoke-progress, sample-03-permission-challenge, sample-04-observer-subscription — each demonstrate a distinct ARCP surface end-to-end via the in-memory transport.

See Recipes/ for focused, single-feature examples covering MCP bridging, cost-budget enforcement, permission leases, and stream resume.

CLI

swift run arcp serve              # accept one ARCP session over stdio
swift run arcp send <tool> --args '{"k":"v"}'
swift run arcp tail               # subscribe and print events
swift run arcp replay <db> <session>

Build & test (gate command set)

The v1.1 release passes these five commands at exit code 0:

swift package plugin --allow-writing-to-package-directory format-source-code
swift package plugin lint-source-code -- --strict
swift build -c release -Xswiftc -warnings-as-errors
swift test --parallel --enable-code-coverage
swift package generate-documentation --target ARCP

Architecture

State diagrams for sessions, jobs, streams, subscriptions, and leases live under docs/diagrams/.

RFC mapping

Every in-scope wire message type maps to a MessageType enum case and payload struct in Sources/ARCP/. Out-of-scope types decode as .unknown(typeName:payload:) and are rejected per RFC §21.3 with UNIMPLEMENTED when a non-optional sender expects them.

License

Apache License 2.0 — see LICENSE in this directory.