monkeybot 2.1.1__py3-none-any.whl

monkeybot/core/workspace/s3.py

@@ -0,0 +1,151 @@
+"""Amazon S3 :class:`WorkspaceStorage` (``boto3``)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from botocore.exceptions import ClientError
+
+from monkeybot.core.workspace.protocol import WorkspaceStorage
+
+_log = logging.getLogger(__name__)
+
+
+class S3WorkspaceStorage:
+    """Object-prefix layout: ``s3://bucket/{prefix}/{path}``."""
+
+    def __init__(self, bucket: str, prefix: str = "") -> None:
+        import boto3
+
+        self._s3 = boto3.client("s3")
+        self._bucket = bucket
+        self._prefix = prefix.strip().strip("/").replace("\\", "/")
+        if self._prefix:
+            self._prefix = self._prefix + "/"
+
+    def _key(self, path: str) -> str:
+        key = path.strip().replace("\\", "/").lstrip("/")
+        return self._prefix + key if self._prefix else key
+
+    async def read_text(self, path: str) -> str:
+        key = self._key(path)
+
+        def _read() -> str:
+            resp = self._s3.get_object(Bucket=self._bucket, Key=key)
+            body: bytes = resp["Body"].read()
+            return body.decode("utf-8")
+
+        try:
+            return await asyncio.to_thread(_read)
+        except ClientError as exc:
+            code = exc.response.get("Error", {}).get("Code", "")
+            if code in ("404", "NoSuchKey", "NotFound"):
+                raise FileNotFoundError(key) from exc
+            raise
+
+    async def write_text(self, path: str, content: str) -> None:
+        key = self._key(path)
+
+        def _write() -> None:
+            self._s3.put_object(
+                Bucket=self._bucket,
+                Key=key,
+                Body=content.encode("utf-8"),
+                ContentType="text/plain; charset=utf-8",
+            )
+
+        await asyncio.to_thread(_write)
+
+    async def append_text(self, path: str, content: str) -> None:
+        key = self._key(path)
+
+        def _append() -> None:
+            try:
+                resp = self._s3.get_object(Bucket=self._bucket, Key=key)
+                cur = resp["Body"].read().decode("utf-8")
+            except ClientError as exc:
+                code = exc.response.get("Error", {}).get("Code", "")
+                if code not in ("404", "NoSuchKey", "NotFound"):
+                    raise
+                cur = ""
+            self._s3.put_object(
+                Bucket=self._bucket,
+                Key=key,
+                Body=(cur + content).encode("utf-8"),
+                ContentType="text/plain; charset=utf-8",
+            )
+
+        await asyncio.to_thread(_append)
+
+    async def exists(self, path: str) -> bool:
+        key = self._key(path)
+
+        def _head() -> bool:
+            try:
+                self._s3.head_object(Bucket=self._bucket, Key=key)
+                return True
+            except ClientError as exc:
+                code = exc.response.get("Error", {}).get("Code", "")
+                if code in ("404", "NoSuchKey", "NotFound"):
+                    return False
+                raise
+
+        return await asyncio.to_thread(_head)
+
+    async def list_files(self, prefix: str = "") -> list[str]:
+        pfx = self._key(prefix)
+
+        def _list() -> list[str]:
+            out: list[str] = []
+            paginator = self._s3.get_paginator("list_objects_v2")
+            for page in paginator.paginate(Bucket=self._bucket, Prefix=pfx):
+                for obj in page.get("Contents", []):
+                    name = obj["Key"]
+                    if name.endswith("/"):
+                        continue
+                    rel = name[len(self._prefix) :] if self._prefix else name
+                    out.append(rel.lstrip("/"))
+            return sorted(out)
+
+        return await asyncio.to_thread(_list)
+
+    async def delete(self, path: str) -> None:
+        key = self._key(path)
+
+        def _del() -> None:
+            self._s3.delete_object(Bucket=self._bucket, Key=key)
+
+        try:
+            await asyncio.to_thread(_del)
+        except ClientError as exc:
+            code = exc.response.get("Error", {}).get("Code", "")
+            if code not in ("404", "NoSuchKey", "NotFound"):
+                raise
+
+    async def move(self, src: str, dest: str) -> None:
+        sk = self._key(src)
+        dk = self._key(dest)
+
+        def _copy_delete() -> None:
+            self._s3.copy_object(
+                Bucket=self._bucket,
+                CopySource={"Bucket": self._bucket, "Key": sk},
+                Key=dk,
+            )
+            try:
+                self._s3.delete_object(Bucket=self._bucket, Key=sk)
+            except Exception as exc:
+                _log.warning("s3 move: delete source failed after copy src=%s dest=%s: %r", sk, dk, exc)
+
+        await asyncio.to_thread(_copy_delete)
+
+    async def gc_prefix(self, prefix: str, max_age_sec: float) -> dict[str, int]:
+        del prefix, max_age_sec
+        _log.info(
+            "s3 gc_prefix: skipped — configure S3 lifecycle rules on the bucket for prefix cleanup"
+        )
+        return {"scanned": 0, "deleted": 0, "errors": 0}
+
+
+__all__ = ["S3WorkspaceStorage"]

