monkeybot 2.1.1__py3-none-any.whl

monkeybot/gateway/realtime/session.py

@@ -0,0 +1,232 @@
+"""Per-connection realtime session state machine."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from monkeybot.core.llm.realtime_provider import (
+    AudioFormat,
+    RealtimeAudioDelta,
+    RealtimeDone,
+    RealtimeEvent,
+    RealtimeInterrupted,
+    RealtimePartialTranscript,
+    RealtimeProvider,
+    RealtimeSession,
+    RealtimeTextDelta,
+    RealtimeToolCall,
+    RealtimeTurnBoundary,
+    RealtimeUsage,
+)
+from monkeybot.core.logging_utils import kv
+from monkeybot.core.runtime.utterance_buffer import UtteranceBuffer
+
+from .metrics import RealtimeMetrics
+from .wire import audio_duration_sec
+
+logger = logging.getLogger("monkeybot.gateway.realtime.session")
+
+
+class SessionStateError(Exception):
+    """Invalid state transition or operation on a realtime session."""
+
+
+RealtimeSessionState = Literal[
+    "listening", "thinking", "speaking", "interrupted", "tool_running", "closing"
+]
+
+
+@dataclass
+class RealtimeConnectionState:
+    """Mutable state for one realtime WebSocket connection."""
+
+    session_id: str
+    request_id: str
+    provider: RealtimeProvider
+    realtime_session: RealtimeSession
+    buffer: UtteranceBuffer = field(default_factory=UtteranceBuffer)
+    state: RealtimeSessionState = "listening"
+    opened_at: float = 0.0
+    last_activity_at: float = 0.0
+    # Pending tool/subagent payloads to inject when the session reaches idle.
+    # Each item is either tool-result tuples for send_tool_results, or a context
+    # string for send_context (e.g. hook inject_text).
+    idle_delivery_queue: asyncio.Queue[Any] = field(default_factory=asyncio.Queue)
+    metrics: RealtimeMetrics = field(init=False)
+    pending_responses: dict[str, asyncio.Future[Any]] = field(default_factory=dict)
+    _closed: bool = False
+
+    def __post_init__(self) -> None:
+        self.metrics = RealtimeMetrics(
+            session_id=self.session_id,
+            request_id=self.request_id,
+            opened_at=self.opened_at,
+        )
+
+    def register_pending(self, key: str) -> asyncio.Future[Any]:
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future[Any] = loop.create_future()
+        self.pending_responses[key] = fut
+        return fut
+
+    def resolve_pending(self, key: str, payload: dict[str, Any]) -> bool:
+        fut = self.pending_responses.pop(key, None)
+        if fut is None or fut.done():
+            return False
+        fut.set_result(payload)
+        return True
+
+    def abandon_pending_timeout(self, key: str) -> None:
+        fut = self.pending_responses.pop(key, None)
+        if fut is not None and not fut.done():
+            fut.set_result({"_timeout": True})
+
+    def abandon_pending_cancel_all(self) -> None:
+        for key in list(self.pending_responses):
+            fut = self.pending_responses.pop(key, None)
+            if fut is not None and not fut.done():
+                fut.cancel()
+
+    def is_pending_or_terminal(
+        self, key: str
+    ) -> Literal["pending", "terminated", "unknown"]:
+        if key in self.pending_responses:
+            return "pending"
+        return "unknown"
+
+    def transition(self, new_state: RealtimeSessionState) -> None:
+        """Validate and apply a state transition."""
+        valid = (self.state, new_state) in _VALID_TRANSITIONS
+        if not valid:
+            raise SessionStateError(
+                f"Invalid realtime transition {self.state} -> {new_state}"
+            )
+        old = self.state
+        self.state = new_state
+        logger.debug(
+            "realtime state transition %s",
+            kv(
+                request_id=self.request_id,
+                session_id=self.session_id,
+                old=old,
+                new=new_state,
+            ),
+        )
+
+    def mark_activity(self, now: float) -> None:
+        self.last_activity_at = now
+
+    def apply_provider_event(self, event: RealtimeEvent) -> None:
+        """Update state, buffer, and metrics based on a provider event."""
+        if self.state == "closing":
+            return
+        if isinstance(event, RealtimePartialTranscript):
+            if event.is_final:
+                # Gemini Live emits input transcription as final-only, often after
+                # the client already sent audio_stream_end. Attach it to the
+                # just-finished utterance so history commit sees spoken text.
+                self.buffer.apply_final_user_transcript(event.text)
+            else:
+                self.buffer.add_user_text(event.text)
+        elif isinstance(event, (RealtimeAudioDelta, RealtimeTextDelta)):
+            if isinstance(event, RealtimeAudioDelta):
+                self.metrics.mark_model_audio_sec(
+                    audio_duration_sec(event.chunk, self.realtime_session.output_format)
+                )
+            else:
+                self.buffer.add_assistant_text(event.text)
+            self.metrics.mark_first_output()
+            if self.state in ("listening", "thinking"):
+                self.transition("speaking")
+        elif isinstance(event, RealtimeTurnBoundary):
+            if event.role == "user":
+                if self.state in ("speaking", "thinking"):
+                    # User interrupted the assistant and then finalized.
+                    self.transition("interrupted")
+                    self.transition("listening")
+                self.buffer.mark_user_turn_boundary()
+                self.metrics.start_turn()
+            else:
+                # Assistant turn boundary.
+                self.buffer.mark_assistant_turn_boundary()
+                self.metrics.end_turn()
+                # mark_assistant_turn_boundary clears the in-flight buffer; check the
+                # finalized turn for tool calls.
+                if self.buffer.current_assistant_turn().tool_calls:
+                    self.transition("tool_running")
+                    return
+                self.transition("listening")
+        elif isinstance(event, RealtimeToolCall):
+            self.buffer.add_assistant_tool_call(event)
+            self.metrics.mark_tool_in_turn()
+        elif isinstance(event, RealtimeInterrupted):
+            # Provider acknowledged interrupt.
+            if self.state in ("speaking", "thinking"):
+                self.transition("interrupted")
+        elif isinstance(event, RealtimeUsage):
+            self.metrics.mark_usage(
+                input_tokens=event.input_tokens,
+                output_tokens=event.output_tokens,
+            )
+        elif isinstance(event, RealtimeDone) and self.state in (
+            "speaking",
+            "thinking",
+            "interrupted",
+        ):
+            # Assistant turn ended naturally.
+            self.buffer.mark_assistant_turn_boundary()
+            self.metrics.end_turn()
+            self.transition("listening")
+
+    def handle_user_interrupt(self) -> None:
+        """Client or user barge-in."""
+        if self.state in ("speaking", "thinking"):
+            self.metrics.mark_interrupt()
+            self.buffer.interrupt()
+            self.transition("interrupted")
+            # The provider interrupt call is made by the gateway; here we just update state.
+        elif self.state == "tool_running":
+            # Constraint 4: do not interrupt a tool call once dispatched.
+            pass
+
+    def mark_user_audio(self, duration_sec: float) -> None:
+        """Track user audio duration and activity."""
+        self.metrics.mark_user_audio_sec(duration_sec)
+
+    def is_idle(self) -> bool:
+        return self.state == "listening" and not self.buffer.in_user_turn
+
+    def enqueue_idle_delivery(self, payload: Any) -> None:
+        """Queue a payload for injection when the session is idle."""
+        self.idle_delivery_queue.put_nowait(payload)
+
+    def close(self) -> None:
+        self._closed = True
+        self.state = "closing"
+
+
+_VALID_TRANSITIONS: set[tuple[RealtimeSessionState, RealtimeSessionState]] = {
+    ("listening", "listening"),
+    ("listening", "thinking"),
+    ("listening", "speaking"),  # model can start speaking immediately after user input
+    ("thinking", "speaking"),
+    ("thinking", "listening"),
+    ("thinking", "interrupted"),
+    ("speaking", "interrupted"),
+    ("interrupted", "listening"),
+    ("speaking", "listening"),
+    ("speaking", "tool_running"),
+    ("thinking", "tool_running"),
+    ("listening", "tool_running"),  # tool-only turns may skip speaking
+    ("tool_running", "listening"),
+    ("tool_running", "thinking"),
+    # ("tool_running", "interrupted") is explicitly disallowed.
+}
+
+
+# Any source state may transition to closing.
+for _src in ("listening", "thinking", "speaking", "interrupted", "tool_running"):
+    _VALID_TRANSITIONS.add((_src, "closing"))

monkeybot/gateway/realtime/wire.py

@@ -0,0 +1,412 @@
+"""WebSocket frame protocol for MonkeyBot realtime sessions.
+
+Frames are either binary audio chunks or JSON control messages. The gateway keeps
+client/gateway audio formats fixed per deployment; the provider may negotiate a
+different format internally, but the client contract is stable.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from monkeybot.core.llm.realtime_provider import AudioFormat
+
+
+@dataclass(frozen=True)
+class ClientConnectFrame:
+    """First message from the client; requests a realtime session for the given id."""
+
+    kind: Literal["connect"] = "connect"
+    session_id: str = ""
+
+
+@dataclass(frozen=True)
+class ClientTextFrame:
+    """Text input from the client."""
+
+    kind: Literal["text"] = "text"
+    text: str = ""
+
+
+@dataclass(frozen=True)
+class ClientInterruptFrame:
+    """Client explicitly requests to interrupt the current assistant turn."""
+
+    kind: Literal["interrupt"] = "interrupt"
+
+
+@dataclass(frozen=True)
+class ClientAudioStreamEndFrame:
+    """Client finished a push-to-talk utterance; provider should treat speech as complete."""
+
+    kind: Literal["audio_stream_end"] = "audio_stream_end"
+
+
+@dataclass(frozen=True)
+class ClientCloseFrame:
+    """Client is closing the realtime session gracefully."""
+
+    kind: Literal["close"] = "close"
+    reason: str = "client_close"
+
+
+@dataclass(frozen=True)
+class ClientToolConfirmationResponseFrame:
+    kind: Literal["tool_confirmation_response"] = "tool_confirmation_response"
+    tool_call_id: str = ""
+    approved: bool = False
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class ClientElicitationResponseFrame:
+    kind: Literal["elicitation_response"] = "elicitation_response"
+    elicitation_id: str = ""
+    user_data: Any = None
+    cancelled: bool = False
+
+
+ClientFrame = (
+    ClientConnectFrame
+    | ClientTextFrame
+    | ClientInterruptFrame
+    | ClientAudioStreamEndFrame
+    | ClientCloseFrame
+    | ClientToolConfirmationResponseFrame
+    | ClientElicitationResponseFrame
+)
+
+
+@dataclass(frozen=True)
+class ServerConnectedFrame:
+    kind: Literal["connected"] = "connected"
+    session_id: str = ""
+    input_format: str = "pcm_s16le_24khz_mono"
+    output_format: str = "pcm_s16le_24khz_mono"
+    chunk_ms: int = 200
+
+
+@dataclass(frozen=True)
+class ServerTextDeltaFrame:
+    kind: Literal["text_delta"] = "text_delta"
+    delta: str = ""
+    is_final: bool = False
+
+
+@dataclass(frozen=True)
+class ServerAudioFrame:
+    kind: Literal["audio"] = "audio"
+    chunk: bytes = b""
+
+
+@dataclass(frozen=True)
+class ServerInterruptedFrame:
+    kind: Literal["interrupted"] = "interrupted"
+
+
+@dataclass(frozen=True)
+class ServerTurnBoundaryFrame:
+    kind: Literal["turn_boundary"] = "turn_boundary"
+    role: Literal["user", "assistant"] = "user"
+
+
+@dataclass(frozen=True)
+class ServerToolCallFrame:
+    kind: Literal["tool_call"] = "tool_call"
+    call_id: str = ""
+    name: str = ""
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ServerToolResultFrame:
+    kind: Literal["tool_result"] = "tool_result"
+    call_id: str = ""
+    name: str = ""
+    result: str = ""
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class ServerUserTranscriptFrame:
+    kind: Literal["user_transcript"] = "user_transcript"
+    text: str = ""
+    is_final: bool = True
+
+
+@dataclass(frozen=True)
+class ServerUsageFrame:
+    kind: Literal["usage"] = "usage"
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ServerToolConfirmationFrame:
+    kind: Literal["tool_confirmation"] = "tool_confirmation"
+    tool_call_id: str = ""
+    tool_name: str = ""
+    prompt: str = ""
+    arguments: dict[str, Any] = field(default_factory=dict)
+    timeout_sec: float | None = None
+
+
+@dataclass(frozen=True)
+class ServerElicitationFrame:
+    kind: Literal["elicitation"] = "elicitation"
+    elicitation_id: str = ""
+    prompt: str = ""
+    schema: dict[str, Any] | None = None
+    timeout_sec: float | None = None
+
+
+@dataclass(frozen=True)
+class ServerErrorFrame:
+    kind: Literal["error"] = "error"
+    error: str = ""
+
+
+@dataclass(frozen=True)
+class ServerSessionEndedFrame:
+    kind: Literal["session_ended"] = "session_ended"
+    reason: str = "session_end"
+
+
+ServerFrame = (
+    ServerConnectedFrame
+    | ServerTextDeltaFrame
+    | ServerAudioFrame
+    | ServerInterruptedFrame
+    | ServerTurnBoundaryFrame
+    | ServerToolCallFrame
+    | ServerToolResultFrame
+    | ServerUserTranscriptFrame
+    | ServerUsageFrame
+    | ServerToolConfirmationFrame
+    | ServerElicitationFrame
+    | ServerErrorFrame
+    | ServerSessionEndedFrame
+)
+
+
+def _frame_size_for(fmt: AudioFormat) -> int:
+    bytes_per_sample = 2 if fmt.encoding.startswith("pcm_s") else 1
+    samples = int(fmt.sample_rate_hz * fmt.frame_ms / 1000)
+    return samples * bytes_per_sample * fmt.channels
+
+
+def audio_duration_sec(chunk: bytes, fmt: AudioFormat) -> float:
+    """Duration in seconds for a PCM (or similar) audio chunk."""
+    bytes_per_sample = 2 if fmt.encoding.startswith("pcm_s") else 1
+    frame_size = bytes_per_sample * fmt.channels
+    if frame_size == 0:
+        return 0.0
+    samples = len(chunk) // frame_size
+    return samples / fmt.sample_rate_hz
+
+
+def parse_client_frame(data: str | bytes) -> ClientFrame:
+    """Parse a client JSON control frame."""
+    if isinstance(data, bytes):
+        raise ProtocolError("Binary frames are audio chunks and must be handled before parsing")
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"Invalid JSON frame: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ProtocolError("Client frame must be a JSON object")
+    kind = str(payload.get("kind") or payload.get("type") or "")
+    if kind == "connect":
+        return ClientConnectFrame(session_id=str(payload.get("session_id", "")))
+    if kind == "text":
+        return ClientTextFrame(text=str(payload.get("text", "")))
+    if kind == "interrupt":
+        return ClientInterruptFrame()
+    if kind == "audio_stream_end":
+        return ClientAudioStreamEndFrame()
+    if kind == "close":
+        return ClientCloseFrame(reason=str(payload.get("reason", "client_close")))
+    if kind == "tool_confirmation_response":
+        return ClientToolConfirmationResponseFrame(
+            tool_call_id=str(payload.get("tool_call_id", "")),
+            approved=bool(payload.get("approved", False)),
+            reason=str(payload.get("reason", "")),
+        )
+    if kind == "elicitation_response":
+        return ClientElicitationResponseFrame(
+            elicitation_id=str(payload.get("elicitation_id", "")),
+            user_data=payload.get("user_data"),
+            cancelled=bool(payload.get("cancelled", False)),
+        )
+    raise ProtocolError(f"Unknown client frame kind: {kind!r}")
+
+
+def parse_server_frame(data: str) -> ServerFrame:
+    """Parse a server JSON control frame."""
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"Invalid JSON frame: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ProtocolError("Server frame must be a JSON object")
+    kind = str(payload.get("kind") or payload.get("type") or "")
+    if kind == "connected":
+        return ServerConnectedFrame(
+            session_id=str(payload.get("session_id", "")),
+            input_format=str(payload.get("input_format", "pcm_s16le_24khz_mono")),
+            output_format=str(payload.get("output_format", "pcm_s16le_24khz_mono")),
+            chunk_ms=int(payload.get("chunk_ms", 200)),
+        )
+    if kind == "text_delta":
+        return ServerTextDeltaFrame(
+            delta=str(payload.get("delta", "")),
+            is_final=bool(payload.get("is_final", False)),
+        )
+    if kind == "interrupted":
+        return ServerInterruptedFrame()
+    if kind == "turn_boundary":
+        role = str(payload.get("role", "user"))
+        return ServerTurnBoundaryFrame(role=role)  # type: ignore[arg-type]
+    if kind == "tool_call":
+        return ServerToolCallFrame(
+            call_id=str(payload.get("call_id", "")),
+            name=str(payload.get("name", "")),
+            args=dict(payload.get("args") or {}),
+        )
+    if kind == "tool_result":
+        err = payload.get("error")
+        return ServerToolResultFrame(
+            call_id=str(payload.get("call_id", "")),
+            name=str(payload.get("name") or payload.get("tool") or ""),
+            result=str(payload.get("result", "")),
+            error=None if err is None else str(err),
+        )
+    if kind == "user_transcript":
+        return ServerUserTranscriptFrame(
+            text=str(payload.get("text", "")),
+            is_final=bool(payload.get("is_final", True)),
+        )
+    if kind == "usage":
+        usage = payload.get("usage")
+        return ServerUsageFrame(usage=dict(usage) if isinstance(usage, dict) else dict(payload))
+    if kind == "tool_confirmation":
+        args = payload.get("arguments") or payload.get("args") or {}
+        timeout = payload.get("timeout_sec")
+        return ServerToolConfirmationFrame(
+            tool_call_id=str(payload.get("tool_call_id", "")),
+            tool_name=str(payload.get("tool_name") or payload.get("tool") or ""),
+            prompt=str(payload.get("prompt") or payload.get("message") or ""),
+            arguments=dict(args) if isinstance(args, dict) else {},
+            timeout_sec=float(timeout) if timeout is not None else None,
+        )
+    if kind == "elicitation":
+        schema = payload.get("schema") or payload.get("requestedSchema")
+        timeout = payload.get("timeout_sec")
+        return ServerElicitationFrame(
+            elicitation_id=str(payload.get("elicitation_id", "")),
+            prompt=str(payload.get("prompt") or payload.get("message") or ""),
+            schema=dict(schema) if isinstance(schema, dict) else None,
+            timeout_sec=float(timeout) if timeout is not None else None,
+        )
+    if kind == "error":
+        return ServerErrorFrame(error=str(payload.get("error", "")))
+    if kind == "session_ended":
+        return ServerSessionEndedFrame(reason=str(payload.get("reason", "session_end")))
+    raise ProtocolError(f"Unknown server frame kind: {kind!r}")
+
+
+def encode_server_frame(frame: ServerFrame) -> str | bytes:
+    """Encode a server frame to JSON text or binary audio."""
+    if isinstance(frame, ServerAudioFrame):
+        return frame.chunk
+    payload: dict[str, Any] = {"kind": frame.kind}
+    if isinstance(frame, ServerConnectedFrame):
+        payload.update(
+            {
+                "session_id": frame.session_id,
+                "input_format": frame.input_format,
+                "output_format": frame.output_format,
+                "chunk_ms": frame.chunk_ms,
+            }
+        )
+    elif isinstance(frame, ServerTextDeltaFrame):
+        payload.update({"delta": frame.delta, "is_final": frame.is_final})
+    elif isinstance(frame, ServerTurnBoundaryFrame):
+        payload["role"] = frame.role
+    elif isinstance(frame, ServerToolCallFrame):
+        payload.update(
+            {"call_id": frame.call_id, "name": frame.name, "args": frame.args or {}}
+        )
+    elif isinstance(frame, ServerToolResultFrame):
+        payload.update(
+            {
+                "call_id": frame.call_id,
+                "name": frame.name,
+                "result": frame.result,
+                "error": frame.error,
+            }
+        )
+    elif isinstance(frame, ServerUserTranscriptFrame):
+        payload.update({"text": frame.text, "is_final": frame.is_final})
+    elif isinstance(frame, ServerUsageFrame):
+        payload["usage"] = frame.usage
+    elif isinstance(frame, ServerToolConfirmationFrame):
+        payload.update(
+            {
+                "tool_call_id": frame.tool_call_id,
+                "tool_name": frame.tool_name,
+                "prompt": frame.prompt,
+                "arguments": frame.arguments,
+                "timeout_sec": frame.timeout_sec,
+            }
+        )
+    elif isinstance(frame, ServerElicitationFrame):
+        payload.update(
+            {
+                "elicitation_id": frame.elicitation_id,
+                "prompt": frame.prompt,
+                "schema": frame.schema,
+                "timeout_sec": frame.timeout_sec,
+            }
+        )
+    elif isinstance(frame, ServerErrorFrame):
+        payload["error"] = frame.error
+    elif isinstance(frame, ServerSessionEndedFrame):
+        payload["reason"] = frame.reason
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+class ProtocolError(Exception):
+    """Malformed realtime frame."""
+
+
+__all__ = [
+    "ClientAudioStreamEndFrame",
+    "ClientCloseFrame",
+    "ClientConnectFrame",
+    "ClientElicitationResponseFrame",
+    "ClientFrame",
+    "ClientInterruptFrame",
+    "ClientTextFrame",
+    "ClientToolConfirmationResponseFrame",
+    "ProtocolError",
+    "ServerAudioFrame",
+    "ServerConnectedFrame",
+    "ServerElicitationFrame",
+    "ServerErrorFrame",
+    "ServerFrame",
+    "ServerInterruptedFrame",
+    "ServerSessionEndedFrame",
+    "ServerTextDeltaFrame",
+    "ServerToolCallFrame",
+    "ServerToolConfirmationFrame",
+    "ServerToolResultFrame",
+    "ServerTurnBoundaryFrame",
+    "ServerUsageFrame",
+    "ServerUserTranscriptFrame",
+    "audio_duration_sec",
+    "encode_server_frame",
+    "parse_client_frame",
+    "parse_server_frame",
+]

