Skip to content

README.md

Latest commit

 

History

History
135 lines (108 loc) · 7.33 KB

README.md

File metadata and controls

135 lines (108 loc) · 7.33 KB

arcp — Ruby SDK for the Agent Runtime Control Protocol

Reference Ruby implementation of the Agent Runtime Control Protocol (ARCP) v1.0.

Status

v0.1.0 — protocol fundamentals are in. See CONFORMANCE.md for what is implemented and what is deferred. The implementation prioritises correctness and readability over speed; idiomatic Ruby (Data.define, case/in, the async gem, fiber-local trace context) is used throughout.

Requirements

  • Ruby 3.4+ (uses pattern matching, Data.define, fiber-local storage)
  • Bundler 2.x

Quickstart

bundle install
bundle exec rake          # rspec + rubocop
bundle exec ruby samples/01_minimal_session.rb

The arcp CLI is also installed by the gem (bundle exec arcp):

arcp version
arcp serve --transport stdio        # blocks on stdin/stdout
arcp serve --transport ws --bind 127.0.0.1:7777
arcp tail   path/to/event-log.sqlite
arcp replay path/to/event-log.sqlite --after msg_xyz
arcp send   ping '{}'

Architecture

+-------------------------+        +---------------------------+
|  Arcp::Client::Client   |  <-->  |  Arcp::Runtime::Runtime   |
|  - open / invoke / ping |        |  - SessionNegotiator      |
|  - cancel / interrupt   |        |  - JobManager             |
|  - on_human_input       |        |  - StreamManager          |
|  - on_permission        |        |  - LeaseManager           |
+-------------------------+        |  - SubscriptionManager    |
            ^                      |  - ArtifactStore          |
            |                      |  - Store::EventLog        |
            v                      +---------------------------+
   +------------------+
   |  Arcp::Transport |   Memory | Stdio | WebSocket
   +------------------+

Layered responsibilities

Layer Files Notes
Envelope lib/arcp/envelope.rb, lib/arcp/json.rb Data.define, structural equality, JSON encode/decode
Errors lib/arcp/error.rb, lib/arcp/error_code.rb Canonical taxonomy as frozen constants; subclass per code
Messages lib/arcp/messages/*.rb Each wire type → Data.define payload, registered
Transport lib/arcp/transport/*.rb Memory (tests), stdio, WebSocket
Runtime lib/arcp/runtime/*.rb Per-session managers + dispatcher
Client lib/arcp/client/client.rb Synchronous-style API on the same fiber reactor
Storage lib/arcp/store/event_log.rb SQLite event log + idempotency table
CLI lib/arcp/cli.rb, exe/arcp dry-cli commands

Concurrency model

Ruby has no algebraic data types and no compile-time exhaustiveness check. We close those gaps with:

  • Data.define for envelope, IDs, and message payloads — immutable value objects with structural equality.
  • case/in pattern matching for typed dispatch on payload class.
  • The async gem for fiber-based concurrency: synchronous-style code suspends on IO, with structured concurrency baked into the task tree.
  • Async::Notification for one-shot wait/signal across fibers (used by PendingRegistry).
  • Fiber[:arcp_trace] for trace context propagation (§17.1).

See PLAN.md for the per-section plan and design notes.

Samples

Each sample is self-contained: it spawns an in-memory runtime + client and exercises one feature.

File Demonstrates
samples/01_minimal_session.rb Handshake, ping/pong, close
samples/02_tool_invoke_with_progress.rb tool.invoke with job.progress + a text stream
samples/03_human_input_request.rb human.input.request with schema validation
samples/04_permission_challenge.rb permission.request → permission.grant → lease
samples/05_observer_subscription.rb Subscribe, observe events, hit backfill marker
samples/06_relay_human_in_the_loop.rb Combined human input + permission relay flow

RFC mapping

RFC § Implementation Status
§6 Arcp::Envelope, Arcp::Json Full
§7 Arcp::Capabilities Full
§8 Arcp::Auth::{Bearer,Jwt}, Arcp::Runtime::SessionNegotiator bearer, signed_jwt, none; mtls/oauth2 deferred
§9 SessionContext Stateless + stateful; durable across reconnect deferred
§10 JobManager Heartbeats, cancellation, interrupts; scheduled jobs deferred
§11 StreamManager Base64 in-envelope only; sidecar deferred
§12 SessionHelper#request_human_input Includes default + expiration
§13 SubscriptionManager Filter, backfill, subscription.backfill_complete
§14 — Out of scope for v0.1
§15 LeaseManager, SessionHelper#request_permission Trust elevation deferred
§16 ArtifactStore Inline base64 only
§17 Tracing, Messages::Telemetry::* log, metric, trace.span
§18 Arcp::Error* Full canonical taxonomy
§19 Runtime#handle_resume Message-id resume only; checkpoint deferred
§21 Arcp::Extensions, Arcp::ExtensionRegistry Full
§22 Arcp::Transport::{Memory,Stdio,Websocket} WebSocket + stdio mandatory; HTTP/2 + QUIC deferred

Running the test suite

bundle exec rspec --format documentation
bundle exec rubocop
bundle exec yard --fail-on-warning
bundle exec rake build

The relay scenario at spec/e2e/relay_scenario_spec.rb runs the same flow over the memory and stdio transports as a shared example.

License

Apache-2.0.