Cycles Rust Client — Runtime Authority for AI Agents (Spend, Actions, Audit)

Tokio-native Rust client for the Cycles protocol — runtime authority over autonomous AI agents. Cycles enforces hard limits on three things observation alone can't fix:

• Spend — reserve-commit budget enforcement that stops runaway LLM cost before the next call, not after the invoice arrives.
• Risky actions — three-way decisions (Allow / AllowWithCaps / Deny) with caps for tool denylists, max tokens, max steps, and cooldowns. The client enforces caps before the agent acts.
• Audit gaps — every reservation, commit, release, and decision is a signed event. Compliance, incident review, and per-agent attribution come for free, not as a separate logging project.

This crate implements the reserve-execute-commit lifecycle with an idiomatic Rust API built around RAII guards, ownership semantics, and Send + Sync concurrency. Same wire protocol as the Python, TypeScript, and Spring Boot clients — switch languages without changing the server.

Installation

[dependencies]
runcycles = "0.2"

Unit must match the budget. The Amount you pass to reserve, with_cycles, decide, or create_event must be in the same unit as the active budget at the target scope. The server indexes budgets by (scope, unit), so reserving Amount::tokens(…) against a USD_MICROCENTS budget returns a 404 "Budget not found for provided scope" even though the scope exists. The client enriches such 404s with the unit that was sent to make the mismatch obvious.

Quick Start — Automatic Lifecycle (with_cycles)

Like Python's @cycles decorator or TypeScript's withCycles. Reserve, execute, and commit/release are handled automatically:

use runcycles::{CyclesClient, with_cycles, WithCyclesConfig, models::*};

#[tokio::main]
async fn main() -> Result<(), runcycles::Error> {
    let client = CyclesClient::builder("my-api-key", "http://localhost:7878")
        .tenant("acme")
        .build();

    let reply = with_cycles(
        &client,
        WithCyclesConfig::new(Amount::tokens(1000))
            .action("llm.completion", "gpt-4o")
            .subject(Subject { tenant: Some("acme".into()), ..Default::default() }),
        |ctx| async move {
            // ctx.caps, ctx.decision, ctx.reservation_id available
            let result = call_llm("Hello").await;
            Ok((result, Amount::tokens(42)))   // (return_value, actual_cost)
        },
    ).await?;
    // On success → auto-commits. On error → auto-releases.

    println!("LLM said: {reply}");
    Ok(())
}
# async fn call_llm(_: &str) -> String { "hi".into() }

Want a real LLM example? examples/async_openai_completion.rs wires the same with_cycles flow against async-openai, threading the response's usage.total_tokens back into the commit. Run it with cargo run --example async_openai_completion — requires OPENAI_API_KEY in the env plus a reachable Cycles server, a tenant API key, and a TOKENS-denominated budget at the scope the example reserves against.

Manual Control — RAII Guard

For streaming, multi-step workflows, or when you need full control:

use runcycles::{CyclesClient, Error, models::*};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let client = CyclesClient::builder("my-api-key", "http://localhost:7878")
        .tenant("acme")
        .build();

    // Reserve budget — returns an RAII guard
    let guard = client.reserve(
        ReservationCreateRequest::builder()
            .subject(Subject { tenant: Some("acme".into()), ..Default::default() })
            .action(Action::new("llm.completion", "gpt-4o"))
            .estimate(Amount::usd_microcents(5000))
            .build()
    ).await?;

    // Check caps if decision is AllowWithCaps
    if let Some(caps) = guard.caps() {
        println!("max_tokens: {:?}", caps.max_tokens);
    }

    // ... perform the guarded operation ...

    // Commit actual spend (consumes the guard — cannot double-commit)
    guard.commit(
        CommitRequest::builder()
            .actual(Amount::usd_microcents(3200))
            .build()
    ).await?;

    Ok(())
}

Design

The Rust client is not a port — it is designed from the ground up around Rust's type system and ownership model:

RAII Guard

The ReservationGuard gives manual control over the lifecycle. It holds a live reservation and auto-extends TTL via a background heartbeat. The guard IS the context — no thread-locals or task-locals needed.

