From 73caf6c4d5ff2893392b4b6b92003e7b28a0b0ca Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Sat, 2 May 2026 11:58:13 -0400 Subject: [PATCH 1/2] docs(profile): add architecture-at-a-glance Mermaid diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GitHub renders Mermaid natively in profile READMEs, so visitors landing on the org page now see the agent → SDK → Cycles → action → commit flow visually before they read the repo list. Two tweaks against the original proposal: - AGENT label trimmed to "AI agent"; supported runtimes moved to a caption line below the diagram so the node doesn't overflow on narrow viewports and so the runtime list is easier to maintain than YAML inside a Mermaid node. - Added a dashed return path from SDK to AGENT on DENY so the "synchronous authority check" claim is visually obvious. Sits right above "Start here" — visitors evaluating the org now get a mental model in the first ~3 seconds before scanning the repo links. --- profile/README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/profile/README.md b/profile/README.md index 16c5bad..f628ef7 100644 --- a/profile/README.md +++ b/profile/README.md @@ -10,6 +10,70 @@ --- +## Architecture at a glance + +Cycles sits between agent runtimes and downstream actions. Agents ask Cycles for authority before costly or risky work runs. If allowed, the action executes; afterward the agent commits actual usage or releases the reservation. + +```mermaid +flowchart LR + %% ========================= + %% Agent side + %% ========================= + subgraph APP["Agent application / workflow runtime"] + AGENT["AI agent"] + SDK["Cycles SDK / middleware
Python · TypeScript · Java · Rust · MCP"] + AGENT -->|"intent: subject + action + estimate"| SDK + end + + %% ========================= + %% Enforcement path + %% ========================= + SDK -->|"1. reserve before execution
POST /v1/reservations"| RUNTIME["Cycles Runtime Server
pre-execution authority"] + RUNTIME -->|"ALLOW + reservation_id
or DENY + reason"| SDK + SDK -.->|"on DENY: skip + surface reason"| AGENT + + SDK -->|"2. execute"| ACTIONS["Downstream actions
LLMs · tools · APIs · email · DB writes · jobs"] + ACTIONS -->|"actual usage / outcome"| SDK + + SDK -->|"3a. commit actual usage"| RUNTIME + SDK -->|"3b. release on cancel / failure"| RUNTIME + + %% ========================= + %% State and governance + %% ========================= + RUNTIME -->|"atomic reserve / commit / release"| STORE["State store
budgets · reservations · balances · quota counters"] + + ADMIN["Cycles Admin Server
tenants · budgets · policies · API keys"] --> STORE + DASH["Cycles Dashboard
operators / SaaS admins"] --> ADMIN + + RUNTIME -->|"events"| EVENTS["Events / webhooks
denials · overages · thresholds · audit trail"] + ADMIN -->|"governance events"| EVENTS + + %% ========================= + %% Styles + %% ========================= + classDef primary fill:#eef6ff,stroke:#2563eb,stroke-width:1px,color:#111827; + classDef runtime fill:#ecfdf5,stroke:#059669,stroke-width:1px,color:#111827; + classDef state fill:#fff7ed,stroke:#ea580c,stroke-width:1px,color:#111827; + classDef external fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#111827; + + class AGENT,SDK primary; + class RUNTIME,ADMIN,DASH runtime; + class STORE state; + class ACTIONS,EVENTS external; +``` + +> Works with LangGraph, CrewAI, OpenAI Agents SDK, MCP clients (Claude Desktop, Cursor, Windsurf), and custom runtimes via the SDKs. + +**The key idea:** Cycles is not a proxy and not a workflow engine. It does not execute tools or inspect payloads. It provides a synchronous authority check around actions that create cost, risk, or side effects. + +1. **Reserve** estimated exposure before the action runs. +2. **Execute** the LLM/tool/API call only if Cycles allows it. +3. **Commit** actual usage, or **release** the reservation if the action failed or was canceled. +4. **Enforce** budgets, action policies, tenant boundaries, retries, and concurrency from one runtime control point. + +--- + ## Start here New to Cycles? Start with the protocol, then choose the implementation surface you need. From 6d9faa5f5952974b8456d509de5576662c640b10 Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Sat, 2 May 2026 12:03:59 -0400 Subject: [PATCH 2/2] docs: simplify profile diagram, move full version to ARCHITECTURE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first iteration put the full architecture (11 nodes, governance plane, state store, events) on the org profile README. That's the right diagram for someone evaluating the system, but the wrong diagram for someone who just landed and is asking "what does this do?" Profile README now shows the minimal 4-node enforcement loop: agent → SDK → runtime → action, with reserve/commit return arrows. 6 arrows, 3 colors, reads in ~5 seconds on mobile. Full diagram moves to a new ARCHITECTURE.md at the repo root. It's discoverable from the profile diagram caption ("Want the full picture? See ARCHITECTURE.md"), preserved as a deep-dive reference, and easier to maintain as a standalone doc than as the README's lead visual. Component-level deep dive (ports, Lua scripts, auth, deployment topology) already lives at runcycles.io/quickstart/architecture-overview — linked from ARCHITECTURE.md so visitors can follow the trail. --- ARCHITECTURE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++ profile/README.md | 67 +++++++++--------------------------- 2 files changed, 104 insertions(+), 50 deletions(-) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..cc4e58f --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,87 @@ +# Runcycles — Full Architecture + +This is the deep-dive companion to the minimal diagram on the [org profile README](./profile/README.md). It shows the full picture: enforcement path, state store, governance plane, and event bus. + +For deployment topology, configuration, and component-level docs (ports, modules, Lua scripts, key provisioning), see the [Architecture Overview](https://runcycles.io/quickstart/architecture-overview-how-cycles-fits-together) on runcycles.io. + +## Full system diagram + +```mermaid +flowchart LR + %% ========================= + %% Agent side + %% ========================= + subgraph APP["Agent application / workflow runtime"] + AGENT["AI agent"] + SDK["Cycles SDK / middleware
Python · TypeScript · Java · Rust · MCP"] + AGENT -->|"intent: subject + action + estimate"| SDK + end + + %% ========================= + %% Enforcement path + %% ========================= + SDK -->|"1. reserve before execution
POST /v1/reservations"| RUNTIME["Cycles Runtime Server
pre-execution authority"] + RUNTIME -->|"ALLOW + reservation_id
or DENY + reason"| SDK + SDK -.->|"on DENY: skip + surface reason"| AGENT + + SDK -->|"2. execute"| ACTIONS["Downstream actions
LLMs · tools · APIs · email · DB writes · jobs"] + ACTIONS -->|"actual usage / outcome"| SDK + + SDK -->|"3a. commit actual usage"| RUNTIME + SDK -->|"3b. release on cancel / failure"| RUNTIME + + %% ========================= + %% State and governance + %% ========================= + RUNTIME -->|"atomic reserve / commit / release"| STORE["State store
budgets · reservations · balances · quota counters"] + + ADMIN["Cycles Admin Server
tenants · budgets · policies · API keys"] --> STORE + DASH["Cycles Dashboard
operators / SaaS admins"] --> ADMIN + + RUNTIME -->|"events"| EVENTS["Events / webhooks
denials · overages · thresholds · audit trail"] + ADMIN -->|"governance events"| EVENTS + + %% ========================= + %% Styles + %% ========================= + classDef primary fill:#eef6ff,stroke:#2563eb,stroke-width:1px,color:#111827; + classDef runtime fill:#ecfdf5,stroke:#059669,stroke-width:1px,color:#111827; + classDef state fill:#fff7ed,stroke:#ea580c,stroke-width:1px,color:#111827; + classDef external fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#111827; + + class AGENT,SDK primary; + class RUNTIME,ADMIN,DASH runtime; + class STORE state; + class ACTIONS,EVENTS external; +``` + +> Works with LangGraph, CrewAI, OpenAI Agents SDK, MCP clients (Claude Desktop, Cursor, Windsurf), and custom runtimes via the SDKs. + +## The key idea + +Cycles is not a proxy and not a workflow engine. It does not execute tools or inspect payloads. It provides a synchronous authority check around actions that create cost, risk, or side effects. + +1. **Reserve** estimated exposure before the action runs. +2. **Execute** the LLM/tool/API call only if Cycles allows it. +3. **Commit** actual usage, or **release** the reservation if the action failed or was canceled. +4. **Enforce** budgets, action policies, tenant boundaries, retries, and concurrency from one runtime control point. + +## Components shown above + +| Component | Role | Repo | +|---|---|---| +| **AI agent** | Your application or agent loop | — | +| **Cycles SDK / middleware** | Wraps reserve/commit lifecycle around agent calls | [Python](https://github.com/runcycles/cycles-client-python) · [TypeScript](https://github.com/runcycles/cycles-client-typescript) · [Java](https://github.com/runcycles/cycles-spring-boot-starter) · [Rust](https://github.com/runcycles/cycles-client-rust) · [MCP](https://github.com/runcycles/cycles-mcp-server) | +| **Cycles Runtime Server** | Atomic reserve/commit/release on every request | [cycles-server](https://github.com/runcycles/cycles-server) | +| **Cycles Admin Server** | Tenants, budgets, policies, API keys | [cycles-server-admin](https://github.com/runcycles/cycles-server-admin) | +| **Cycles Dashboard** | Operator UI for the admin server | [cycles-dashboard](https://github.com/runcycles/cycles-dashboard) | +| **State store** | Redis (budgets, reservations, balances, quota counters) | — | +| **Events / webhooks** | Async delivery of denials, overages, audit events | [cycles-server-events](https://github.com/runcycles/cycles-server-events) | +| **Downstream actions** | The LLMs, tools, APIs, and writes Cycles governs | — | + +## Where to go next + +- **Get the protocol** — [cycles-protocol](https://github.com/runcycles/cycles-protocol) for the OpenAPI spec +- **Run it** — [Deploy the Full Stack](https://runcycles.io/quickstart/deploying-the-full-cycles-stack) +- **See it stop a runaway agent** — [cycles-runaway-demo](https://github.com/runcycles/cycles-runaway-demo) +- **Component-level deep dive** — [Architecture Overview on runcycles.io](https://runcycles.io/quickstart/architecture-overview-how-cycles-fits-together) (ports, Lua scripts, auth schemes, deployment topology) diff --git a/profile/README.md b/profile/README.md index f628ef7..ef13816 100644 --- a/profile/README.md +++ b/profile/README.md @@ -12,65 +12,32 @@ ## Architecture at a glance -Cycles sits between agent runtimes and downstream actions. Agents ask Cycles for authority before costly or risky work runs. If allowed, the action executes; afterward the agent commits actual usage or releases the reservation. - ```mermaid flowchart LR - %% ========================= - %% Agent side - %% ========================= - subgraph APP["Agent application / workflow runtime"] - AGENT["AI agent"] - SDK["Cycles SDK / middleware
Python · TypeScript · Java · Rust · MCP"] - AGENT -->|"intent: subject + action + estimate"| SDK - end - - %% ========================= - %% Enforcement path - %% ========================= - SDK -->|"1. reserve before execution
POST /v1/reservations"| RUNTIME["Cycles Runtime Server
pre-execution authority"] - RUNTIME -->|"ALLOW + reservation_id
or DENY + reason"| SDK - SDK -.->|"on DENY: skip + surface reason"| AGENT - - SDK -->|"2. execute"| ACTIONS["Downstream actions
LLMs · tools · APIs · email · DB writes · jobs"] - ACTIONS -->|"actual usage / outcome"| SDK - - SDK -->|"3a. commit actual usage"| RUNTIME - SDK -->|"3b. release on cancel / failure"| RUNTIME - - %% ========================= - %% State and governance - %% ========================= - RUNTIME -->|"atomic reserve / commit / release"| STORE["State store
budgets · reservations · balances · quota counters"] - - ADMIN["Cycles Admin Server
tenants · budgets · policies · API keys"] --> STORE - DASH["Cycles Dashboard
operators / SaaS admins"] --> ADMIN - - RUNTIME -->|"events"| EVENTS["Events / webhooks
denials · overages · thresholds · audit trail"] - ADMIN -->|"governance events"| EVENTS - - %% ========================= - %% Styles - %% ========================= + AGENT["AI agent"] + SDK["Cycles SDK"] + RUNTIME["Cycles Runtime
authority check"] + ACTION["LLM · tool · API · write"] + + AGENT -->|"intent + estimate"| SDK + SDK -->|"1. reserve"| RUNTIME + RUNTIME -->|"ALLOW or DENY"| SDK + SDK -->|"2. execute (if ALLOW)"| ACTION + ACTION -->|"actual usage"| SDK + SDK -->|"3. commit / release"| RUNTIME + classDef primary fill:#eef6ff,stroke:#2563eb,stroke-width:1px,color:#111827; classDef runtime fill:#ecfdf5,stroke:#059669,stroke-width:1px,color:#111827; - classDef state fill:#fff7ed,stroke:#ea580c,stroke-width:1px,color:#111827; - classDef external fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#111827; + classDef action fill:#f8fafc,stroke:#64748b,stroke-width:1px,color:#111827; class AGENT,SDK primary; - class RUNTIME,ADMIN,DASH runtime; - class STORE state; - class ACTIONS,EVENTS external; + class RUNTIME runtime; + class ACTION action; ``` -> Works with LangGraph, CrewAI, OpenAI Agents SDK, MCP clients (Claude Desktop, Cursor, Windsurf), and custom runtimes via the SDKs. - -**The key idea:** Cycles is not a proxy and not a workflow engine. It does not execute tools or inspect payloads. It provides a synchronous authority check around actions that create cost, risk, or side effects. +The agent declares intent, the SDK reserves with the Cycles runtime, executes only if allowed, then commits actual usage or releases the reservation. Cycles is a synchronous authority check — not a proxy, not a workflow engine. -1. **Reserve** estimated exposure before the action runs. -2. **Execute** the LLM/tool/API call only if Cycles allows it. -3. **Commit** actual usage, or **release** the reservation if the action failed or was canceled. -4. **Enforce** budgets, action policies, tenant boundaries, retries, and concurrency from one runtime control point. +> Want the full picture (admin server, dashboard, state store, events)? See **[ARCHITECTURE.md](../ARCHITECTURE.md)**. ---