Probe the session's high-level status
Return the unified :class:SessionStatus for a session.
Ownership validation, cluster-liveness probing, and parked-state
derivation are all delegated to
:meth:SessionService.get_session_status — see that method for
the precedence rules that collapse the two orthogonal signals
(message-bus run lock + persisted context tail) into a single
four-valued enum.
Args:
session_id (str):
The session to probe.
agent_id (str):
The agent that owns the session (ownership validation).
user_id (str):
Injected authenticated user ID.
session_service (SessionService):
Injected session service. Owns both storage and message
bus dependencies so the composed answer is derived in a
single layer.
Returns:
SessionStatusResponse:
The probed session id and its unified status.
Raises:
HTTPException: 404 if the session does not exist or does not
belong to the authenticated user.
Headers
Caller's user ID. Temporary header-based identity; will be replaced by JWT auth.
Path Parameters
Query Parameters
Agent the session belongs to.
Response
Successful Response
Response body for probing a session's high-level status.
See :class:~agentscope.app._service.SessionStatus for the
semantics of each status value and the precedence rules used
to derive it.
The session that was probed.
The session's unified status. One of running (some worker holds the run lease), idle (no worker, context clean), awaiting_permission (no worker, context parked on HITL tool call), or awaiting_external_result (no worker, context parked on external executor).
running, idle, awaiting_permission, awaiting_external_result