monkeybot/core/workspace_layout.py

@@ -0,0 +1,27 @@
+"""Agent-facing workspace root resolution (shared by gateway and library entry points)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def resolve_agent_workspace_root() -> Path:
+    """Directory the agent should treat as its workspace (``data/``, ``skills/``, spill, …).
+
+    Resolution order:
+
+    1. ``MONKEYBOT_WORKSPACE_ROOT`` — absolute path, or relative to process cwd.
+    2. ``WORKSPACE_ROOT`` — same semantics (alias for serverless / legacy handlers).
+    3. Else if ``<cwd>/workspace`` exists and is a directory, use it.
+    4. Else process cwd.
+    """
+    for env_name in ("MONKEYBOT_WORKSPACE_ROOT", "WORKSPACE_ROOT"):
+        raw = os.environ.get(env_name, "").strip()
+        if raw:
+            p = Path(raw)
+            return p.resolve() if p.is_absolute() else (Path.cwd() / p).resolve()
+    nested = (Path.cwd() / "workspace").resolve()
+    if nested.is_dir():
+        return nested
+    return Path.cwd().resolve()

monkeybot/gateway/__init__.py

@@ -0,0 +1 @@
+"""Gateway — FastAPI SSE interface (v2)."""

monkeybot/gateway/bootstrap.py

@@ -0,0 +1,18 @@
+"""Process-level bootstrap before the FastAPI app is constructed."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def ensure_gateway_runtime_env() -> None:
+    """Load ``.env`` then optional ``monkeybot_config/monkeybot.yaml`` (see ``monkeybot.core.config.runtime_env``)."""
+    load_dotenv()
+    if not os.environ.get("MONKEYBOT_AGENT_ROOT", "").strip():
+        os.environ["MONKEYBOT_AGENT_ROOT"] = str(Path.cwd().resolve())
+    from monkeybot.core.config.runtime_env import apply_monkeybot_runtime_env
+
+    apply_monkeybot_runtime_env()

monkeybot/gateway/main.py

