Wall Clock Gap Thaw Policy • AI Agent SDK

WallClockGapThawPolicy: Config-driven default freeze-thaw detector.

WallClockGapThawPolicy

Defined in the protocols module.

Config-driven default freeze-thaw detector.

The default referenced by `gateway.thaw: blocks in gateway.yaml and the BotOS(..., thaw_policy=...)` Python surface. It is intentionally minimal and dependency-free so the decision lives in core and is provable in isolation; the wrapper owns the side effects (restart channel sockets, refresh presence, reconcile the scheduler).

A suspend gap is detected when, between two consecutive :meth:observe calls, the wall-clock delta ran ahead of the monotonic delta by more than `gap_threshold_s and the monotonic clock itself stayed near-frozen (advanced by no more than one tick plus a small tolerance). Both conditions are the true signature of a frozen host: wall-clock jumps forward while CLOCK_MONOTONIC stalls. The reported gap_seconds` is the wall-vs-monotonic divergence — the time the host was actually frozen.

Requiring the monotonic delta to stay near-frozen distinguishes a real host suspend from a forward wall-clock correction (NTP step / manual clock set) that occurs while the process is running normally: in the correction case monotonic keeps advancing on schedule, so no recovery is requested and healthy transports/schedule are left untouched.

The first observation only seeds the baseline and never reports a gap, so the default preserves current behaviour when no freeze occurs.

Example::

WallClockGapThawPolicy(tick_interval_s=15.0, gap_threshold_s=60.0)

Constructor

Methods

Source