Cycles

Appearance

Cycles integration rules (drop-in for AGENTS.md / CLAUDE.md / .cursorrules) ​

Append this file to your repo's AGENTS.md, CLAUDE.md, or .cursorrules so every AI coding session inherits the Cycles integration contract without re-pasting it.

Source: https://runcycles.io/how-to/add-cycles-with-claude-or-codex Mirror: https://runcycles.io/agents/cycles-integration.md

Cycles — runtime budget authority ​

This repo uses (or is integrating) Cycles for pre-execution budget and action enforcement around LLM calls and external tool calls. The contract below applies whenever you add, modify, or refactor code that calls a model or makes a paid / side-effecting external call.

The invariant: Cycles must run before the costly action on the same execution path. Every rule below exists to prove or enforce that.

Do ​

  1. Wrap LLM calls and external side-effect tool calls with the language-appropriate Cycles primitive:
    • Python: runcycles package, @cycles decorator
    • TypeScript: runcycles package, withCycles HOF
    • Java/Spring: cycles-client-java-spring, @Cycles annotation
    • Rust: runcycles crate, with_cycles() (auto) or ReservationGuard (manual / streaming)
  2. Read configuration from environment variables only:
    • CYCLES_BASE_URL
    • CYCLES_API_KEY (cyc_live_..., never hardcoded)
    • CYCLES_TENANT
  3. Use CyclesConfig.from_env() / CyclesConfig.fromEnv() / Spring Boot auto-config — do not roll a custom config layer.
  4. Commit actual usage after execution; use estimate-as-actual only when that is an explicit, reviewed choice.
  5. On budget denial (BudgetExceededError / CyclesProtocolException with isBudgetExceeded()), take ONE of: graceful fallback, downgraded model, queue-for-later. Never silently retry the original call.
  6. For each new wrapped boundary, add a test that mocks the downstream client and asserts it received zero calls when Cycles denies. This test is the proof of correctness.
  7. When choosing the first boundary, prioritize highest cost, highest frequency, or highest blast radius. Cycles is not just cost control — blast radius (deletes, sends, payments, irreversible side effects) is a first-class reason to wrap a call.
  8. Ship one wrapped boundary per PR. Tune estimates from logs before wrapping the next.

Do not ​

  • Rely on prompts, system messages, or model instructions as enforcement. The model is not the enforcement authority.
  • Add only logging without a deny path that prevents the downstream call.
  • Place the Cycles check after the downstream call. Reserve must precede execution.
  • Treat MCP tool availability as enforcement. Treat MCP as discovery and local-workflow support unless the host or tool harness is required to call Cycles before executing the real action. Production enforcement belongs in the SDK wrapper or gateway on this repo's execution path.
  • Invent a new Cycles abstraction unless the repo already has a gateway or middleware layer where tool/model calls are centralized. Prefer the documented decorator / HOF / annotation first; integrate at the gateway only when it is the natural seam.
  • Hardcode estimates that don't reflect typical call cost — read recent log data or use a callable estimate that derives from request size.
  • Wrap multiple boundaries in one change. One boundary, one test, ship, expand.

Pattern (Python) ​

python
from runcycles import (
    CyclesClient, CyclesConfig, BudgetExceededError, cycles, set_default_client,
)

set_default_client(CyclesClient(CyclesConfig.from_env()))

@cycles(
    estimate=2_000_000,
    # Prefer provider usage/cost metadata (e.g. response.usage.total_tokens)
    # when available. This length-based placeholder keeps the example short.
    actual=lambda summary: max(1, len(summary) * 5),
    action_kind="llm.completion",
    action_name="openai:gpt-4o",
)
def generate_summary(document: str) -> str:
    return openai.chat.completions.create(...).choices[0].message.content

def summarize_or_fallback(document: str) -> str:
    try:
        return generate_summary(document)
    except BudgetExceededError:
        return "Summary unavailable — budget limit reached."

Pattern (TypeScript) ​

typescript
import {
  CyclesClient, CyclesConfig, BudgetExceededError,
  withCycles, setDefaultClient,
} from "runcycles";

setDefaultClient(new CyclesClient(CyclesConfig.fromEnv()));

const generateSummary = withCycles(
  {
    estimate: 2_000_000,
    // Prefer provider usage/cost metadata (e.g. response.usage.total_tokens)
    // when available. This length-based placeholder keeps the example short.
    actual: (summary: string) => Math.max(1, summary.length * 5),
    actionKind: "llm.completion",
    actionName: "openai:gpt-4o",
  },
  async (document: string) => (await openai.chat.completions.create({ ... })).choices[0].message.content!,
);

Pattern (Java / Spring) ​

java
@Cycles(value = "2000000",
        // Adapt #result.usage.totalTokens to your client's response shape.
        actual = "#result.usage.totalTokens * 8",
        actionKind = "llm.completion",
        actionName = "openai:gpt-4o")
public ChatResponse generateSummary(String document) {
    return openAiClient.chat(document);
}

Pattern (Rust) ​

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

let result = with_cycles(
    &client,
    WithCyclesConfig::new(Amount::usd_microcents(2_000_000))
        .action("llm.completion", "openai:gpt-4o"),
    |_ctx| async move {
        let summary = call_openai(document).await?;
        Ok((summary, Amount::usd_microcents(actual_cost)))
    },
).await;

match result {
    Ok(s) => s,
    Err(Error::BudgetExceeded { .. }) => "Summary unavailable — budget limit reached.".into(),
    Err(e) => return Err(e.into()),
}

Required test (sketch) ​

python
# pytest — mock Cycles DENY, then assert OpenAI is not called
import importlib
from unittest.mock import MagicMock

def test_openai_not_called_on_deny(monkeypatch, httpx_mock):
    monkeypatch.setenv("CYCLES_BASE_URL", "http://cycles.test")
    monkeypatch.setenv("CYCLES_API_KEY", "test-key")
    monkeypatch.setenv("CYCLES_TENANT", "acme-corp")
    httpx_mock.add_response(
        method="POST",
        url="http://cycles.test/v1/reservations",
        status_code=409,
        json={
            "error": "BUDGET_EXCEEDED",
            "message": "budget exhausted",
            "request_id": "req_test_123",
        },
    )

    import myapp.summary as summary
    summary = importlib.reload(summary)  # rebuild CyclesConfig.from_env() with test env
    fake_openai = MagicMock()
    monkeypatch.setattr(summary, "openai", fake_openai)

    result = summary.summarize_or_fallback("doc")

    assert "budget limit reached" in result
    fake_openai.chat.completions.create.assert_not_called()

Reference docs ​

Protocol references (only if the SDK doesn't expose what you need) ​