​

TurnExecutorProtocol

Defined in the protocols module.

AI Agent Contract for where a session’s agent turn executes (Issue #4011). The gateway calls :meth:place to obtain a :class:TurnPlacement for a session, then :meth:execute_turn to run the turn on that placement, and :meth:teardown to reclaim a placement’s worker. The default :class:InProcessTurnExecutor runs the turn on the current event loop, reproducing today’s behaviour exactly; an isolated executor (subprocess / container / remote, in the wrapper) runs it on its own worker so a wedged, runaway, or crashed turn is contained to its session. Contract:

• :meth:place returns the placement that owns session_id’s turns. Implementations may cache a placement per session and bump its epoch when the backing worker is replaced.
• :meth:execute_turn runs turn (an async no-arg callable the gateway already built for this turn) on placement and returns its result. The in-process default awaits turn directly on the current loop. An isolated executor does not ship this live callable (and its captured loop/agent state) across a process boundary — the worker owns the session (via :meth:place) and rebuilds/dispatches the turn from serialisable inputs on its own side; turn then acts as the gateway-side await point for that worker’s result. cancel_token carries the per-turn interrupt so the existing cancellation seam is preserved. limits optionally bounds the worker’s CPU/memory/wall time (honoured by isolated executors; ignored in-process). It raises :class:WorkerWedgedError if the placement’s worker can no longer make progress.
• :meth:teardown reclaims placement’s worker (kills the subprocess/container/remote worker, or is a no-op in-process), scoped to the owning session only.

A worker fault must fail scoped: tear down the offending placement and re-place its session, never the whole gateway — mirroring the fail-safe, blast-radius-contained defaults elsewhere.

​

Methods

​

Source