monkeybot 2.1.1__py3-none-any.whl

monkeybot/gateway/realtime/errors.py

@@ -0,0 +1,81 @@
+"""Realtime error taxonomy.
+
+Every error in the realtime loop is either (a) surfaced to the client as a typed
+``RealtimeError`` event and the session is closed, or (b) logged and treated as
+non-fatal (e.g. a malformed client frame). Close/send failures must be logged, never
+silently discarded.
+"""
+
+from __future__ import annotations
+
+
+class RealtimeError(Exception):
+    """Base class for all realtime gateway errors."""
+
+    client_visible: bool = True
+    close_code: int = 1011
+    log_level: str = "error"
+
+    def __init__(self, message: str, *, details: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+
+class ProviderConnectionError(RealtimeError):
+    """Failed to establish the provider realtime session."""
+
+    close_code = 1011
+
+
+class ProviderStreamError(RealtimeError):
+    """The provider stream failed mid-session."""
+
+    close_code = 1011
+
+
+class ClientProtocolError(RealtimeError):
+    """Malformed or unexpected client frame."""
+
+    close_code = 1008
+    log_level = "warning"
+
+
+class AudioFormatError(RealtimeError):
+    """Client and gateway audio formats do not match."""
+
+    close_code = 1008
+
+
+class SubagentDispatchError(RealtimeError):
+    """A subagent/task dispatch failed. Non-fatal; surfaced to the client but session continues."""
+
+    client_visible = True
+    close_code = 0  # do not close the WebSocket
+    log_level = "warning"
+
+
+class GatewayInternalError(RealtimeError):
+    """Unexpected gateway internal error."""
+
+    close_code = 1011
+
+
+class GuardrailError(RealtimeError):
+    """Session closed due to a guardrail trigger (idle, max duration, etc.)."""
+
+    close_code = 1001
+
+
+class ConcurrencyLimitError(RealtimeError):
+    """Realtime concurrency limit reached; upgrade rejected."""
+
+    close_code = 1013  # Try Again Later
+    log_level = "warning"
+
+
+class SessionConflictError(RealtimeError):
+    """A live WebSocket already exists for this session_id."""
+
+    close_code = 1008
+    log_level = "warning"

monkeybot/gateway/realtime/guardrails.py

@@ -0,0 +1,88 @@
+"""Realtime session guardrails: max duration, idle timeout, max response turn.
+
+Guardrails are enforced by a background task that runs alongside the main session loop.
+They are non-blocking and only raise a :class:`GuardrailError` when a threshold is
+crossed. The session loop then closes the session gracefully. The WebSocket ping/pong
+keepalive is handled by the underlying Starlette/FastAPI implementation; this module only
+encloses the application-level idle timer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from monkeybot.core.config.realtime_config import RealtimeConfig
+from monkeybot.core.logging_utils import kv
+
+from .errors import GuardrailError
+from .session import RealtimeConnectionState
+
+logger = logging.getLogger("monkeybot.gateway.realtime.guardrails")
+
+
+async def run_guardrails(
+    state: RealtimeConnectionState,
+    config: RealtimeConfig,
+    *,
+    poll_interval_sec: float = 5.0,
+) -> None:
+    """Background task enforcing session duration, idle timeout, and response-turn limits.
+
+    Raises :class:`GuardrailError` with the guardrail reason when a limit is hit. The
+    caller is responsible for canceling this task after the error is raised.
+    """
+    max_duration = config.session.max_duration_sec
+    idle_timeout = config.session.idle_timeout_sec
+    max_response_turn = config.session.max_response_turn_sec
+
+    while True:
+        await asyncio.sleep(poll_interval_sec)
+        if state._closed or state.state == "closing":
+            return
+
+        now = time.monotonic()
+
+        # Max duration hard cap
+        if now - state.opened_at >= max_duration:
+            logger.info(
+                "realtime guardrail triggered: max_duration %s",
+                kv(session_id=state.session_id, max_duration_sec=max_duration),
+            )
+            raise GuardrailError(
+                f"Session exceeded max_duration_sec={max_duration}",
+                details="max_duration_exceeded",
+            )
+
+        # Idle timeout: no client or provider activity.
+        if now - state.last_activity_at >= idle_timeout:
+            logger.info(
+                "realtime guardrail triggered: idle_timeout %s",
+                kv(
+                    session_id=state.session_id,
+                    idle_timeout_sec=idle_timeout,
+                    idle_sec=round(now - state.last_activity_at, 1),
+                ),
+            )
+            raise GuardrailError(
+                f"No activity for idle_timeout_sec={idle_timeout}",
+                details="idle_timeout",
+            )
+
+        # Max response turn: one model turn cannot exceed the limit.
+        if state.state in ("thinking", "speaking", "tool_running"):
+            turn_start = state.metrics.current_turn_started_at if state.metrics else None
+            if turn_start is not None and now - turn_start >= max_response_turn:
+                logger.info(
+                    "realtime guardrail triggered: max_response_turn %s",
+                    kv(
+                        session_id=state.session_id,
+                        max_response_turn_sec=max_response_turn,
+                        turn_sec=round(now - turn_start, 1),
+                    ),
+                )
+                raise GuardrailError(
+                    f"Model turn exceeded max_response_turn_sec={max_response_turn}",
+                    details="max_response_turn_exceeded",
+                )

monkeybot/gateway/realtime/manager.py

@@ -0,0 +1,77 @@
+"""Realtime session registry and concurrency guardrails."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from monkeybot.core.config.realtime_config import RealtimeConfig
+from monkeybot.core.logging_utils import kv
+
+from .session import RealtimeConnectionState
+
+logger = logging.getLogger("monkeybot.gateway.realtime.manager")
+
+
+@dataclass
+class RealtimeSessionManager:
+    """In-process manager for realtime sessions.
+
+    Mirrors the existing SSE ``SessionRegistry`` pattern: one instance per process.
+    Multi-instance deployments require sticky routing or an external pub/sub (out of
+    scope for v1, per the realtime design doc).
+    """
+
+    config: RealtimeConfig
+    _sessions: dict[str, RealtimeConnectionState] = field(default_factory=dict)
+    _sem: asyncio.Semaphore = field(init=False)
+
+    def __post_init__(self) -> None:
+        self._sem = asyncio.Semaphore(self.config.session.max_concurrent_sessions)
+
+    async def acquire_slot(self, session_id: str) -> bool:
+        """Acquire a concurrency slot. Returns True if granted, False if at limit."""
+        if self._sem.locked():
+            logger.warning(
+                "realtime concurrency limit reached %s",
+                kv(
+                    session_id=session_id,
+                    max_concurrent=self.config.session.max_concurrent_sessions,
+                ),
+            )
+            return False
+        await self._sem.acquire()
+        return True
+
+    def release_slot(self, session_id: str) -> None:
+        self._sem.release()
+        logger.debug(
+            "realtime concurrency slot released %s",
+            kv(session_id=session_id),
+        )
+
+    def register(self, session_id: str, state: RealtimeConnectionState) -> None:
+        """Register a live connection. Raises if ``session_id`` is already active."""
+        if session_id in self._sessions:
+            raise ValueError(f"Realtime session already active: {session_id}")
+        self._sessions[session_id] = state
+
+    def get(self, session_id: str) -> RealtimeConnectionState | None:
+        return self._sessions.get(session_id)
+
+    def remove(self, session_id: str, state: RealtimeConnectionState | None = None) -> None:
+        """Remove a session. When ``state`` is given, only remove that exact connection."""
+        current = self._sessions.get(session_id)
+        if current is None:
+            return
+        if state is not None and current is not state:
+            return
+        self._sessions.pop(session_id, None)
+
+    def snapshot_metrics(self) -> dict[str, Any]:
+        return {
+            "active_sessions": len(self._sessions),
+            "max_concurrent_sessions": self.config.session.max_concurrent_sessions,
+        }

monkeybot/gateway/realtime/metrics.py

@@ -0,0 +1,144 @@
+"""Realtime session and turn metrics."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from monkeybot.core.logging_utils import kv
+
+logger = logging.getLogger("monkeybot.gateway.realtime.metrics")
+
+
+@dataclass
+class RealtimeMetrics:
+    """Accumulated metrics for one realtime session."""
+
+    session_id: str
+    request_id: str
+    opened_at: float = field(default_factory=time.monotonic)
+    closed_at: float | None = None
+    close_reason: str = "unknown"
+    user_audio_sec: float = 0.0
+    model_audio_sec: float = 0.0
+    interrupt_count: int = 0
+    turn_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    last_prompt_tokens: int = 0
+    turn_latencies_ms: list[float] = field(default_factory=list)
+    turn_model_durations_ms: list[float] = field(default_factory=list)
+    turn_tool_counts: list[int] = field(default_factory=list)
+    _current_turn_started_at: float | None = None
+    _current_turn_first_output_at: float | None = None
+    _current_turn_tool_count: int = 0
+
+    def mark_user_audio_sec(self, duration: float) -> None:
+        self.user_audio_sec += duration
+
+    def mark_model_audio_sec(self, duration: float) -> None:
+        self.model_audio_sec += duration
+
+    def mark_interrupt(self) -> None:
+        self.interrupt_count += 1
+
+    def mark_usage(self, *, input_tokens: int = 0, output_tokens: int = 0) -> None:
+        """Accumulate session totals; keep last turn's prompt size for the context meter."""
+        inp = max(0, input_tokens)
+        out = max(0, output_tokens)
+        self.input_tokens += inp
+        self.output_tokens += out
+        # Provider usage events report per-turn (or current-context) prompt size.
+        # The CLI context ring must use that latest value, not the session sum.
+        self.last_prompt_tokens = inp
+
+    def to_usage_payload(self, *, context_window_tokens: int = 200_000) -> dict[str, Any]:
+        """Shape compatible with ``GET /sessions/{id}/usage`` / ``parse_usage_response``.
+
+        ``input_tokens`` / ``output_tokens`` are session cumulatives.
+        ``last_prompt_tokens`` / ``estimated_prompt_tokens`` are the most recent
+        provider-reported prompt size (realtime has no separate preflight count).
+        """
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cost_usd": 0.0,
+            "last_prompt_tokens": self.last_prompt_tokens,
+            "estimated_prompt_tokens": self.last_prompt_tokens,
+            "context_window_tokens": context_window_tokens,
+            "summarization_threshold_tokens": max(1, int(context_window_tokens * 0.85)),
+        }
+
+    def start_turn(self, now: float | None = None) -> None:
+        """Call when a user turn boundary is finalized (model is about to respond)."""
+        self._current_turn_started_at = now or time.monotonic()
+        self._current_turn_first_output_at = None
+        self._current_turn_tool_count = 0
+
+    def mark_first_output(self, now: float | None = None) -> None:
+        """Call when the first assistant output delta arrives."""
+        if self._current_turn_started_at is None:
+            return
+        now = now or time.monotonic()
+        self._current_turn_first_output_at = now
+        self.turn_latencies_ms.append(
+            round((now - self._current_turn_started_at) * 1000, 2)
+        )
+
+    def mark_tool_in_turn(self) -> None:
+        self._current_turn_tool_count += 1
+
+    def end_turn(self, now: float | None = None) -> None:
+        """Call when the assistant turn boundary is finalized."""
+        self.turn_count += 1
+        self.turn_tool_counts.append(self._current_turn_tool_count)
+        if self._current_turn_first_output_at is not None:
+            now = now or time.monotonic()
+            self.turn_model_durations_ms.append(
+                round((now - self._current_turn_first_output_at) * 1000, 2)
+            )
+        self._current_turn_started_at = None
+        self._current_turn_first_output_at = None
+        self._current_turn_tool_count = 0
+
+    @property
+    def current_turn_started_at(self) -> float | None:
+        return self._current_turn_started_at
+
+    def close(self, reason: str, now: float | None = None) -> None:
+        self.close_reason = reason
+        self.closed_at = now or time.monotonic()
+
+    def as_dict(self) -> dict[str, Any]:
+        duration = 0.0
+        if self.closed_at is not None:
+            duration = round(self.closed_at - self.opened_at, 3)
+        return {
+            "event": "realtime_session_summary",
+            "session_id": self.session_id,
+            "request_id": self.request_id,
+            "realtime_session_duration_sec": duration,
+            "realtime_session_user_audio_sec": round(self.user_audio_sec, 3),
+            "realtime_session_model_audio_sec": round(self.model_audio_sec, 3),
+            "realtime_session_interrupt_count": self.interrupt_count,
+            "realtime_session_turn_count": self.turn_count,
+            "realtime_session_input_tokens": self.input_tokens,
+            "realtime_session_output_tokens": self.output_tokens,
+            "realtime_session_close_reason": self.close_reason,
+            "realtime_turn_latency_ms_avg": round(sum(self.turn_latencies_ms) / len(self.turn_latencies_ms), 2)
+            if self.turn_latencies_ms
+            else 0.0,
+            "realtime_turn_model_duration_ms_avg": round(
+                sum(self.turn_model_durations_ms) / len(self.turn_model_durations_ms), 2
+            )
+            if self.turn_model_durations_ms
+            else 0.0,
+            "realtime_turn_tool_count_total": sum(self.turn_tool_counts),
+        }
+
+    def emit_summary(self) -> None:
+        if self.closed_at is None:
+            self.close("unknown")
+        logger.info("realtime session summary %s", kv(**self.as_dict()))