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.
For routing to labeled branches (pass / fail / unsure), use a Judge instead. Fuse vs branch.
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”- Judge. Labeled multi-out routing (not a fuse)
- Errors & retries. Per-node failure policy
- Stdlib · token-estimate. Chars÷4 into a tokens breaker
- Splice. What park hands you
- Costs & billing. Where spend numbers come from