@@ -0,0 +1,47 @@
+"""
+Gateway server entrypoint (SSE harness).
+
+Run locally with:
+
+    python -m 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.sse.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/realtime/__init__.py

@@ -0,0 +1,31 @@
+"""Realtime WebSocket gateway for MonkeyBot."""
+
+from __future__ import annotations
+
+from monkeybot.gateway.realtime.app import create_realtime_app
+from monkeybot.gateway.realtime.deps import RealtimeDependencies
+from monkeybot.gateway.realtime.errors import RealtimeError
+from monkeybot.gateway.realtime.guardrails import run_guardrails
+from monkeybot.gateway.realtime.manager import RealtimeSessionManager
+from monkeybot.gateway.realtime.metrics import RealtimeMetrics
+from monkeybot.gateway.realtime.routes import create_realtime_router
+from monkeybot.gateway.realtime.session import RealtimeConnectionState
+from monkeybot.gateway.realtime.wire import (
+    ServerConnectedFrame,
+    encode_server_frame,
+    parse_client_frame,
+)
+
+__all__ = [
+    "RealtimeConnectionState",
+    "RealtimeDependencies",
+    "RealtimeError",
+    "RealtimeMetrics",
+    "RealtimeSessionManager",
+    "ServerConnectedFrame",
+    "create_realtime_app",
+    "create_realtime_router",
+    "encode_server_frame",
+    "parse_client_frame",
+    "run_guardrails",
+]

monkeybot/gateway/realtime/app.py

@@ -0,0 +1,321 @@
+"""FastAPI application factory for the realtime gateway.
+
+This creates a new FastAPI app that mounts the SSE gateway routes **plus** the realtime
+WebSocket endpoint. The existing ``gateway/sse/app.py`` is left untouched.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from monkeybot.core.attachments.config import attachments_enabled_from_env
+from monkeybot.core.attachments.store import FilesystemAttachmentStore
+from monkeybot.core.config.realtime_config import RealtimeConfig, get_realtime_config
+from monkeybot.core.config.settings import (
+    auto_schema_enabled_from_config,
+    get_subagent_registry,
+    normalize_model_provider,
+    vertex_google_search_enabled_from_config,
+)
+from monkeybot.core.hooks import HookManager
+from monkeybot.core.llm.provider import Provider
+from monkeybot.core.mcp.mcp_client import MCPClient
+from monkeybot.core.memory.subsystem import MemorySubsystem
+from monkeybot.core.persistence.backends import create_storage_backend
+from monkeybot.core.tools.inspector import CommandTierInspector, RulesInspector
+from monkeybot.core.tools.permission import try_load_permission_inspector
+from monkeybot.core.workspace import create_workspace_storage
+from monkeybot.gateway.bootstrap import ensure_gateway_runtime_env
+from monkeybot.gateway.sse.routes import create_app as build_sse_app
+from monkeybot.gateway.sse.workspace_layout import resolve_agent_workspace_root
+from monkeybot.providers.gemini_live import GeminiLiveProvider
+from monkeybot.web_search import WebSearchTool, build_backend
+
+from .deps import RealtimeDependencies
+from .manager import RealtimeSessionManager
+from .routes import create_realtime_router
+
+logger = logging.getLogger(__name__)
+
+
+def _memory_enabled() -> bool:
+    raw = os.environ.get("MONKEYBOT_MEMORY_HOOK_ENABLED", "true").strip().lower()
+    return raw not in {"0", "false", "no", "off"}
+
+
+def _memory_storage_uri() -> str:
+    uri = os.environ.get("MEMORY_STORAGE_URI", "").strip()
+    if uri:
+        return uri
+    raw_mp = os.environ.get("MEMORY_PATH")
+    if raw_mp is not None:
+        logger.info(
+            "memory: deriving storage URI from MEMORY_PATH; prefer paths.memory_storage_uri in monkeybot.yaml"
+        )
+    legacy = (raw_mp or "data/memory").strip()
+    mem = Path(legacy)
+    resolved = mem.resolve() if mem.is_absolute() else (Path.cwd().resolve() / mem).resolve()
+    return f"local://{resolved}"
+
+
+def _tool_denied_patterns() -> list[str]:
+    raw = os.environ.get("MONKEYBOT_TOOL_DENIED_PATTERNS")
+    if raw is None:
+        return ["rm -rf", "/etc/passwd", "DROP TABLE"]
+    return [p.strip() for p in raw.split(",") if p.strip()]
+
+
+def _resolve_provider() -> Provider:
+    from monkeybot.core.config.settings import get_provider_config
+    from monkeybot.core.testing.mocks_provider import ScriptedFakeProvider
+
+    mode = normalize_model_provider(os.environ.get("MODEL_PROVIDER", "google_vertexai"))
+    if mode == "fake":
+        return ScriptedFakeProvider([])
+    return get_provider_config(provider=mode).provider
+
+
+@contextlib.asynccontextmanager
+async def _realtime_lifespan(
+    app: FastAPI,
+    deps: RealtimeDependencies,
+    config: RealtimeConfig,
+) -> AsyncIterator[None]:
+    """Wire storage, MCP, inspectors, memory, and realtime provider."""
+    db_url = os.environ.get("DB_URL", "sqlite:///data/monkeybot.db")
+    backend = create_storage_backend(db_url)
+    await backend.open(run_schema=auto_schema_enabled_from_config())
+    app.state.storage = backend
+    deps.storage = backend
+
+    mcp = MCPClient()
+    deps.mcp = mcp
+    mcp_config = Path(os.environ.get("MCP_CONFIG", "/app/monkeybot_config/mcp.json"))
+    strict = os.environ.get("MCP_STRICT_LOAD", "").strip().lower() in ("1", "true", "yes")
+    try:
+        await mcp.load_from_config(mcp_config, raise_on_error=strict)
+    except OSError as exc:
+        logger.info("MCP config skipped (%s): %s", mcp_config, exc)
+
+    tiers_path = Path(
+        os.environ.get("COMMAND_ALLOWLIST_CONFIG", "/app/monkeybot_config/command_allowlist.yaml")
+    )
+    deps.run_command_allowed_commands = None
+    deps.run_command_allowed_path_prefixes = None
+    inspectors: list[Any] = []
+    try:
+        tier_insp = CommandTierInspector(tiers_path)
+        inspectors.append(tier_insp)
+        deps.run_command_allowed_commands = list(tier_insp.allowed_commands)
+        deps.run_command_allowed_path_prefixes = list(tier_insp.allowed_path_prefixes)
+    except FileNotFoundError:
+        logger.info("command tiers missing (%s); allowing all tool calls", tiers_path)
+    except Exception as exc:
+        logger.exception("command tier load failed: %s", exc)
+
+    denied = _tool_denied_patterns()
+    if denied:
+        inspectors.append(RulesInspector(denied))
+
+    perm_path = Path(
+        os.environ.get("PERMISSION_CONFIG", "/app/monkeybot_config/permissions.yaml")
+    )
+    perm_insp = try_load_permission_inspector(perm_path)
+    if perm_insp is not None:
+        inspectors.append(perm_insp)
+
+    deps.inspectors = inspectors
+
+    # Realtime model can be a Live-only preview while the main turn-based model
+    # stays a regular generateContent model. Use realtime.model.provider if set,
+    # otherwise fall back to the main provider.
+    realtime_provider = normalize_model_provider(
+        config.model.provider or os.environ.get("MODEL_PROVIDER", "google_vertexai")
+    )
+    if realtime_provider == "google_genai":
+        api_key = os.environ.get("GEMINI_API_KEY", "")
+        if not api_key:
+            logger.warning("realtime MODEL_PROVIDER=google_genai but GEMINI_API_KEY is not set")
+        deps.realtime_provider = GeminiLiveProvider(api_key=api_key)
+    else:
+        deps.realtime_provider = GeminiLiveProvider()
+
+    provider = _resolve_provider()
+    vertex_gs = vertex_google_search_enabled_from_config()
+    try:
+        backend_ws = build_backend()
+        if backend_ws is not None:
+            deps.web_search_tool = WebSearchTool(backend_ws)
+            logger.info("web search enabled: backend=%s", backend_ws.name)
+        else:
+            deps.web_search_tool = None
+    except Exception as exc:
+        logger.warning("web search backend init failed — disabling: %s", exc)
+        deps.web_search_tool = None
+
+    if vertex_gs:
+        logger.info("vertex google_search grounding enabled")
+    if deps.web_search_tool is None and not vertex_gs:
+        logger.info("web search disabled (WEB_SEARCH_BACKEND=none)")
+
+    if _memory_enabled():
+        try:
+            mem_uri = _memory_storage_uri()
+            storage = create_workspace_storage(mem_uri)
+            model_name = os.environ.get("MODEL_NAME", "gemini-2.5-flash")
+            memory = MemorySubsystem(
+                storage=storage,
+                provider=provider,
+                model=model_name,
+                memory_uri=mem_uri,
+            )
+            mgr = HookManager()
+            memory.register_hooks(mgr)
+            deps.hook_manager = mgr
+            deps.memory = memory
+            app.state.memory = memory
+            logger.info("memory hook enabled (memory_storage_uri=%s)", mem_uri)
+        except Exception as exc:
+            logger.warning("memory hook init failed — disabling: %s", exc)
+    else:
+        logger.info("memory hook disabled")
+
+    deps.subagent_registry = get_subagent_registry()
+
+    if attachments_enabled_from_env():
+        try:
+            deps.attachment_store = FilesystemAttachmentStore(resolve_agent_workspace_root())
+            app.state.attachment_store = deps.attachment_store
+            logger.info("attachments enabled")
+        except Exception as exc:
+            logger.warning("attachment store init failed: %s", exc)
+            deps.attachment_store = None
+            app.state.attachment_store = None
+    else:
+        deps.attachment_store = None
+        app.state.attachment_store = None
+        logger.info("attachments disabled via ATTACHMENTS_ENABLED")
+
+    deps.freeze()
+
+    try:
+        yield
+    finally:
+        if deps.mcp is not None:
+            for name in list(getattr(deps.mcp, "_servers", {}).keys()):
+                try:
+                    await deps.mcp.disconnect(name)
+                except Exception:
+                    logger.exception("MCP disconnect failed for %s", name)
+        if deps.storage is not None:
+            await deps.storage.close()
+
+
+@contextlib.asynccontextmanager
+async def _combined_lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """SSE startup (turn-based /reply) plus realtime Live provider wiring.
+
+    Chat and talk share this process. SSE ``GatewayLoopPort`` reads module-level
+    ``_deps`` from ``gateway.sse.app``, so we must run SSE ``_startup`` here —
+    not only the realtime-only lifespan (which left /reply with a no-op loop).
+    """
+    from monkeybot.gateway.sse.app import _deps as sse_deps
+    from monkeybot.gateway.sse.app import _shutdown as sse_shutdown
+    from monkeybot.gateway.sse.app import _startup as sse_startup
+
+    deps: RealtimeDependencies = app.state.realtime_deps
+    config: RealtimeConfig = app.state.realtime_config
+
+    await sse_startup(app)
+
+    # Bridge shared process deps into RealtimeDependencies (no second DB open).
+    deps.storage = app.state.storage
+    deps.mcp = sse_deps.mcp
+    deps.inspectors = list(sse_deps.inspectors)
+    deps.memory = sse_deps.memory
+    deps.hook_manager = sse_deps.hook_manager
+    deps.web_search_tool = sse_deps.web_search_tool
+    deps.run_command_allowed_commands = sse_deps.run_command_allowed_commands
+    deps.run_command_allowed_path_prefixes = sse_deps.run_command_allowed_path_prefixes
+    deps.subagent_registry = sse_deps.subagent_registry
+    deps.attachment_store = getattr(app.state, "attachment_store", None)
+
+    realtime_provider = normalize_model_provider(
+        config.model.provider or os.environ.get("MODEL_PROVIDER", "google_vertexai")
+    )
+    if realtime_provider == "google_genai":
+        api_key = os.environ.get("GEMINI_API_KEY", "")
+        if not api_key:
+            logger.warning("realtime MODEL_PROVIDER=google_genai but GEMINI_API_KEY is not set")
+        deps.realtime_provider = GeminiLiveProvider(api_key=api_key)
+    else:
+        deps.realtime_provider = GeminiLiveProvider()
+
+    deps.freeze()
+
+    try:
+        yield
+    finally:
+        await sse_shutdown(app)
+
+
+def create_realtime_app(**kwargs: Any) -> FastAPI:
+    """Build a FastAPI app serving both SSE routes and the realtime WebSocket endpoint.
+
+    Extra keyword arguments are forwarded to the underlying SSE app factory.
+    """
+    ensure_gateway_runtime_env()
+
+    config = get_realtime_config()
+    manager = RealtimeSessionManager(config)
+    deps = RealtimeDependencies()
+
+    # Wire the real turn-based loop (same as gateway.sse.app). Without this,
+    # build_sse_app installs a no-op default that clears busy and emits nothing —
+    # which leaves the chat TUI stuck on "thinking…".
+    from monkeybot.gateway.sse.app import GatewayLoopPort, _StaticUsagePortZeros
+    from monkeybot.gateway.sse.session_bus import SessionRegistry
+
+    registry = kwargs.pop("registry", None) or SessionRegistry()
+    loop_port = kwargs.pop("loop_port", None) or GatewayLoopPort(registry)
+    usage_port = kwargs.pop("usage_port", None) or _StaticUsagePortZeros()
+
+    app = build_sse_app(
+        lifespan=_combined_lifespan,
+        registry=registry,
+        loop_port=loop_port,
+        usage_port=usage_port,
+        **kwargs,
+    )
+    if isinstance(loop_port, GatewayLoopPort):
+        loop_port.bind_app(app)
+
+    app.state.realtime_config = config
+    app.state.realtime_deps = deps
+    app.state.realtime_manager = manager
+
+    if not any(isinstance(m, CORSMiddleware) for m in app.user_middleware):
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    router = create_realtime_router(deps, manager)
+    app.include_router(router)
+
+    return app
+
+
+# Module-level app for ``uvicorn monkeybot.gateway.realtime.app:app``.
+app = create_realtime_app()

