Supervision Layer

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

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 Supervision	With Supervision
Runaway calls	Agent loops infinitely on a failing API	Circuit breaker trips after 3 failures
Stuck sessions	Tool hangs silently, agent waits forever	Timeout kills it after 30s
Audit trail	No record of what happened	Every call logged with timestamp, outcome, cost
Crash loops	Subagent restarts infinitely	After 3 crashes, marked permanently failed

Quick Start

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

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

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

License

MIT