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 SupervisionRunaway callsAgent loops infinitely on a failing APICircuit breaker trips after 3 failuresStuck sessionsTool hangs silently, agent waits foreverTimeout kills it after 30sAudit trailNo record of what happenedEvery call logged with timestamp, outcome, costCrash 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