monkeybot/gateway/realtime/deps.py

@@ -0,0 +1,52 @@
+"""Process-level dependencies for the realtime gateway.
+
+This mirrors the SSE gateway's ``_GatewayDeps`` but is owned by the realtime package so
+that the realtime app can be wired independently without modifying ``gateway/sse/app.py``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from monkeybot.core.attachments.store import AttachmentStore
+from monkeybot.core.config.settings import SubagentConfig
+from monkeybot.core.hooks import HookManager
+from monkeybot.core.llm.realtime_provider import RealtimeProvider
+from monkeybot.core.mcp.ports_mcp import MCPClientPort
+from monkeybot.core.memory.subsystem import MemorySubsystem
+from monkeybot.core.persistence.backends import StorageBackend
+from monkeybot.core.tools.inspector import ToolInspector
+
+
+@dataclass
+class RealtimeDependencies:
+    """Mutable process singleton populated on realtime app startup.
+
+    Call :meth:`freeze` after lifespan setup so accidental post-startup mutation fails
+    loudly (single-process assumption; multi-replica still needs sticky WS routing).
+    """
+
+    mcp: MCPClientPort | None = None
+    inspectors: list[ToolInspector] = field(default_factory=list)
+    memory: MemorySubsystem | None = None
+    hook_manager: HookManager | None = None
+    web_search_tool: Any | None = None
+    run_command_allowed_commands: list[str] | None = None
+    run_command_allowed_path_prefixes: list[str] | None = None
+    subagent_registry: dict[str, SubagentConfig] = field(default_factory=dict)
+    realtime_provider: RealtimeProvider | None = None
+    storage: StorageBackend | None = None
+    attachment_store: AttachmentStore | None = None
+    _frozen: bool = field(default=False, repr=False)
+
+    def freeze(self) -> None:
+        """Lock dependency fields after startup wiring completes."""
+        object.__setattr__(self, "_frozen", True)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name != "_frozen" and getattr(self, "_frozen", False):
+            raise RuntimeError(
+                f"RealtimeDependencies is frozen; cannot set {name!r} after startup"
+            )
+        object.__setattr__(self, name, value)