Restart Loop Guard • AI Agent SDK

RestartLoopGuard: Pure rolling-window predicate that trips on a rapid restart loop.

RestartLoopGuard

Defined in the protocols module.

Pure rolling-window predicate that trips on a rapid restart loop.

A companion to :func:classify_exit_reason for the crash-loop breaker referenced in Issue #3021. Where `classify_exit_reason` maps a single exit to a supervisor exit code, this tracks the rate of restart-worthy boots so a process that keeps crashing-on-resume can stop auto-resuming the offending work rather than wedging in a tight restart loop.

It is intentionally side-effect free (records timestamps only, no I/O, no heavy deps) so both gateway runtimes (`BotOS and WebSocketGateway`) can reuse the same decision and prove it in isolation. The caller feeds a monotonic timestamp each time a restart-interrupted boot is observed and asks whether the breaker has tripped.

A trip means: at least `max_restarts restarts occurred within the last window_seconds`. When tripped, the caller should stop auto-resuming the offending session (while still serving real inbound) instead of restarting it again immediately.

Example::

guard = RestartLoopGuard(max_restarts=3, window_seconds=60)
if guard.record(now=time.monotonic()):
    # too many restarts too fast — stop auto-resuming this session
    ...

Constructor

Methods

Source