Wrap every tool call with timeouts, circuit breakers, audit logging, and crash loop protection. Enforcement the agent cannot bypass.

Supervision Layer

Stop trusting agents to police themselves. Supervision Layer wraps every tool call in timeouts, circuit breakers, and audit logs — enforcement the agent cannot bypass.

Before vs After

Without SupervisionWith Supervision
Runaway callsAgent loops infinitely on a failing APICircuit breaker trips after 3 failures
Stuck sessionsTool hangs silently, agent waits foreverTimeout kills it after 30s
Audit trailNo record of what happenedEvery call logged with timestamp, outcome, cost
Crash loopsSubagent restarts infinitelyAfter 3 crashes, marked permanently failed

Quick Start

python
from supervision import get_supervisor

supervisor = get_supervisor()
result = await supervisor.execute(
    tool="web_fetch",
    fn=fetch_fn,
    agent_id="worker-1",
    session_id="sess-abc",
)

Components

  1. TimeoutWrapper — Per-tool configurable timeouts (default 30s)
  2. CircuitBreaker — 3-state machine (CLOSED → OPEN → HALF_OPEN)
  3. AuditLogger — Structured JSONL logging, 50MB rotation, queryable
  4. CrashLoopProtector — Track restarts, mark failed after 3 within window
  5. SupervisedCall — All-in-one: crash check → circuit check → audit → timeout → audit

Testing

bash
cd scripts/ && python -m pytest test_supervision.py -v

58 tests. 0 external dependencies. Works with any async Python project.

License

MIT