topos-node 0.1.7__tar.gz → 0.1.9__tar.gz

{topos_node-0.1.7 → topos_node-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 0.1.7
+Version: 0.1.9
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai

{topos_node-0.1.7 → topos_node-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "0.1.7"
+version = "0.1.9"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"

{topos_node-0.1.7 → topos_node-0.1.9}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "0.1.7"
-__version_info__ = (0, 1, 7)
+__version__ = "0.1.9"
+__version_info__ = (0, 1, 9)
 
 __all__ = ["__version__", "__version_info__"]

{topos_node-0.1.7 → topos_node-0.1.9}/topos/api/device.py

@@ -12,12 +12,12 @@ router = APIRouter()
 
 @router.get("/device/info", response_model=DeviceInfoResponse, dependencies=[Depends(require_api_key)])
 async def get_device_info(services: Services = Depends(get_services)):
-    return await services.device.get_device_info()
+    return await services.device.get_device_info(context=None)
 
 
 @router.get("/device_info", response_model=DeviceInfoResponse, dependencies=[Depends(require_api_key)])
 async def get_device_info_alias(services: Services = Depends(get_services)):
-    return await services.device.get_device_info()
+    return await services.device.get_device_info(context=None)
 
 
 @router.post("/device_name", response_model=DeviceNameResponse, dependencies=[Depends(require_api_key)])

{topos_node-0.1.7 → topos_node-0.1.9}/topos/api/source_install.py

@@ -145,6 +145,21 @@ async def _list_sources_core(payload: Dict[str, Any]) -> Dict[str, Any]:
     return {"status": "ok", "sources": sources}
 
 
+async def _patch_source_install_core(payload: Dict[str, Any]) -> Dict[str, Any]:
+    source_id = str(payload.get("source_id") or "").strip()
+    if not source_id:
+        raise ValueError("source_id is required")
+    partial = payload.get("source_definition_json")
+    if not isinstance(partial, dict):
+        raise ValueError("source_definition_json object is required")
+    record = install_service.patch_source_install(
+        source_id=source_id,
+        scope=_scope_from_payload(payload),
+        source_definition_json=partial,
+    )
+    return {"status": "ok", "install": record.to_dict()}
+
+
 async def _uninstall_source_core(payload: Dict[str, Any]) -> Dict[str, Any]:
     source_id = str(payload.get("source_id") or "").strip()
     if not source_id:
@@ -266,6 +281,21 @@ async def source_install_status(
     return _ok_envelope(request_id, result)
 
 
+@router.patch("/source-install", dependencies=[Depends(require_api_key)])
+async def patch_source_install(payload: Dict[str, Any] = Body(default_factory=dict)) -> Dict[str, Any]:
+    request_id = str(uuid.uuid4())
+    _log_request("patch_source_install", request_id, payload)
+    try:
+        result = await _patch_source_install_core(payload)
+        return _ok_envelope(request_id, result)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
 @router.delete("/source-install", dependencies=[Depends(require_api_key)])
 async def uninstall_source(payload: Dict[str, Any] = Body(default_factory=dict)) -> Dict[str, Any]:
     request_id = str(uuid.uuid4())

{topos_node-0.1.7 → topos_node-0.1.9}/topos/app.py

@@ -46,6 +46,11 @@ from .control_plane_client import ControlPlaneClient
 from .engine.registration import build_engine_heartbeat_message, build_engine_register_message
 from .hosted_pool_lease import HostedPoolLeaseClient
 from .services.container import get_services
+from .runtime_update import (
+    start_runtime_update_monitor,
+    start_update_hotkey_listener,
+    stop_runtime_update_monitor,
+)
 from .startup_banner import emit_startup_banner
 from .sync import SyncClient
 from .sync_handlers import handle_sync_op
@@ -206,6 +211,9 @@ async def startup_event() -> None:
                     await state.control_plane_client.send_message(build_engine_heartbeat_message())
 
         state.engine_presence_task = asyncio.create_task(_presence_loop())
+    start_runtime_update_monitor()
+    start_update_hotkey_listener()
+
     if settings.enable_sync and settings.topos_user_id:
         state.sync_client = SyncClient(
             sync_url=settings.get_sync_url(),
@@ -229,6 +237,7 @@ async def startup_event() -> None:
 
 @app.on_event("shutdown")
 async def shutdown_event() -> None:
+    await stop_runtime_update_monitor()
     if state.engine_presence_task:
         state.engine_presence_task.cancel()
         try:

{topos_node-0.1.7 → topos_node-0.1.9}/topos/cli/commands.py

@@ -2,28 +2,42 @@
 
 from __future__ import annotations
 
-import json
 import os
-import subprocess
 import sys
-from importlib.metadata import PackageNotFoundError, version as package_version
 from pathlib import Path
-from urllib.error import URLError
-from urllib.request import urlopen
 
 import click
 import uvicorn
-from packaging.version import InvalidVersion, Version
 
 # Add parent directory to path for imports
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
+from topos.runtime_update import (
+    DEFAULT_PACKAGE_NAME,
+    apply_package_update,
+    can_prompt_for_input,
+    check_for_update,
+    get_installed_package_version,
+    get_latest_pypi_version,
+    get_module_version,
+    should_skip_update_check,
+)
 from topos.storage.db.paths import discover_databases
 from topos.startup_banner import emit_startup_banner
 
 USER_ENV_PATH = Path.home() / ".topos" / ".env"
 LEGACY_ENV_PATH = Path(__file__).resolve().parent.parent / ".env"
 
+# Re-exported for tests that monkeypatch commands.*
+_get_installed_package_version = get_installed_package_version
+_get_latest_pypi_version = get_latest_pypi_version
+_get_module_version = get_module_version
+_can_prompt_for_input = can_prompt_for_input
+
+
+def _get_runtime_version(package_name: str = DEFAULT_PACKAGE_NAME) -> str:
+    return _get_module_version() or _get_installed_package_version(package_name) or "unknown"
+
 
 def _load_env_file(env_path: Path) -> None:
     if not env_path.exists():
@@ -69,10 +83,6 @@ def _save_topos_key(topos_key: str, env_path: Path = USER_ENV_PATH) -> Path:
     return env_path
 
 
-def _can_prompt_for_input() -> bool:
-    return sys.stdin.isatty() and sys.stdout.isatty()
-
-
 def _prompt_for_topos_key() -> str:
     click.echo("TOPOS_KEY is required to connect Topos Node.")
     click.echo("Enter your TOPOS_KEY to save it locally and continue.")
@@ -107,26 +117,7 @@ def _resolve_topos_key(cli_topos_key: str | None, env_path: Path = USER_ENV_PATH
     )
 
 
-def _get_installed_package_version(package_name: str) -> str | None:
-    try:
-        return package_version(package_name)
-    except PackageNotFoundError:
-        return None
-
-
-def _get_module_version() -> str | None:
-    try:
-        from topos.__version__ import __version__
-    except Exception:
-        return None
-    return __version__ or None
-
-
-def _get_runtime_version(package_name: str = "topos-node") -> str:
-    return _get_module_version() or _get_installed_package_version(package_name) or "unknown"
-
-
-def _emit_startup_banner(host: str, port: int, package_name: str = "topos-node") -> None:
+def _emit_startup_banner(host: str, port: int, package_name: str = DEFAULT_PACKAGE_NAME) -> None:
     runtime_version = _get_runtime_version(package_name=package_name)
     emit_startup_banner(
         click.echo,
@@ -138,45 +129,18 @@ def _emit_startup_banner(host: str, port: int, package_name: str = "topos-node")
     os.environ["TOPOS_STARTUP_BANNER_EMITTED"] = "1"
 
 
-def _get_latest_pypi_version(package_name: str, timeout_seconds: float = 2.0) -> str | None:
-    url = f"https://pypi.org/pypi/{package_name}/json"
-    try:
-        with urlopen(url, timeout=timeout_seconds) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-    except (OSError, URLError, ValueError):
-        return None
-    return str(payload.get("info", {}).get("version") or "").strip() or None
-
-
-def _should_skip_update_check(skip_update_check: bool) -> bool:
-    if skip_update_check:
-        return True
-    env_value = (os.getenv("TOPOS_SKIP_UPDATE_CHECK") or "").strip().lower()
-    return env_value in {"1", "true", "yes", "on"}
-
-
 def _maybe_offer_self_update(
     skip_update_check: bool,
-    package_name: str = "topos-node",
+    package_name: str = DEFAULT_PACKAGE_NAME,
 ) -> bool:
-    if _should_skip_update_check(skip_update_check):
+    if should_skip_update_check(cli_skip=skip_update_check):
         return False
 
-    installed = _get_installed_package_version(package_name)
-    if not installed:
+    info = check_for_update(package_name)
+    if not info:
         return False
 
-    latest = _get_latest_pypi_version(package_name)
-    if not latest:
-        return False
-
-    try:
-        if Version(latest) <= Version(installed):
-            return False
-    except InvalidVersion:
-        return False
-
-    click.echo(f"Update available for {package_name}: {installed} -> {latest}")
+    click.echo(f"Update available for {package_name}: {info.installed} -> {info.latest}")
     if not _can_prompt_for_input():
         click.echo(f"Run `uv tool upgrade {package_name}` to update.")
         return False
@@ -185,8 +149,7 @@ def _maybe_offer_self_update(
         return False
 
     click.echo(f"Updating {package_name}...")
-    result = subprocess.run(["uv", "tool", "upgrade", package_name], check=False)
-    if result.returncode != 0:
+    if not apply_package_update(package_name):
         click.echo("Update failed. Continuing with current version.")
         return False
 
@@ -246,6 +209,9 @@ def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_ch
             click.echo("No existing databases found")
         return
 
+    if skip_update_check:
+        os.environ["TOPOS_SKIP_UPDATE_CHECK"] = "1"
+
     if _maybe_offer_self_update(skip_update_check=skip_update_check):
         return
 

{topos_node-0.1.7 → topos_node-0.1.9}/topos/core/handlers.py

@@ -1139,6 +1139,15 @@ async def handle_control_plane_request(message: Dict[str, Any]) -> Optional[Dict
     _payload = message.get("payload") or {}
     _mcp_source = _payload.get("mcp_source")
     _mcp_requester_id = _payload.get("mcp_requester_id")
+    if msg_type == "migrate_browser_plugin_app_id":
+        from .state import _migrate_legacy_browser_plugin_app_ids
+
+        conn = get_db_connection()
+        if not conn:
+            return {"id": req_id, "status": "error", "error": "Database not available"}
+        updated = _migrate_legacy_browser_plugin_app_ids(conn)
+        return {"id": req_id, "status": "ok", "payload": {"updated_rows": updated}}
+
     if msg_type == "get_request_counts":
         """Return UMA + MCP request counts from engine DB (for CP proxy or direct frontend)."""
         payload = message.get("payload") or {}
@@ -1305,6 +1314,20 @@ async def handle_control_plane_request(message: Dict[str, Any]) -> Optional[Dict
         except Exception as exc:  # noqa: BLE001
             return {"id": req_id, "status": "error", "error": str(exc)}
 
+    if msg_type == "patch_source_install":
+        from ..api.source_install import _patch_source_install_core
+
+        payload = message.get("payload") if isinstance(message.get("payload"), dict) else {}
+        try:
+            result = await _patch_source_install_core(payload)
+            return {"id": req_id, "status": "ok", "payload": result}
+        except ValueError as exc:
+            return {"id": req_id, "status": "error", "error": str(exc)}
+        except RuntimeError as exc:
+            return {"id": req_id, "status": "error", "error": str(exc)}
+        except Exception as exc:  # noqa: BLE001
+            return {"id": req_id, "status": "error", "error": str(exc)}
+
     if msg_type == "post_source_test_ingestion":
         from ..api.source_install import _test_ingestion_core
 
@@ -1759,8 +1782,10 @@ async def handle_control_plane_request(message: Dict[str, Any]) -> Optional[Dict
         except Exception as exc:  # noqa: BLE001
             return {"id": req_id, "status": "error", "error": str(exc)}
     if msg_type == "get_device_info":
+        payload = message.get("payload") or {}
+        context = payload if isinstance(payload, dict) else {}
         try:
-            result = await get_services().device.get_device_info()
+            result = await get_services().device.get_device_info(context=context)
             return {"id": req_id, "status": "ok", "payload": result.model_dump()}
         except Exception as exc:  # noqa: BLE001
             return {"id": req_id, "status": "error", "error": str(exc)}

{topos_node-0.1.7 → topos_node-0.1.9}/topos/core/logging.py

@@ -5,6 +5,7 @@ from datetime import datetime
 from time import time
 
 from ..config.settings import settings
+from ..runtime_update import is_update_available
 
 _LOG_FORMAT: str | None = None
 
@@ -96,8 +97,9 @@ class ColorFormatter(logging.Formatter):
         logging.CRITICAL: "\x1b[38;5;196m", # Red
     }
     
-    # Timestamp color: Forest green
+    # Timestamp color: Forest green (amber when a newer Topos release is on PyPI)
     _TIMESTAMP_COLOR = "\x1b[38;5;28m"  # Forest green
+    _TIMESTAMP_UPDATE_COLOR = "\x1b[38;5;214m"  # Amber
     
     # Separator color: Light gray
     _SEPARATOR_COLOR = "\x1b[38;5;244m"  # Light gray
@@ -119,7 +121,10 @@ class ColorFormatter(logging.Formatter):
     def format(self, record: logging.LogRecord) -> str:  # noqa: D401
         # Format timestamp: YYYY-MM-DD HH:MM:SS.ms (green)
         timestamp_str = datetime.fromtimestamp(record.created).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
-        timestamp = f"{self._TIMESTAMP_COLOR}{timestamp_str}{self._RESET}"
+        timestamp_color = (
+            self._TIMESTAMP_UPDATE_COLOR if is_update_available() else self._TIMESTAMP_COLOR
+        )
+        timestamp = f"{timestamp_color}{timestamp_str}{self._RESET}"
         
         # Get text color for log level (no background)
         level_color = self._LEVEL_COLORS.get(record.levelno, "")

{topos_node-0.1.7 → topos_node-0.1.9}/topos/core/state.py

@@ -14,6 +14,8 @@ from typing import Any, Dict, Optional
 
 MCP_REQUEST_LOG_TABLE = "mcp_request_log"
 UMA_ACCESS_REQUESTS_TABLE = "uma_access_requests"
+LEGACY_BROWSER_PLUGIN_APP_ID = "browser-plugin"
+BROWSER_HISTORY_PLUGIN_APP_ID = "browser-history-plugin"
 
 
 def derive_uma_access_context(owner_user_id: str, requesting_user_id: Optional[str]) -> str:
@@ -401,6 +403,29 @@ def _ensure_uma_access_requests_table(conn: sqlite3.Connection) -> None:
                 conn.commit()
     except Exception as exc:
         logger.warning("Failed to ensure uma_access_requests table exists: %s", exc)
+    else:
+        _migrate_legacy_browser_plugin_app_ids(conn)
+
+
+def _migrate_legacy_browser_plugin_app_ids(conn: sqlite3.Connection) -> int:
+    """Rewrite engine Activity counts from browser-plugin → browser-history-plugin (idempotent)."""
+    try:
+        cursor = conn.execute(
+            f"UPDATE {UMA_ACCESS_REQUESTS_TABLE} SET app_id = ? WHERE app_id = ?",
+            (BROWSER_HISTORY_PLUGIN_APP_ID, LEGACY_BROWSER_PLUGIN_APP_ID),
+        )
+        if cursor.rowcount:
+            conn.commit()
+            logger.info(
+                "Migrated %s uma_access_requests rows: %s → %s",
+                cursor.rowcount,
+                LEGACY_BROWSER_PLUGIN_APP_ID,
+                BROWSER_HISTORY_PLUGIN_APP_ID,
+            )
+        return int(cursor.rowcount or 0)
+    except Exception as exc:
+        logger.warning("browser-plugin app_id migration on engine failed: %s", exc)
+        return 0
 
 
 def record_uma_request(
@@ -463,6 +488,7 @@ def get_uma_request_counts(
         "total_read_requests": 0,
         "total_write_requests": 0,
         "by_app": [],
+        "by_app_requester": [],
         "by_requesting_user": [],
         "access_attribution": {
             "window_days": since_days or 0,
@@ -510,6 +536,38 @@ def get_uma_request_counts(
                 for aid, d in sorted(by_app.items())
             ]
 
+            cursor = conn.execute(
+                f"""SELECT app_id, requesting_user_id, requesting_user_email, request_type
+                    FROM {UMA_ACCESS_REQUESTS_TABLE}
+                    WHERE owner_user_id = ? AND created_at >= ?""",
+                (owner_user_id, since_ts),
+            )
+            by_app_req: Dict[str, Dict[str, Any]] = {}
+            for row in cursor.fetchall():
+                app_id_val = (row[0] or "").strip() if len(row) > 0 else ""
+                rid = (row[1] or "").strip() if len(row) > 1 else ""
+                remail = (row[2] or "").strip() if len(row) > 2 else ""
+                rt = (row[3] or "").strip().lower() if len(row) > 3 else ""
+                key = f"{app_id_val}\0{rid}\0{remail}"
+                if key not in by_app_req:
+                    by_app_req[key] = {
+                        "app_id": app_id_val or None,
+                        "requesting_user_id": rid or None,
+                        "requesting_user_email": remail or None,
+                        "read_requests": 0,
+                        "write_requests": 0,
+                    }
+                if rt == "read":
+                    by_app_req[key]["read_requests"] += 1
+                elif rt == "write":
+                    by_app_req[key]["write_requests"] += 1
+            app_req_ranked = []
+            for d in by_app_req.values():
+                tr = int(d["read_requests"]) + int(d["write_requests"])
+                app_req_ranked.append({**d, "total_requests": tr})
+            app_req_ranked.sort(key=lambda x: -x["total_requests"])
+            out["by_app_requester"] = app_req_ranked[:50]
+
             cursor = conn.execute(
                 f"""SELECT requesting_user_id, requesting_user_email, request_type, access_context
                     FROM {UMA_ACCESS_REQUESTS_TABLE}

topos_node-0.1.9/topos/runtime_update.py

@@ -0,0 +1,246 @@
+"""Runtime PyPI update checks for the Topos node (non-blocking while server runs)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import subprocess
+import sys
+import threading
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version as package_version
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from packaging.version import InvalidVersion, Version
+
+DEFAULT_PACKAGE_NAME = "topos-node"
+DEFAULT_CHECK_INTERVAL_SECONDS = 6 * 60 * 60
+INITIAL_CHECK_DELAY_SECONDS = 10.0
+PYPI_TIMEOUT_SECONDS = 2.0
+
+_logger = logging.getLogger("topos.runtime_update")
+_lock = threading.Lock()
+_update_info: UpdateInfo | None = None
+_announcement_logged = False
+_monitor_task: asyncio.Task[None] | None = None
+_hotkey_thread: threading.Thread | None = None
+
+
+@dataclass(frozen=True)
+class UpdateInfo:
+    package_name: str
+    installed: str
+    latest: str
+
+
+def should_skip_update_check(*, cli_skip: bool = False) -> bool:
+    if cli_skip:
+        return True
+    env_value = (os.getenv("TOPOS_SKIP_UPDATE_CHECK") or "").strip().lower()
+    return env_value in {"1", "true", "yes", "on"}
+
+
+def get_installed_package_version(package_name: str = DEFAULT_PACKAGE_NAME) -> str | None:
+    try:
+        return package_version(package_name)
+    except PackageNotFoundError:
+        return None
+
+
+def get_module_version() -> str | None:
+    try:
+        from topos.__version__ import __version__
+    except Exception:
+        return None
+    return __version__ or None
+
+
+def get_runtime_version(package_name: str = DEFAULT_PACKAGE_NAME) -> str:
+    return get_module_version() or get_installed_package_version(package_name) or "unknown"
+
+
+def get_latest_pypi_version(
+    package_name: str = DEFAULT_PACKAGE_NAME,
+    timeout_seconds: float = PYPI_TIMEOUT_SECONDS,
+) -> str | None:
+    url = f"https://pypi.org/pypi/{package_name}/json"
+    try:
+        with urlopen(url, timeout=timeout_seconds) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, URLError, ValueError):
+        return None
+    return str(payload.get("info", {}).get("version") or "").strip() or None
+
+
+def is_update_available() -> bool:
+    with _lock:
+        return _update_info is not None
+
+
+def get_update_info() -> UpdateInfo | None:
+    with _lock:
+        return _update_info
+
+
+def _set_update_info(info: UpdateInfo | None) -> None:
+    global _update_info
+    with _lock:
+        _update_info = info
+
+
+def _is_newer_version(installed: str, latest: str) -> bool:
+    try:
+        return Version(latest) > Version(installed)
+    except InvalidVersion:
+        return False
+
+
+def check_for_update(package_name: str = DEFAULT_PACKAGE_NAME) -> UpdateInfo | None:
+    """Return update details when PyPI has a newer release, else None."""
+    if should_skip_update_check():
+        return None
+
+    installed = get_installed_package_version(package_name) or get_module_version()
+    if not installed or installed == "unknown":
+        return None
+
+    latest = get_latest_pypi_version(package_name)
+    if not latest or not _is_newer_version(installed, latest):
+        return None
+
+    return UpdateInfo(package_name=package_name, installed=installed, latest=latest)
+
+
+def apply_package_update(package_name: str = DEFAULT_PACKAGE_NAME) -> bool:
+    """Install the latest PyPI release via `uv tool upgrade`. Returns True on success."""
+    result = subprocess.run(["uv", "tool", "upgrade", package_name], check=False)
+    return result.returncode == 0
+
+
+def _log_update_available_once(info: UpdateInfo) -> None:
+    global _announcement_logged
+    with _lock:
+        if _announcement_logged:
+            return
+        _announcement_logged = True
+
+    _logger.warning(
+        "New Topos version available: %s -> %s. "
+        "Timestamps will show in amber until you restart. "
+        "Update with `uv tool upgrade %s` then stop (Ctrl+C) and re-run `topos-node`. "
+        "In an interactive terminal, type `:update` and press Enter to install now.",
+        info.installed,
+        info.latest,
+        info.package_name,
+    )
+
+
+async def _monitor_loop(
+    *,
+    package_name: str = DEFAULT_PACKAGE_NAME,
+    initial_delay_seconds: float = INITIAL_CHECK_DELAY_SECONDS,
+    interval_seconds: float = DEFAULT_CHECK_INTERVAL_SECONDS,
+) -> None:
+    await asyncio.sleep(initial_delay_seconds)
+    while True:
+        try:
+            info = await asyncio.to_thread(check_for_update, package_name)
+            if info:
+                _set_update_info(info)
+                _log_update_available_once(info)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            _logger.debug("Runtime update check failed (non-fatal): %s", exc)
+        await asyncio.sleep(interval_seconds)
+
+
+def start_runtime_update_monitor(
+    *,
+    cli_skip: bool = False,
+    package_name: str = DEFAULT_PACKAGE_NAME,
+) -> asyncio.Task[None] | None:
+    """Schedule periodic PyPI checks; safe to call once at app startup."""
+    global _monitor_task
+    if should_skip_update_check(cli_skip=cli_skip):
+        return None
+    if _monitor_task is not None and not _monitor_task.done():
+        return _monitor_task
+
+    loop = asyncio.get_running_loop()
+    _monitor_task = loop.create_task(
+        _monitor_loop(package_name=package_name),
+        name="topos-runtime-update-monitor",
+    )
+    return _monitor_task
+
+
+async def stop_runtime_update_monitor() -> None:
+    global _monitor_task
+    task = _monitor_task
+    _monitor_task = None
+    if task is None:
+        return
+    task.cancel()
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+
+
+def _handle_hotkey_line(line: str, package_name: str = DEFAULT_PACKAGE_NAME) -> None:
+    command = line.strip().lower()
+    if command not in {":update", ":u"}:
+        return
+
+    info = get_update_info() or check_for_update(package_name)
+    if not info:
+        _logger.info("Topos is already on the latest published version.")
+        return
+
+    _logger.info("Updating %s (%s -> %s)...", package_name, info.installed, info.latest)
+    if apply_package_update(package_name):
+        _logger.warning(
+            "Update installed. Stop Topos (Ctrl+C) and re-run `topos-node` to use %s.",
+            info.latest,
+        )
+    else:
+        _logger.error("Update failed. Run `uv tool upgrade %s` manually.", package_name)
+
+
+def _hotkey_listener_loop(package_name: str = DEFAULT_PACKAGE_NAME) -> None:
+    try:
+        for line in sys.stdin:
+            _handle_hotkey_line(line, package_name=package_name)
+    except Exception as exc:  # noqa: BLE001
+        _logger.debug("Update hotkey listener stopped: %s", exc)
+
+
+def start_update_hotkey_listener(
+    *,
+    cli_skip: bool = False,
+    package_name: str = DEFAULT_PACKAGE_NAME,
+) -> None:
+    """Listen for `:update` on stdin (interactive terminals only)."""
+    global _hotkey_thread
+    if should_skip_update_check(cli_skip=cli_skip):
+        return
+    if not sys.stdin.isatty():
+        return
+    if _hotkey_thread is not None and _hotkey_thread.is_alive():
+        return
+
+    _hotkey_thread = threading.Thread(
+        target=_hotkey_listener_loop,
+        kwargs={"package_name": package_name},
+        name="topos-update-hotkey",
+        daemon=True,
+    )
+    _hotkey_thread.start()
+
+
+def can_prompt_for_input() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()