monkeybot/gateway/realtime_main.py

@@ -0,0 +1,49 @@
+"""Gateway server entrypoint for the realtime WebSocket harness.
+
+Run locally with:
+
+    python -m monkeybot.gateway.realtime_main
+
+This serves both the existing SSE routes and the realtime WebSocket endpoint at
+``WS /sessions/{session_id}/realtime``. The existing SSE-only entrypoint remains at
+:mod:`monkeybot.gateway.main`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from monkeybot.core.logging_utils import normalize_log_level
+from monkeybot.gateway.bootstrap import ensure_gateway_runtime_env
+
+ensure_gateway_runtime_env()
+
+logging.basicConfig(
+    level=normalize_log_level(os.getenv("LOG_LEVEL")),
+    format="%(levelname)s:%(name)s:%(message)s",
+)
+# Suppress chatty third-party loggers regardless of LOG_LEVEL.
+for _noisy in ("httpx", "httpcore", "urllib3", "google_genai", "google.auth"):
+    logging.getLogger(_noisy).setLevel(logging.WARNING)
+
+from monkeybot.gateway.realtime.app import app  # noqa: E402
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    port = int(os.getenv("PORT", os.getenv("GATEWAY_PORT", "8000")))
+    log_level = os.getenv("LOG_LEVEL", "info").lower()
+    timeout_graceful_shutdown = int(os.getenv("GRACEFUL_SHUTDOWN_TIMEOUT_SEC", "5"))
+
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=port,
+        log_level=log_level,
+        access_log=True,
+        timeout_graceful_shutdown=timeout_graceful_shutdown,
+    )

monkeybot/gateway/sse/__init__.py

@@ -0,0 +1 @@
+"""SSE gateway: session event bus, framing, and HTTP routes (v2 API)."""