techrevati-runtime 0.2.0__tar.gz → 0.3.0.dev1__tar.gz

{techrevati_runtime-0.2.0 → techrevati_runtime-0.3.0.dev1}/CHANGELOG.md

@@ -5,6 +5,135 @@ follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html), with the
 caveat that 0.x APIs are explicitly unstable.
 
+## [0.3.0.dev1] — 2026-05-22
+
+First preview of the 0.3.0 milestone (EU AI Act compliance release).
+Bundles Sprint 2 (governance plane + async guardrails) and Sprint 3
+(streaming + mutating hook chain) plus all the 0.2.1 sharp-edges
+fixes — 0.2.1 itself was committed but never tagged for PyPI, so its
+fixes ride into 0.3.0 instead. Install with
+`pip install --pre techrevati-runtime` to try the preview; the stable
+channel still resolves to 0.2.0.
+
+This is a **dev release** (PEP 440 `.dev1`). API surface is
+forward-compatible with planned 0.3.0 features but may shift before the
+final cut; pin to `==0.3.0.dev1` if you depend on the exact surface.
+
+### Added — Sprint 3 (streaming + lifecycle hooks)
+
+- **`AsyncOrchestrationSession.arun_turn_stream`** — structured
+  `StreamEvent` generator that reemits caller-produced text chunks and
+  terminates with a `final` event carrying the resolved usage snapshot.
+  Participates in the full session bookkeeping (iteration cap,
+  governance plane, rate limiter, usage tracker) exactly like
+  `arun_turn`. Cancellation is consumer-driven: wrap with
+  `contextlib.aclosing` to get deterministic cleanup of the upstream
+  generator; `session._last_stream_cancelled` flips to `True` on the
+  cancelled path.
+- **`StreamEvent`** frozen dataclass + classmethod constructors
+  (`text`, `tool_call`, `tool_result`, `handoff`, `final`, `error`),
+  `to_dict()` / `to_json()` for wire serialization. `StreamEventType`
+  and `StreamFinalStatus` type aliases exported for consumer typing.
+- **`Hook` + `AsyncHook` Protocols** — interceptor chain that *mutates*
+  data, in contrast to the observe-only `EventSink`. Methods are
+  optional via `hasattr` dispatch; implement only what you need.
+- **`HookContext`** — mutable dataclass shared across the hook chain.
+  Fields: `role`, `phase`, `model`, `prompt`, `tool`, `args`, `extra`.
+  Pass via `hook_ctx=` on `run_turn` / `arun_turn` / `run_tool` /
+  `arun_tool` / `arun_turn_stream`.
+- **`AgentSession(hooks=[...])`** — hook chain wired through every
+  sync + async session. Chain runs left-to-right; later hooks see
+  earlier mutations.
+- **Built-in hooks:** `RedactPIIHook` (best-effort PII scrubbing for
+  strings, dicts, OpenAI-style message lists; runs `before_model` and
+  `after_model`), `LogModelIOHook` (stdlib logger emits model input +
+  output with truncation), `TokenBudgetCheckHook` (pre-flight token
+  budget guard that raises `HookBudgetExceededError`).
+- **Docs:** `docs/patterns/streaming.md`, `docs/patterns/hooks.md`,
+  plus API reference stubs `docs/api/streaming.md`,
+  `docs/api/hooks.md`; mkdocs nav updated.
+
+### Added — Sprint 2 (governance plane + async guardrails)
+
+- **`GovernancePlane`** primitive — hard-stop limit enforcement
+  *outside* agent code, terminal on breach (does NOT route through
+  recovery). Built-in limits: `MaxIterationsLimit`, `MaxBudgetLimit`,
+  `MaxConsecutiveFailuresLimit`, `MaxToolCallsLimit`. Each carries a
+  `value`, `scope` (`session` for now), and `on_breach` mode
+  (`terminate` raises `GovernanceBreachError`; `alert` emits
+  `governance.alert` events and continues).
+- **`AgentSession(governance=...)`** wired through both sync and async
+  sessions. The plane ticks turn counter pre-turn, tool counter
+  pre-tool, and cost / success-streak post-turn.
+- **`AsyncGuardrail`** Protocol (`acheck_pre` / `acheck_post`) for
+  guardrails that need I/O. Mixed sync + async guardrail lists
+  supported on async sessions.
+- **`PatternGuardrail`** (regex deny-list, one compiled alternation
+  per instance) and **`PromptInjectionGuardrail`** (subclass with 11
+  canonical injection signatures: instruction override, role hijack,
+  delimiter abuse, base64 blob, system-prompt extraction).
+- **`governance.breach`** + **`governance.alert`** event names in
+  `AgentEventName` — emitted via `EventSink` before the breach
+  exception raises so audit logs catch them even when the exception
+  propagates past handlers.
+- **Docs:** `docs/patterns/governance.md` + `docs/api/governance.md`.
+
+## [0.2.1] — 2026-05-20
+
+Sharp-edges patch landed the same day as 0.2.0 to close silent footguns
+identified in the 0.3.0 migration audit. No new primitives; one
+intentional soft-breaking semantic change to `GuardrailViolatedError`
+(callers reading the legacy single-violation fields still work — see
+"Changed" below).
+
+### Fixed
+
+- **`RecoveryRecipe.step_retries` is now honored** by `attempt_recovery`
+  and `aattempt_recovery`. Previously the field existed on the dataclass
+  but the recovery executors did not consume it — a recipe that set
+  `step_retries={RecoveryStep.RETRY_WITH_BACKOFF: 3}` silently ran the
+  step exactly once. Now the executor retries the step up to the
+  budgeted count before moving to the next step. Missing keys default
+  to a single attempt, preserving 0.2.0 behavior.
+- **`OpenTelemetrySink` cleans up orphan parent spans on interpreter
+  exit.** If a process died between `AGENT_STARTED` / `PHASE_STARTED`
+  and the matching `AGENT_COMPLETED` / `AGENT_FAILED` / `PHASE_COMPLETED`,
+  the parent span previously stayed open in the exporter buffer and
+  corrupted the APM trace tree. An `atexit` hook now marks every
+  still-open parent with `error.type=abrupt_termination` and an `ERROR`
+  status before ending it. The hook is no-op on the clean-exit path.
+
+### Added
+
+- **`register_pricing(model, pricing, *, on_conflict="overwrite")`** — explicit
+  merge semantics. `"overwrite"` (default) preserves 0.2.0 behavior;
+  `"error"` raises `PricingAlreadyRegisteredError` on re-registration;
+  `"keep"` retains the existing entry and drops the new pricing silently.
+  Useful for "register defaults if not present" startup patterns.
+- **`PricingAlreadyRegisteredError`** — exported from
+  `techrevati.runtime`. Subclass of `ValueError`, carries `.model`.
+- **`GuardrailViolation`** dataclass — one entry in the new
+  `GuardrailViolatedError.violations` tuple. Carries `outcome`,
+  `guardrail` (name), `stage` (`"pre"` / `"post"`). Has `to_dict()` for
+  audit-log serialization.
+- **`DeprecationWarning` on `Orchestrator(...)` instantiation** — emitted
+  once per process. `AgentSession` has been the canonical class name
+  since 0.2.0; the alias remains for a deprecation window and will be
+  removed in 0.3.0. Silent in import — only the first construction
+  warns.
+
+### Changed
+
+- **`GuardrailViolatedError.violations`** — every guardrail that fires
+  at the same stage is now collected and surfaced as a tuple on the
+  raised error, instead of short-circuiting on the first violation.
+  Required for EU AI Act Article 12 record-keeping (audit logs must
+  reflect the full set of guardrails that fired). Legacy callers that
+  read `error.outcome` / `error.guardrail` / `error.stage` still work —
+  those attributes mirror the first violation. The orchestrator now
+  runs every pre-check and post-check before raising; tests that
+  asserted short-circuit behavior have been updated.
+
 ## [0.2.0] — 2026-05-20
 
 Durable execution, token-aware rate limiting, OTel agent-level span