# use runcycles::{CyclesClient, Error, models::*};
# async fn example(client: CyclesClient) -> Result<(), Error> {
let guard = client.reserve(/* ... */
# ReservationCreateRequest::builder()
#     .subject(Subject { tenant: Some("acme".into()), ..Default::default() })
#     .action(Action::new("llm.completion", "gpt-4o"))
#     .estimate(Amount::usd_microcents(5000))
#     .build()
).await?;

// The guard provides all context
guard.reservation_id();  // &ReservationId
guard.decision();        // Decision::Allow or AllowWithCaps
guard.caps();            // Option<&Caps>
guard.is_capped();       // bool
guard.affected_scopes(); // &[String]

// Commit or release (both consume `self`)
guard.commit(CommitRequest::builder().actual(Amount::usd_microcents(3200)).build()).await?;
// guard.commit(...) here would be a COMPILE ERROR
# Ok(())
# }

Low-Level Client

For full control, use the client methods directly:

# use runcycles::{CyclesClient, models::*};
# async fn example(client: CyclesClient) -> Result<(), runcycles::Error> {
let resp = client.create_reservation(&ReservationCreateRequest::builder()
    .subject(Subject { tenant: Some("acme".into()), ..Default::default() })
    .action(Action::new("llm.completion", "gpt-4o"))
    .estimate(Amount::usd_microcents(5000))
    .build()
).await?;

if resp.decision.is_allowed() {
    let id = resp.reservation_id.unwrap();
    // ... do work ...
    client.commit_reservation(&id, &CommitRequest::builder()
        .actual(Amount::usd_microcents(3200))
        .build()
    ).await?;
}
# Ok(())
# }

Error Handling

Errors use pattern matching:

use runcycles::Error;

# fn example(err: Error) {
match err {
    Error::BudgetExceeded { message, .. } => {
        println!("Budget exceeded: {}", message);
    }
    Error::Api { status, code, .. } => {
        println!("API error ({}): {:?}", status, code);
    }
    Error::Transport(e) => {
        println!("Network error: {}", e);
    }
    _ => {}
}
# }

Configuration

From code

# use runcycles::CyclesClient;
let client = CyclesClient::builder("my-api-key", "http://localhost:7878")
    .tenant("acme")
    .workspace("production")
    .connect_timeout(std::time::Duration::from_secs(2))
    .read_timeout(std::time::Duration::from_secs(5))
    .retry_enabled(true)
    .retry_max_attempts(5)
    .build();

From environment

# use runcycles::{CyclesClient, CyclesConfig};
// Reads CYCLES_BASE_URL, CYCLES_API_KEY, CYCLES_TENANT, etc.
let config = CyclesConfig::from_env().expect("missing env vars");
let client = CyclesClient::new(config);

Commit retry

If the attempt inside guard.commit(...) fails with a retryable error — a transport failure, a 5xx server error, or an error code the protocol classifies as transient (e.g. LIMIT_EXCEEDED rate limiting; unrecognized error codes are treated as transient for forward compatibility, see Error::is_retryable) — and retry_enabled is set (the default), the commit is retried inline with exponential backoff (retry_initial_delay × retry_multiplier, capped at retry_max_delay, up to retry_max_attempts attempts). Retries reuse the original request — same idempotency key — so a commit that already landed server-side cannot double-charge, and the reservation heartbeat keeps extending the TTL until the outcome is final, so the reservation cannot expire mid-retry.

The result of commit() is final: Ok means the spend was recorded, Err means no further commit attempt will ever be made — safe to compensate. Under a persistent outage the call blocks for the full backoff schedule; tune the knobs or set retry_enabled(false) for fail-fast single-attempt commits. Env knobs: CYCLES_RETRY_ENABLED, CYCLES_RETRY_MAX_ATTEMPTS, CYCLES_RETRY_INITIAL_DELAY, CYCLES_RETRY_MULTIPLIER, CYCLES_RETRY_MAX_DELAY.

Features

License

Apache-2.0