Circuit breakers
A ‡ Circuit breaker watches what flows past it and reacts when a condition fires — stopping the run, starving a branch, or parking for a human.
Breakers are reactive, not predictive. They read live metrics after steps have run; they are not a cost forecast.
One node, two outcomes. The mode decides what it watches; the action decides what happens when it fires.
Two layers
Section titled “Two layers”| Layer | Scope | Where |
|---|---|---|
| Graph spend ceiling | The whole run | ≔ params → spend ceiling (USD) |
| Circuit breaker node | One wire / one branch | Dropped on the canvas |
The ceiling is checked between parallelism waves and aborts the run. Nodes are checked when the wire carries a value.
| Mode | Trips when | Configure |
|---|---|---|
| spend | Run spend ≥ threshold | thresholdUsd |
| tokens | Inbound tokens ≥ threshold (known session tokens, else a chars ÷ 4 estimate) | thresholdTokens |
| duration | Wall-clock since run start ≥ threshold | thresholdMs |
| content | Text is empty, shorter than a minimum, or matches / fails to match a regex | minChars, pattern, tripOnMatch |
| retries | Accumulated run failures ≥ threshold | thresholdRetries |
Content is the subtle one. With a pattern and tripOnMatch: true it fires when the text matches (catch ERROR). Left false, it fires when the text fails to match — an assertion that the output contains what it must. With neither minChars nor pattern, it simply trips on empty text.
An invalid regex trips rather than passing silently, so a broken guard can’t pretend to be a working one.
Actions
Section titled “Actions”| Action | Effect |
|---|---|
| abort | Stop the run |
| skip | Fail this node; downstream starves; the rest of the graph continues |
| park | Pause and hand the text to a human — the same editable dock as an approval gate |
Detached runs have nobody to ask: with --approve-all a parked circuit breaker auto-passes and says so in the log. Without it, the run refuses to start.
Reading the log
Section titled “Reading the log”Every evaluation is logged, whether it fires or not:
‡ circuit breaker ok — spend $0.8400 < $5‡ circuit breaker — content did not match /PASS/ → parkThat makes a quiet circuit breaker auditable: you can prove the guard ran and saw a healthy value.
Patterns
Section titled “Patterns”The seatbelt. A spend ceiling on every graph you run unattended. Costs nothing, prevents the runaway.
The quality gate. content + minChars after a drafting agent — a two-sentence “draft” parks for review instead of flowing into the implement stage.
The assertion. content + pattern: "All tests pass" on a test-runner branch: trips when the phrase is absent.
The deadline. duration + skip on an optional enrichment branch: if the run is already slow, drop the nice-to-have and keep going.
The flake budget. retries + abort at 3 — tolerate two hiccups, give up on the third.
Examples
Section titled “Examples”▶ Content breaker · Min-chars breaker · Spend ceiling · Token breaker · Guarded parallel
Related
Section titled “Related”- Errors & retries — per-node failure policy
- Splice — what park hands you
- Costs & billing — where spend numbers come from