{techrevati_runtime-0.2.0 → techrevati_runtime-0.3.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: techrevati-runtime
-Version: 0.2.0
+Version: 0.3.0.dev1
 Summary: Async-aware runtime primitives for multi-step LLM agent loops.
 Project-URL: Homepage, https://github.com/Techrevati/runtime
 Project-URL: Documentation, https://Techrevati.github.io/runtime
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-green.svg)](#design-goals)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Production-grade runtime primitives for multi-step LLM agent loops — sync **and** async, with retry classification, circuit-breaker protection, per-model cost tracking, opt-in budget enforcement, role-based tool gating, content guardrails, agent-to-agent handoffs, declarative policy, and OpenTelemetry GenAI semantic conventions out of the box. **Beta — 0.1.x; minor breaking changes possible until 0.2.0.**
+Production-grade runtime primitives for multi-step LLM agent loops — sync **and** async, with retry classification, circuit-breaker protection, per-model cost tracking, opt-in budget enforcement, role-based tool gating, content guardrails, agent-to-agent handoffs, declarative policy, durable checkpointing, token-aware rate limiting, and OpenTelemetry GenAI semantic conventions out of the box. **Beta — 0.2.x; 0.x APIs remain explicitly unstable.**
 
 ```bash
 pip install techrevati-runtime
@@ -190,20 +190,20 @@ print(tracker.format_cost())
 - **OpenAI Agents SDK** is a *cohesive runtime* tied to OpenAI's models, with default tracing through their dashboards. Use it when you're committed to OpenAI and want the smoothest path.
 - **`techrevati-runtime`** is a *zero-dep primitive set*. Sync + async. Vendor-neutral. Emits OpenTelemetry GenAI semantic conventions so the same APM dashboards that consume OpenAI Agents SDK telemetry will pick us up too. Bring your own model client and your own persistence — the runtime stays opinion-free.
 
-The runtime is **not** a durable workflow engine. Sessions are in-memory; a pluggable checkpointer is on the 0.2.0 roadmap. If you need restart-resumable workflows today, pair this with [Temporal](https://temporal.io/), [dbos](https://www.dbos.dev/), or LangGraph's checkpointer.
+The runtime ships a pluggable `CheckpointSaver` protocol with `InMemorySaver` and `SqliteSaver` implementations (0.2.0) — enough for resume-from-checkpoint replay across restarts. It is still not a full durable workflow engine in the Temporal sense; pair with [Temporal](https://temporal.io/), [dbos](https://www.dbos.dev/), or LangGraph's checkpointer if you need cross-host scheduling, retries-as-history, or a durable timer service.
 
 ## Limitations (be honest with yourself before adopting)
 
 - **Pricing must be registered.** The bundled `pricing.json` is intentionally empty. Without `register_pricing()` or `load_pricing_from_file()`, every cost calculation returns $0.00 (you will see a one-time warning per model).
 - **Budget enforcement is opt-in.** Set `Orchestrator(enforce_budget=True)` to raise `BudgetExceededError`; the default merely records an event and continues.
 - **Permissions are advisory.** `OrchestrationSession.run_tool()` enforces; `run_turn()` does not gate model calls. There is no sandbox — pair with OS-level isolation if needed.
-- **No durable execution.** Sessions are in-memory and ephemeral. Pair with Temporal/dbos for restart-resumable workflows.
+- **Durable execution is opt-in.** Default sessions are in-memory; pass a `CheckpointSaver` (e.g. `SqliteSaver`) plus a stable `thread_id` to get resume-from-checkpoint replay. Pair with Temporal/dbos if you need cross-host scheduling or durable timers.
 - **Default sinks are in-memory ring buffers.** Long-running sessions need a durable `EventSink` and `UsageSink` (e.g. `OpenTelemetrySink`, or your own).
 - **`CircuitBreaker` state is per-process.** Each replica counts its own failures. Add a shared coordinator if you need fleet-wide breaker state.
 
 ## Status
 
-`techrevati-runtime` is at version **0.1.0** (beta). This release ships async-first execution, the four standard primitives (Sessions, Tools, Handoffs, Guardrails), `max_iterations` cap, and OpenTelemetry GenAI semantic conventions. Minor breaking changes are possible between 0.1.x and 0.2.0 — they will be documented in [docs/migrating-from-0.0.x.md](docs/migrating-from-0.0.x.md) and gated by deprecation warnings. Pinning Python 3.11+ for `from __future__ import annotations` ergonomics and modern asyncio.
+`techrevati-runtime` is at version **0.2.0** (beta). This release ships durable execution (`CheckpointSaver` + `SqliteSaver`), token-aware rate limiting (`RateLimiter` / `AsyncRateLimiter`), provider routing, per-session `UsageLimits`, nested OTel agent spans, persistent SQLite sinks, and supply-chain hardening (CycloneDX SBOM + CodeQL + zero-deps smoke). The `AgentSession` rename and OTel wire-format change are the two soft-breaking items — see [docs/migrating-from-0.1.x.md](docs/migrating-from-0.1.x.md). 0.x APIs remain unstable; breaking changes will continue to be gated by deprecation warnings. Pinning Python 3.11+ for `from __future__ import annotations` ergonomics and modern asyncio.
 
 See [CHANGELOG.md](CHANGELOG.md) for the per-sprint release notes and [docs/tutorials/end-to-end.md](docs/tutorials/end-to-end.md) for a guided tour of every primitive.
 

{techrevati_runtime-0.2.0 → techrevati_runtime-0.3.0.dev1}/README.md

@@ -6,7 +6,7 @@
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-green.svg)](#design-goals)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Production-grade runtime primitives for multi-step LLM agent loops — sync **and** async, with retry classification, circuit-breaker protection, per-model cost tracking, opt-in budget enforcement, role-based tool gating, content guardrails, agent-to-agent handoffs, declarative policy, and OpenTelemetry GenAI semantic conventions out of the box. **Beta — 0.1.x; minor breaking changes possible until 0.2.0.**
+Production-grade runtime primitives for multi-step LLM agent loops — sync **and** async, with retry classification, circuit-breaker protection, per-model cost tracking, opt-in budget enforcement, role-based tool gating, content guardrails, agent-to-agent handoffs, declarative policy, durable checkpointing, token-aware rate limiting, and OpenTelemetry GenAI semantic conventions out of the box. **Beta — 0.2.x; 0.x APIs remain explicitly unstable.**
 
 ```bash
 pip install techrevati-runtime
@@ -149,20 +149,20 @@ print(tracker.format_cost())
 - **OpenAI Agents SDK** is a *cohesive runtime* tied to OpenAI's models, with default tracing through their dashboards. Use it when you're committed to OpenAI and want the smoothest path.
 - **`techrevati-runtime`** is a *zero-dep primitive set*. Sync + async. Vendor-neutral. Emits OpenTelemetry GenAI semantic conventions so the same APM dashboards that consume OpenAI Agents SDK telemetry will pick us up too. Bring your own model client and your own persistence — the runtime stays opinion-free.
 
-The runtime is **not** a durable workflow engine. Sessions are in-memory; a pluggable checkpointer is on the 0.2.0 roadmap. If you need restart-resumable workflows today, pair this with [Temporal](https://temporal.io/), [dbos](https://www.dbos.dev/), or LangGraph's checkpointer.
+The runtime ships a pluggable `CheckpointSaver` protocol with `InMemorySaver` and `SqliteSaver` implementations (0.2.0) — enough for resume-from-checkpoint replay across restarts. It is still not a full durable workflow engine in the Temporal sense; pair with [Temporal](https://temporal.io/), [dbos](https://www.dbos.dev/), or LangGraph's checkpointer if you need cross-host scheduling, retries-as-history, or a durable timer service.
 
 ## Limitations (be honest with yourself before adopting)
 
 - **Pricing must be registered.** The bundled `pricing.json` is intentionally empty. Without `register_pricing()` or `load_pricing_from_file()`, every cost calculation returns $0.00 (you will see a one-time warning per model).
 - **Budget enforcement is opt-in.** Set `Orchestrator(enforce_budget=True)` to raise `BudgetExceededError`; the default merely records an event and continues.
 - **Permissions are advisory.** `OrchestrationSession.run_tool()` enforces; `run_turn()` does not gate model calls. There is no sandbox — pair with OS-level isolation if needed.
-- **No durable execution.** Sessions are in-memory and ephemeral. Pair with Temporal/dbos for restart-resumable workflows.
+- **Durable execution is opt-in.** Default sessions are in-memory; pass a `CheckpointSaver` (e.g. `SqliteSaver`) plus a stable `thread_id` to get resume-from-checkpoint replay. Pair with Temporal/dbos if you need cross-host scheduling or durable timers.
 - **Default sinks are in-memory ring buffers.** Long-running sessions need a durable `EventSink` and `UsageSink` (e.g. `OpenTelemetrySink`, or your own).
 - **`CircuitBreaker` state is per-process.** Each replica counts its own failures. Add a shared coordinator if you need fleet-wide breaker state.
 
 ## Status
 
-`techrevati-runtime` is at version **0.1.0** (beta). This release ships async-first execution, the four standard primitives (Sessions, Tools, Handoffs, Guardrails), `max_iterations` cap, and OpenTelemetry GenAI semantic conventions. Minor breaking changes are possible between 0.1.x and 0.2.0 — they will be documented in [docs/migrating-from-0.0.x.md](docs/migrating-from-0.0.x.md) and gated by deprecation warnings. Pinning Python 3.11+ for `from __future__ import annotations` ergonomics and modern asyncio.
+`techrevati-runtime` is at version **0.2.0** (beta). This release ships durable execution (`CheckpointSaver` + `SqliteSaver`), token-aware rate limiting (`RateLimiter` / `AsyncRateLimiter`), provider routing, per-session `UsageLimits`, nested OTel agent spans, persistent SQLite sinks, and supply-chain hardening (CycloneDX SBOM + CodeQL + zero-deps smoke). The `AgentSession` rename and OTel wire-format change are the two soft-breaking items — see [docs/migrating-from-0.1.x.md](docs/migrating-from-0.1.x.md). 0.x APIs remain unstable; breaking changes will continue to be gated by deprecation warnings. Pinning Python 3.11+ for `from __future__ import annotations` ergonomics and modern asyncio.
 
 See [CHANGELOG.md](CHANGELOG.md) for the per-sprint release notes and [docs/tutorials/end-to-end.md](docs/tutorials/end-to-end.md) for a guided tour of every primitive.
 

techrevati_runtime-0.3.0.dev1/docs/api/governance.md

@@ -0,0 +1,3 @@
+# API: `techrevati.runtime.governance`
+
+::: techrevati.runtime.governance

techrevati_runtime-0.3.0.dev1/docs/api/hooks.md

@@ -0,0 +1,3 @@
+# Hooks
+
+::: techrevati.runtime.hooks

techrevati_runtime-0.3.0.dev1/docs/api/streaming.md

@@ -0,0 +1,3 @@
+# Streaming
+
+::: techrevati.runtime.streaming

techrevati_runtime-0.3.0.dev1/docs/patterns/governance.md

@@ -0,0 +1,194 @@
+# Governance Plane
+
+`GovernancePlane` is the runtime's last line of defense: hard-stop
+limits enforced *outside* agent code so the agent cannot bypass them
+via recovery. When a limit configured with `on_breach="terminate"` is
+exceeded, the orchestrator raises `GovernanceBreachError`, which the
+session marks as `FAILED` and re-raises **without** going through the
+failure classifier or the recovery loop.
+
+This is the technical primitive auditors expect for EU AI Act
+deployments — Article 14 (human oversight via stopping conditions),
+Article 15 (robustness / fail-safes), and Article 26 (deployer
+monitoring + reporting). The full article-by-article compliance mapping
+ships in 0.3.0 Sprint 6 (`docs/compliance/`).
+
+## When to use this
+
+- **You ship to EU customers** and any user-deployed system would meet
+  the Annex III "high-risk" definition. Article 9 risk management,
+  Article 12 record-keeping, and Article 26 deployer-side monitoring
+  all want a runtime kill-switch.
+- **Cost is dollars per token, not milliseconds per request.** A
+  budget cap that the agent could in principle catch + recover from is
+  not a hard cap. `MaxBudgetLimit(on_breach="terminate")` is.
+- **The agent runs unattended and must stop on its own.** Production
+  multi-step agent loops can drift; a 25-turn iteration cap + a
+  consecutive-failure cap rules out the canonical runaway-loop
+  failure mode.
+- **You need a rollout signal before flipping a knob to hard-stop.**
+  Use `on_breach="alert"` first; measure breach rates from the
+  `governance.alert` events; flip to `"terminate"` when you trust the
+  threshold.
+
+## When NOT to use this
+
+- For *recoverable* token / cost ceilings inside one session that the
+  agent is allowed to react to. Use [`UsageLimits`](usage-tracking.md)
+  instead — its `UsageLimitExceededError` is catchable and recovery
+  flows can respond.
+- For per-tool authorization. Use [`PermissionEnforcer`](permissions.md).
+- For pattern blocking on tool inputs or outputs. Use the
+  built-in `PatternGuardrail` / `PromptInjectionGuardrail` (or a
+  custom `Guardrail`) — see [Permissions](permissions.md) and
+  [API: Guardrails](../api/guardrails.md).
+
+## Quickstart
+
+```python
+from techrevati.runtime import (
+    AgentSession,
+    GovernancePlane,
+    MaxBudgetLimit,
+    MaxConsecutiveFailuresLimit,
+    MaxIterationsLimit,
+    MaxToolCallsLimit,
+)
+
+plane = GovernancePlane(
+    limits=(
+        MaxIterationsLimit(value=25, on_breach="terminate"),
+        MaxBudgetLimit(value=5.00, on_breach="terminate"),
+        MaxConsecutiveFailuresLimit(value=3, on_breach="terminate"),
+        MaxToolCallsLimit(value=100, on_breach="alert"),
+    ),
+)
+
+session = AgentSession(role="writer", phase="draft", governance=plane)
+```
+
+The orchestrator ticks the plane's counters at three points:
+
+- **Pre-turn** — `record_turn_start()` and `enforce()`. The iteration
+  cap fires here.
+- **Pre-tool** — `record_tool_call()` and `enforce()`. The tool-call
+  cap fires here.
+- **Post-turn** — `record_success()` or `record_failure()`,
+  `record_cost(cost_delta)`, and `enforce()`. The budget and
+  consecutive-failures caps fire here.
+
+## The four built-in limits
+
+### `MaxIterationsLimit`
+
+Caps total turns in the session. Distinct from
+`AgentSession.max_iterations` — that one raises a recoverable
+`MaxIterationsExceededError`; this one is terminal.
+
+```python
+MaxIterationsLimit(value=25, on_breach="terminate")
+```
+
+### `MaxBudgetLimit`
+
+Caps cumulative cost in USD. Distinct from `UsageLimits.cost_usd_max`
+— that one is recoverable; this one is terminal.
+
+```python
+MaxBudgetLimit(value=5.00, on_breach="terminate")
+```
+
+### `MaxConsecutiveFailuresLimit`
+
+Counts consecutive failures. A single successful turn resets the
+counter to zero. Catches "the agent retries the same broken thing
+forever" failure modes that per-step retry budgets alone do not.
+
+```python
+MaxConsecutiveFailuresLimit(value=3, on_breach="terminate")
+```
+
+### `MaxToolCallsLimit`
+
+Caps total tool invocations in the session. Distinct from
+`UsageLimits.tool_calls_max` only in being terminal.
+
+```python
+MaxToolCallsLimit(value=100, on_breach="alert")
+```
+
+## `on_breach` modes
+
+| Mode | Behavior |
+|---|---|
+| `"terminate"` (default) | Raises `GovernanceBreachError`. Worker → `FAILED`. Recovery loop is **NOT** invoked. |
+| `"alert"` | Emits a `governance.alert` event on every breached evaluation. Session continues. |
+
+Rolling out a new limit safely: deploy with `"alert"` for 1–2 weeks,
+observe the `governance.alert` event rate, then flip to `"terminate"`.
+
+## Event surface
+
+Two new `AgentEventName` values surface in 0.3.0:
+
+- `governance.breach` — emitted **before** `GovernanceBreachError`
+  raises so downstream sinks see the breach in the audit log even when
+  the exception propagates past them.
+- `governance.alert` — emitted once per evaluation per breached
+  alert-mode limit.
+
+Both carry `data = {limit_name, observed, ceiling, scope}` for sink
+serialization.
+
+## Composing with `UsageLimits`
+
+These two primitives are not redundant — they sit at different layers.
+
+```python
+sess = AgentSession(
+    role="writer",
+    phase="draft",
+    # Soft cap: agent code can catch UsageLimitExceededError and react.
+    usage_limits=UsageLimits(total_tokens_max=200_000),
+    # Hard cap: governance breach terminates the session regardless.
+    governance=GovernancePlane(
+        limits=(MaxBudgetLimit(value=10.00, on_breach="terminate"),),
+    ),
+)
+```
+
+A common pattern is: `usage_limits` cap at 80% of the budget, `governance`
+hard-stop at 100%. The agent gets a recoverable warning before the
+session dies.
+
+## Tuning the knobs
+
+| Knob | Reasonable range | Notes |
+|---|---|---|
+| `MaxIterationsLimit.value` | 10–50 for production loops | Same default as OpenAI Agents SDK. |
+| `MaxBudgetLimit.value` | per-customer / per-session limit | Pair with `UsageLimits.cost_usd_max` at 80%. |
+| `MaxConsecutiveFailuresLimit.value` | 2–5 | Below 2 is twitchy; above 5 hides real reliability bugs. |
+| `MaxToolCallsLimit.value` | 5×–10× expected | Useful as an alert before flipping to terminate. |
+| `on_breach="alert"` | Always start here for new limits | Measure first, terminate second. |
+
+## Anti-patterns
+
+- **Catching `GovernanceBreachError` and retrying.** Don't. The point
+  of the plane is that the agent cannot bypass it. If you want
+  recoverable behavior, use `UsageLimits` instead.
+- **Putting business logic in `GovernanceState.record_*`.** The state
+  object is a counter; do not subclass it to fire side effects on
+  every tick. Add a custom `EventSink` for that.
+- **One plane per turn.** Construct the plane once and pass it to
+  `AgentSession`; do not create a new plane on each turn — counters
+  reset.
+- **Mixing `"alert"` and `"terminate"` randomly across limits.** Pick a
+  rollout phase per limit, document it, and don't half-migrate.
+
+## Sources
+
+- Waxell — *AI Agent Circuit Breakers: The Reliability Pattern Production
+  Teams Are Missing* — [https://dev.to/waxell/ai-agent-circuit-breakers-...](https://dev.to/waxell/ai-agent-circuit-breakers-the-reliability-pattern-production-teams-are-missing-5bpg)
+- DZone — *Engineering Hard-Stop Safety Into Autonomous Agent
+  Workflows* — [https://dzone.com/articles/algorithmic-circuit-breakers-agent-safety](https://dzone.com/articles/algorithmic-circuit-breakers-agent-safety)
+- EU AI Act Articles 9, 12, 14, 15, 26 — [artificialintelligenceact.eu](https://artificialintelligenceact.eu/section/3-2/)