System Manual
The Harness
The layer that wraps every agent run: a credit check, trust gates, a circuit breaker, retries with timeouts, model escalation, and an evaluator that double-checks high-stakes agents.
Every run goes through the harness
The harness wraps every run. In order, one call through it does a credit pre-check, a model downshift if the plan needs one, a trust gate, a circuit-breaker check, a retry loop with timeouts, and model escalation. For high-stakes agents it then runs an evaluator. The orchestrator calls the harness for every node, so nothing reaches your systems without passing through it.
The defaults at a glance
| Max retries | 2 (3 attempts total) |
| Backoff | Exponential: 800 ms, then 1,600 ms |
| Per-attempt timeout | 120 seconds (120,000 ms) |
| Circuit breaker threshold | 5 consecutive failures → circuit opens |
| Circuit breaker reset | Auto-resets 5 minutes (300,000 ms) after opening |
| Escalation threshold | Fast-tier (Gemini Flash) confidence < 0.72 → retry once on claude-opus-4-6 (plan-gated) |
| Evaluator | Runs after the 6 high-stakes agents; can force triage or request an Opus retry |
Retries, timeout & circuit breaker
A run is retried up to 2 times with exponential backoff: the first retry waits 800 ms, the second 1,600 ms. Each attempt has a 120-second timeout, so an agent that hangs counts as a failed attempt and does not block the run.
The circuit breaker
Failures are counted per agent, per organization. After 5 consecutive failures the circuit opens and further calls fail at once for 5 minutes before it resets. That stops a broken integration or a model outage from burning credits in a retry loop. The breaker state lives in the agent_circuit_breakers table (with an in-memory fallback), so it is shared across processes. A successful run resets the count to zero and closes the circuit.
Model escalation
When a fast-tier (Gemini Flash) agent returns confidence below 0.72, the harness retries the run once on Opus (claude-opus-4-6) and keeps the escalated result only if confidence actually improved. If Opus does no better, the original output stands and a failed escalation is non-fatal.
allowOpusEscalation is true (Growth and Enterprise). It also never fires on a run that was already downshifted or is already using a model override.Plan-gated model downshift
Before the run even starts, the credit meter resolves the model the agent may use. If the agent's default model exceeds the plan's allowed tiers, it is downshifted to the best model the plan permits. The agent still runs, on a cheaper model.
The evaluator on high-stakes agents
Six high-stakes agents trigger a separate EvaluatorAgent after a successful run. The evaluator grades the output out of 100 and returns a suggested action.
// HIGH_STAKES_AGENTS: these trigger the evaluator after a successful run
const HIGH_STAKES_AGENTS = new Set([
"ap_specialist",
"payroll_processor",
"tax_filer",
"capex_approver",
"contract_reviewer",
"fraud_detector",
]);The evaluator can only make a run more cautious. Besides a pass, it has two verdicts:
triagesends the run to the triage inbox with the evaluator's score and the issues it found.retry_opusruns the agent again on Opus, on plans that allow Opus escalation, and uses that output.
Worked example: a low-confidence payroll run
Example · Payroll Processor on a Growth plan
A payroll run starts. The credit meter confirms credits remain and that Growth allows the premium tier, so no downshift. The agent runs and succeeds, but because payroll_processor is high-stakes, the evaluator grades the output and scores it 62/100, flagging an unusual deduction.
The evaluator returns triage. The harness overrides the run to requires_triage: true with the reason "Evaluator forced triage (score 62/100): unusual deduction", resets the circuit, and records a trust outcome. The run lands in the inbox for a person, even though the agent itself was confident.