Gateway Abort and Per-Turn Timeout

Cancel a running agent turn or drain a whole session (turn + queued backlog) from the gateway with /stop, /stop all, /cancel, an abort WebSocket frame, or a per-turn timeout

Stop a hung or runaway gateway turn cooperatively using /stop, an abort WebSocket frame, or a configurable per-turn timeout — or stop the whole session (the running turn and everything queued behind it) with /stop all, /cancel, or abort carrying scope: "session".

from praisonaiagents import Agent

agent = Agent(name="gateway-agent", instructions="Answer questions.")

The gateway relays a message_abort event to clients when a turn is cancelled, so a custom client can render the turn as “cancelled” instead of hanging or leaking a raw traceback.

graph LR
    S1[/stop / stop] --> H[Session Handler]
    S2[/stop all / /cancel] --> H
    W1[abort scope=turn] --> H
    W2[abort scope=session] --> H
    T[per_turn_timeout] --> H
    H -->|TURN| IC[Per-turn<br/>InterruptController]
    H -->|SESSION| IC
    H -->|SESSION| Q[Drain session inbox<br/>+ bump stop_epoch]
    IC --> A[Agent turn]
    Q --> C[pending_cancelled: N]
    A --> Fin[turn_aborted: true]
    Fin --> F[message_abort frame]
    C --> R[reply payload]
    F --> R

    classDef in fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef proc fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef cfg fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef out fill:#10B981,stroke:#7C90A0,color:#fff

    class S1,S2,W1,W2,T in
    class H,IC,A,Q proc
    class Fin,F,C,R out

Pick the scope that matches what you want stopped — the running answer only, or that answer plus everything you queued behind it.

graph TB
    Q{What do you want to stop?} --> A[Just the running answer]
    Q --> B[Everything I typed — the running answer AND my queued follow-ups]
    A --> A1[/stop  ·  stop  ·  abort frame default]
    B --> B1[/stop all  ·  /cancel  ·  abort frame with scope=session]

    classDef q fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef turn fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef session fill:#F59E0B,stroke:#7C90A0,color:#fff

    class Q q
    class A,A1 turn
    class B,B1 session

Quick Start

1. Cancel from any chat client with /stop

   Any chat client can cancel the in-flight turn by sending /stop (or bare stop, case-insensitive). Reply is either {"type":"aborted","session_id":"..."} or {"type":"no_active_turn","session_id":"..."}.

   {"type": "message", "content": "/stop"}

2. Cancel the whole session with /stop all or /cancel

   When the user typed several follow-ups and wants everything they queued cancelled too, a session-scoped stop cancels the in-flight turn and drains the session inbox.

   {"type": "message", "content": "/stop all"}

   Reply carries the drained count:

   {
     "type": "aborted",
     "session_id": "sess-1",
     "scope": "session",
     "turn_aborted": true,
     "pending_cancelled": 2
   }

   /cancel is an alias for /stop all.

3. Session-scope the abort WebSocket frame

   The same abort frame drains the backlog when you add scope: "session":

   {"type": "abort", "reason": "user", "scope": "session"}

   scope is optional; absent or unknown falls back to TURN.

4. Cancel with an abort WebSocket frame

   Send an abort frame — requires the write operator scope (same as sending a message as the agent):

   {"type": "abort", "reason": "user"}

   reason is optional (defaults to "user") and is echoed back in the terminal turn message.

5. Set a per-turn wall-clock ceiling

   Set a wall-clock ceiling per turn in the gateway config. 0 (default) disables the timeout — behaviour is byte-identical to earlier releases.

   gateway:
     per_turn_timeout: 60.0   # cancel any turn that runs longer than 60s

   A timed-out turn’s terminal response is "Turn cancelled: exceeded per-turn timeout.".

6. Render the message_abort event on the client

   When the gateway cancels a turn it emits a message_abort event; treat it as a terminal outcome for that turn.

   from praisonaiagents.gateway.protocols import EventType
   
   if event["type"] == EventType.MESSAGE_ABORT.value:  # "message_abort"
       mark_turn_cancelled(event)

Config: gateway.per_turn_timeout

Wall-clock ceiling for a single agent turn. When exceeded, the turn is cancelled cooperatively (via its InterruptController) and, if it does not unwind within a bounded grace window, the driving task is cancelled hard.

Three ways to set it:

from praisonaiagents.gateway.config import GatewayConfig

config = GatewayConfig(per_turn_timeout=60.0)

# multi-channel gateway config
gateway:
  per_turn_timeout: 60.0

# via the bot pydantic schema — same key
from praisonai_bot.bots._config_schema import GatewayServerSchema

GatewayServerSchema(per_turn_timeout=60.0)

Stop Scopes

Two scopes. TURN stops the current answer. SESSION stops the current answer and drains everything the user queued behind it.

Both StopScope and StopResult are exported from the public gateway surface:

from praisonaiagents.gateway import StopScope, StopResult

StopResult.to_dict() serialises to exactly {"scope": ..., "turn_aborted": ..., "pending_cancelled": ...}. pending_cancelled is the count of queued messages a SESSION stop drained — a visible, intentional non-outcome, never a silent drop — and is always 0 for a TURN stop.

Frame shapes

Client → Gateway

Abort frame — requires the write operator scope:

{"type": "abort", "reason": "user", "scope": "session"}

message_abort is accepted as an alias for type.

Portable stop command — any client already joined to a session can cancel via the message channel:

{"type": "message", "content": "/stop all"}

Matching is case-insensitive and whitespace-trimmed.

Gateway → Client (reply to abort)

The reply carries the StopResult fields alongside type and session_id.

type is "aborted" when either turn_aborted is true or pending_cancelled > 0; otherwise "no_active_turn". A SESSION stop with no active turn but 3 queued messages still replies "aborted" with pending_cancelled: 3 — the queued work counts as work stopped.

Turn-scoped reply:

{
  "type": "aborted",
  "session_id": "sess-1",
  "scope": "turn",
  "turn_aborted": true,
  "pending_cancelled": 0
}

Session-scoped reply:

{
  "type": "aborted",
  "session_id": "sess-1",
  "scope": "session",
  "turn_aborted": true,
  "pending_cancelled": 3
}

Terminal turn message

The turn’s own response (delivered on the normal message channel) is a typed string:

The message_abort event

EventType.MESSAGE_ABORT is defined in praisonaiagents/gateway/protocols.py and serialises to the wire string "message_abort".

How It Works

Every turn runs through a per-turn InterruptController, so a /stop, an abort frame, or a timeout on one session never touches another session’s turn.

Common Patterns

Real scenarios this page lets you pattern-match to:

Related