topos-node 1.3.1__tar.gz → 1.3.3__tar.gz

{topos_node-1.3.1 → topos_node-1.3.3}/MANIFEST.in

@@ -3,3 +3,5 @@
 # topos/query/scope_registry.json, whose absence denies every scoped query.
 recursive-include topos *.json
 recursive-include shared *.json
+# Tray icon glyphs (topos/cli/assets) — without them the tray cannot render.
+recursive-include topos *.png

{topos_node-1.3.1/topos_node.egg-info → topos_node-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.3.1
+Version: 1.3.3
 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
@@ -33,7 +33,12 @@ Requires-Dist: hf-xet~=1.5.1
 Requires-Dist: sentence-transformers~=5.6.0
 Requires-Dist: networkx<3.7,>=3.2.1
 Requires-Dist: python-louvain<0.17,>=0.16
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: scikit-learn<2,>=1.4
 Requires-Dist: sqlite-vec~=0.1.9
+Requires-Dist: pystray~=0.19.5
+Requires-Dist: pillow>=10.0
 Provides-Extra: database
 Requires-Dist: psycopg[binary]~=3.3.3; extra == "database"
 Provides-Extra: engine
@@ -46,6 +51,9 @@ Requires-Dist: hf-xet~=1.5.1; extra == "engine"
 Requires-Dist: sentence-transformers~=5.6.0; extra == "engine"
 Requires-Dist: networkx<3.7,>=3.2.1; extra == "engine"
 Requires-Dist: python-louvain<0.17,>=0.16; extra == "engine"
+Requires-Dist: numpy<3,>=1.26; extra == "engine"
+Requires-Dist: scipy<2,>=1.11; extra == "engine"
+Requires-Dist: scikit-learn<2,>=1.4; extra == "engine"
 Provides-Extra: local
 Provides-Extra: signal
 Requires-Dist: pysqlcipher3~=1.2.0; extra == "signal"

{topos_node-1.3.1 → topos_node-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.3.1"
+version = "1.3.3"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,7 +35,15 @@ dependencies = [
   "sentence-transformers~=5.6.0",
   "networkx>=3.2.1,<3.7",
   "python-louvain>=0.16,<0.17",
+  # Complexity readings (topos.features.complexity): entropy/MI + graph math.
+  "numpy>=1.26,<3",
+  "scipy>=1.11,<2",
+  "scikit-learn>=1.4,<2",
   "sqlite-vec~=0.1.9",
+  # Menu-bar/system-tray status icon (topos.cli.tray). Imported lazily and
+  # only when a GUI session is detected — harmless on headless installs.
+  "pystray~=0.19.5",
+  "pillow>=10.0",
 ]
 
 [project.urls]
@@ -58,6 +66,9 @@ engine = [
   "sentence-transformers~=5.6.0",
   "networkx>=3.2.1,<3.7",
   "python-louvain>=0.16,<0.17",
+  "numpy>=1.26,<3",
+  "scipy>=1.11,<2",
+  "scikit-learn>=1.4,<2",
 ]
 # Backward-compatible alias; local runtime deps are in core dependencies.
 local = []
@@ -109,6 +120,7 @@ markers = [
   "adversarial: scope-break / access-control adversarial test (privacy enforcement)",
   "uar: unauthorized-access-rate probe (privacy claim #1); tier-1 CI gate, must find zero leaks",
   "cer: canary-extraction-rate probe (privacy claim #2); tier-1 CI gate",
+  "bhlr: black-hole leak-rate probe (entity black hole); tier-1 CI gate, must find zero leaks",
   "eval_nightly: statistical privacy eval (attacker advantage, minimality, latency); nightly",
   "eval_release: release-tier privacy eval (negotiation A/B, Pareto); run per release",
 ]

{topos_node-1.3.1 → topos_node-1.3.3}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.3.1"
-__version_info__ = (1, 3, 1)
+__version__ = "1.3.3"
+__version_info__ = (1, 3, 3)
 
 __all__ = ["__version__", "__version_info__"]

{topos_node-1.3.1 → topos_node-1.3.3}/topos/api/llm.py

@@ -16,6 +16,51 @@ logger = logging.getLogger("topos.api.llm")
 router = APIRouter()
 
 
+def _enforce_blackhole_egress(body: GenerationRequest) -> GenerationRequest:
+    """Gate B: this route reaches cloud providers without passing the engine router.
+
+    `Engine.run` gates every task-shaped inference, but these two endpoints call
+    the LLM service directly, so the same policy has to be applied here or the
+    hole stays open. Rewrites the provider onto a secure one when the prompt
+    mentions a protected entity; refuses when nothing secure can serve it.
+
+    The refusal is owner-facing (this route is API-key authenticated) and still
+    names no entity — the reason may be logged somewhere less private.
+    """
+    from fastapi import HTTPException
+
+    try:
+        from ..engine.engine import _policy_db_connection
+        from ..features.lifecycle.blackhole_llm import describe_block, evaluate
+    except Exception:  # noqa: BLE001
+        return body
+
+    conn, owned = _policy_db_connection()
+    try:
+        verdict = evaluate(
+            conn,
+            {"prompt": body.prompt, "system": getattr(body, "system", None)},
+            provider=body.provider or "",
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=503, detail=f"blackhole_policy_unavailable: {exc}")
+    finally:
+        if owned and conn is not None:
+            try:
+                conn.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    if not verdict.tainted:
+        return body
+    if verdict.blocked:
+        raise HTTPException(status_code=503, detail=describe_block(verdict))
+    if verdict.redirected:
+        logger.info("blackhole: llm route redirected to %s", verdict.provider)
+        return body.model_copy(update={"provider": verdict.provider, "model": None})
+    return body
+
+
 @router.post(
     "/llm_generation",
     response_model=GenerationResponse,
@@ -28,6 +73,7 @@ async def llm_generation(body: GenerationRequest):
         body.model,
         len(body.prompt or ""),
     )
+    body = _enforce_blackhole_egress(body)
     services: Services = get_services()
     result = await services.llm.generate(body.model_dump())
     usage = result.get("usage") if isinstance(result, dict) else {}
@@ -60,6 +106,7 @@ async def llm_generation_alias(body: GenerationRequest):
         body.model,
         len(body.prompt or ""),
     )
+    body = _enforce_blackhole_egress(body)
     services: Services = get_services()
     result = await services.llm.generate(body.model_dump())
     usage = result.get("usage") if isinstance(result, dict) else {}

topos_node-1.3.3/topos/api/shell.py

@@ -0,0 +1,91 @@
+"""Shell contract endpoints.
+
+Everything a menu-bar/tray shell (the pystray tray, the future Swift macOS
+shell, the Windows shell) needs to supervise this node lives here, so shells
+stay dumb renderers: identity + version for attach-don't-double-start, the
+log file location for a "Show Logs" action, and cached update state with a
+localhost-only trigger to apply an update.
+
+Update *checking* is not done here — the runtime update monitor started in
+app startup keeps ``get_update_info()`` fresh; this router only reads it.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from time import time
+
+from fastapi import APIRouter, HTTPException, Request
+
+from ..core.logging import get_log_file_path
+from ..runtime_update import (
+    DEFAULT_PACKAGE_NAME,
+    apply_package_update,
+    get_runtime_version,
+    get_update_info,
+)
+
+router = APIRouter(prefix="/v1/shell", tags=["shell"])
+
+_STARTED_AT = time()
+
+_apply_lock = threading.Lock()
+_apply_state: dict[str, object] = {"applying": False, "last_result": None}
+
+
+def _client_is_local(request: Request) -> bool:
+    # Applying an update is the one mutating action here; a LAN peer must not
+    # be able to trigger it even though the node binds 0.0.0.0. ("testclient"
+    # is FastAPI's TestClient peer name — unreachable over a real socket.)
+    host = request.client.host if request.client else None
+    return host in ("127.0.0.1", "::1", "localhost", "testclient")
+
+
+@router.get("/status")
+async def shell_status() -> dict:
+    info = get_update_info()
+    log_file = get_log_file_path()
+    return {
+        "name": "topos-node",
+        "version": get_runtime_version(),
+        "pid": os.getpid(),
+        "started_at": _STARTED_AT,
+        "log_file": str(log_file) if log_file else None,
+        "update": {
+            "available": info is not None,
+            "installed": info.installed if info else None,
+            "latest": info.latest if info else None,
+            "applying": _apply_state["applying"],
+            "last_result": _apply_state["last_result"],
+        },
+    }
+
+
+@router.post("/update")
+async def shell_apply_update(request: Request) -> dict:
+    if not _client_is_local(request):
+        raise HTTPException(
+            status_code=403, detail="Shell update can only be triggered from localhost."
+        )
+    if get_update_info() is None:
+        return {"started": False, "reason": "no_update_available"}
+    with _apply_lock:
+        if _apply_state["applying"]:
+            return {"started": False, "reason": "already_applying"}
+        _apply_state["applying"] = True
+        _apply_state["last_result"] = None
+
+    def worker() -> None:
+        ok = False
+        try:
+            ok = apply_package_update(DEFAULT_PACKAGE_NAME)
+        finally:
+            with _apply_lock:
+                _apply_state["applying"] = False
+                # The running process keeps the old version until restart;
+                # shells surface "restart to finish" off this value.
+                _apply_state["last_result"] = "success" if ok else "failed"
+
+    threading.Thread(target=worker, daemon=True, name="topos-shell-update").start()
+    return {"started": True}

{topos_node-1.3.1 → topos_node-1.3.3}/topos/api/signal.py

@@ -217,9 +217,12 @@ async def list_entities(
 ):
     """Resolved entity registry (entity spine), sorted by mention count."""
     from ..features.entities.reads import list_entities as _list
+    from ..features.lifecycle.blackhole_guard import owner_ui_guard
 
+    conn = _entities_conn()
     return _list(
-        _entities_conn(),
+        conn,
+        guard=owner_ui_guard(conn),
         q=q,
         entity_type=entity_type,
         contacts_only=contacts_only,
@@ -253,11 +256,13 @@ async def get_entity_graph(
     import asyncio
 
     from ..features.entities.reads import entity_graph
+    from ..features.lifecycle.blackhole_guard import owner_ui_guard
 
     conn = _entities_conn()
     return await asyncio.to_thread(
         entity_graph,
         conn,
+        guard=owner_ui_guard(conn),
         limit_nodes=limit_nodes,
         limit_edges=limit_edges,
         min_weight=min_weight,
@@ -347,8 +352,10 @@ async def get_entity(
 ):
     """Entity detail: aliases, connections, recent mentions, dossier (owner view)."""
     from ..features.entities.reads import get_entity_detail
+    from ..features.lifecycle.blackhole_guard import owner_ui_guard
 
-    detail = get_entity_detail(_entities_conn(), entity_id)
+    conn = _entities_conn()
+    detail = get_entity_detail(conn, entity_id, guard=owner_ui_guard(conn))
     if detail is None:
         raise HTTPException(status_code=404, detail=f"entity not found: {entity_id}")
     return detail
@@ -458,6 +465,79 @@ async def exclude_entity_from_intelligence(
         raise HTTPException(status_code=400, detail=str(exc))
 
 
+class EntityBlackholeBody(BaseModel):
+    processing_tier: str = Field(default="secure", max_length=20)
+    note: Optional[str] = Field(default=None, max_length=500)
+
+
+@router.post("/entities/{entity_id}/blackhole")
+async def blackhole_entity(
+    entity_id: str,
+    body: EntityBlackholeBody = EntityBlackholeBody(),
+    _api_key: str = Depends(require_api_key),
+):
+    """Owner black hole: this entity is mine alone.
+
+    Nothing is deleted — the owner keeps full visibility. Every other caller
+    (third-party MCP agents, routines, grantees) is denied, and content
+    mentioning it may only be processed by the tier's secure model set.
+    Raises a rebuild-needed notification before the rebuild runs (D4).
+    """
+    import asyncio
+
+    from ..features.lifecycle.blackhole import BlackholeStore
+    from ..features.lifecycle.blackhole_rebuild import rebuild_for_blackhole
+
+    conn = _entities_conn()
+    try:
+        result = BlackholeStore(conn).blackhole_entity(
+            entity_ref=entity_id,
+            processing_tier=body.processing_tier,
+            note=body.note,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    # D4: the notification above was raised first, so the owner already knows the
+    # hide is incomplete; now do the rebuild that makes it true. Non-owners are
+    # withheld the prose artifacts for the duration, so this running late is safe
+    # while it running silently would not be.
+    if not result.get("already_blackholed"):
+        result["rebuild"] = await asyncio.to_thread(rebuild_for_blackhole, conn, entity_id)
+        result["rebuild"] = result["rebuild"].as_dict()
+    return result
+
+
+@router.delete("/entities/{entity_id}/blackhole")
+async def unblackhole_entity(
+    entity_id: str,
+    _api_key: str = Depends(require_api_key),
+):
+    """Lift a black hole. Existing grants are not restored — normal permissions resume."""
+    from ..features.lifecycle.blackhole import BlackholeStore
+
+    return BlackholeStore(_entities_conn()).unblackhole_entity(entity_ref=entity_id)
+
+
+@router.get("/blackholes")
+async def list_blackholes(_api_key: str = Depends(require_api_key)):
+    """The owner's off-limits list (mirrors the exclusions list in the drawer)."""
+    from ..features.lifecycle.blackhole import BlackholeStore
+
+    store = BlackholeStore(_entities_conn())
+    return {"blackholes": store.list(), "notifications": store.notifications(state="open")}
+
+
+@router.post("/blackholes/notifications/{notification_id}/dismiss")
+async def dismiss_blackhole_notification(
+    notification_id: str,
+    _api_key: str = Depends(require_api_key),
+):
+    from ..features.lifecycle.blackhole import BlackholeStore
+
+    return {"dismissed": BlackholeStore(_entities_conn()).dismiss_notification(notification_id)}
+
+
 @router.get("/facts")
 async def list_facts(
     predicate: Optional[str] = Query(default=None, max_length=80),
@@ -653,6 +733,23 @@ async def refresh_dimension_brief(
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
 
+# --------------------------------------------------------------- timeline rollup
+
+@router.get("/timeline/daily")
+async def timeline_daily(
+    _api_key: str = Depends(require_api_key),
+    days: int = Query(90, ge=1, le=365),
+):
+    """Per-day lane counts + births + episodes (PLAN_TIMELINE_UNIFIED.md E1)."""
+    from ..core.state import get_db_connection
+    from ..features.timeline_rollup import timeline_daily_rollup
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return timeline_daily_rollup(conn, days=days)
+
+
 # --------------------------------------------------------------- attention triage
 
 @router.get("/attention/dashboard")
@@ -669,3 +766,99 @@ async def attention_dashboard(
     if conn is None:
         raise HTTPException(status_code=503, detail="database unavailable")
     return attention_dashboard_data(conn, days=days, include_titles=include_titles)
+
+
+# --------------------------------------------------------------- complexity
+
+@router.get("/complexity/summary")
+async def complexity_summary(
+    _api_key: str = Depends(require_api_key),
+    recompute: bool = Query(False),
+    weeks: int = Query(12, ge=1, le=104),
+    window_days: int = Query(30, ge=1, le=3650),
+    half_life_days: Optional[float] = Query(None, ge=0.1, le=3650.0),
+):
+    """Data spine for the /data/complexity tab (PLAN_COMPLEXITY_DATA_PAGE.md).
+
+    Snapshot computation is CPU-bound (~1s cold on a live-size DB), so it runs
+    in a worker thread; warm calls serve the complexity_snapshots cache.
+    """
+    import asyncio
+
+    from ..core.state import get_db_connection
+    from ..features.complexity.engine import get_complexity_summary
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return await asyncio.to_thread(
+        get_complexity_summary,
+        conn,
+        recompute=recompute,
+        weeks=weeks,
+        window_days=window_days,
+        half_life_days=half_life_days,
+    )
+
+
+@router.get("/complexity/timeline")
+async def complexity_timeline(
+    _api_key: str = Depends(require_api_key),
+    recompute: bool = Query(False),
+    weeks: int = Query(12, ge=1, le=104),
+):
+    import asyncio
+
+    from ..core.state import get_db_connection
+    from ..features.complexity.engine import get_shift_timeline
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return await asyncio.to_thread(get_shift_timeline, conn, recompute=recompute, weeks=weeks)
+
+
+@router.get("/complexity/topics/daily")
+async def complexity_topics_daily(
+    _api_key: str = Depends(require_api_key),
+    days: int = Query(90, ge=1, le=365),
+    top: int = Query(10, ge=1, le=24),
+):
+    """Per-day supertopic shares — the braid's substrate (PLAN_TIMELINE_UNIFIED.md E2)."""
+    import asyncio
+
+    from ..core.state import get_db_connection
+    from ..features.complexity.topics_daily import topics_daily
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return await asyncio.to_thread(topics_daily, conn, days=days, top=top)
+
+
+@router.get("/complexity/influence")
+async def complexity_influence(
+    _api_key: str = Depends(require_api_key),
+    recompute: bool = Query(False),
+    weeks: int = Query(12, ge=1, le=104),
+    top_k: int = Query(5, ge=1, le=50),
+    window_days: int = Query(90, ge=1, le=3650),
+    target: Optional[str] = Query(None, max_length=500),
+):
+    import asyncio
+
+    from ..core.state import get_db_connection
+    from ..features.complexity.engine import get_influence_threads
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return await asyncio.to_thread(
+        get_influence_threads,
+        conn,
+        recompute=recompute,
+        weeks=weeks,
+        top_k=top_k,
+        window_days=window_days,
+        target=target,
+    )

{topos_node-1.3.1 → topos_node-1.3.3}/topos/api/uma_data.py

@@ -253,8 +253,12 @@ async def get_uma_messages(
     )
     items = _get_messages_from_db(conn, effective_dataset_id, limited, offset, allowed_tables=allowed_tables)
     try:
+        # UMA data proxy = the grantee HTTP lane; filter unconditionally.
+        from ..features.lifecycle.blackhole_guard import BlackholeGuard, CallerClass
+
         items, uma_contact_sidecar = apply_message_contact_pipeline(
             items,
+            blackhole_guard=BlackholeGuard(conn, caller_class=CallerClass.GRANTEE),
             conn=conn,
             dataset_id=effective_dataset_id,
             allowed_scopes=allowed_scopes,

{topos_node-1.3.1 → topos_node-1.3.3}/topos/app.py

@@ -48,6 +48,7 @@ from .api import (
     home_chat as home_chat_routes,
     privacy_disclose as privacy_disclose_routes,
     signal as signal_routes,
+    shell as shell_routes,
     tool_index as tool_index_routes,
     upgrades as upgrades_routes,
 )
@@ -100,6 +101,7 @@ app.add_middleware(
 )
 
 app.include_router(health_routes.router)
+app.include_router(shell_routes.router)
 app.include_router(upgrades_routes.router)
 app.include_router(local_mcp_routes.router)
 app.include_router(llm_routes.router)

{topos_node-1.3.1 → topos_node-1.3.3}/topos/cli/commands.py

@@ -132,6 +132,29 @@ def _emit_startup_banner(host: str, port: int, package_name: str = DEFAULT_PACKA
     os.environ["TOPOS_STARTUP_BANNER_EMITTED"] = "1"
 
 
+def _probe_running_node(host: str, port: int) -> dict | None:
+    """Return the running node's shell status (or minimal version dict) if one
+    is already serving this port; None when the port is free or not a topos node."""
+    import httpx
+
+    probe_host = "127.0.0.1" if host in ("0.0.0.0", "::") else host
+    base = f"http://{probe_host}:{port}"
+    try:
+        response = httpx.get(f"{base}/v1/shell/status", timeout=2.0)
+        if response.status_code == 200 and response.json().get("name") == "topos-node":
+            return response.json()
+    except Exception:
+        return None
+    try:
+        # Older node without the shell endpoint.
+        response = httpx.get(f"{base}/version", timeout=2.0)
+        if response.status_code == 200 and "version" in response.json():
+            return {"version": response.json()["version"]}
+    except Exception:
+        return None
+    return None
+
+
 def _maybe_offer_self_update(
     skip_update_check: bool,
     package_name: str = DEFAULT_PACKAGE_NAME,
@@ -194,7 +217,19 @@ def _maybe_offer_self_update(
     is_flag=True,
     help="Skip checking PyPI for a newer topos-node version.",
 )
-def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_check) -> None:
+@click.option(
+    "--tray/--no-tray",
+    "tray",
+    default=None,
+    help="Show a menu-bar/system-tray status icon (default: auto-detect GUI).",
+)
+@click.option(
+    "--app",
+    "app_mode",
+    is_flag=True,
+    help="App mode: tray icon only, logs to ~/.topos/logs/node.log instead of the terminal.",
+)
+def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_check, tray, app_mode) -> None:
     """Topos Control Plane API entry point."""
     if set_topos_key:
         env_path = _save_topos_key(set_topos_key)
@@ -221,8 +256,45 @@ def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_ch
     _load_env_file(USER_ENV_PATH)
     _load_env_file(LEGACY_ENV_PATH)
 
+    if app_mode and tray is None:
+        tray = True
+
+    # Attach, don't double-start: two nodes on one ~/.topos DB is a corruption
+    # risk, and for launchers "make sure Topos is running" should be idempotent.
+    running = _probe_running_node(host, port)
+    if running is not None:
+        running_version = running.get("version", "unknown")
+        from topos.cli import tray as tray_module
+
+        if tray_module.should_enable_tray(cli_flag=tray):
+            click.echo(
+                f"Topos Node v{running_version} is already running on port {port} — "
+                "attaching tray to it (closing this tray leaves the node running)."
+            )
+            log_file = running.get("log_file")
+            tray_module.attach_tray(
+                host=host,
+                port=port,
+                version=running_version,
+                package_name=DEFAULT_PACKAGE_NAME,
+                log_path=Path(log_file) if log_file else None,
+            )
+            return
+        raise click.ClickException(
+            f"Topos Node v{running_version} is already running on port {port}. "
+            "Use --port to start a second instance."
+        )
+
     _resolve_topos_key(topos_key)
 
+    if app_mode:
+        # Must happen before `topos.app` is imported — configure_logging() runs
+        # at import time and reads TOPOS_LOG_FILE to pick file vs stdout.
+        from topos.core.logging import default_node_log_path
+
+        os.environ.setdefault("TOPOS_LOG_FILE", str(default_node_log_path()))
+        click.echo(f"App mode: logs → {os.environ['TOPOS_LOG_FILE']}")
+
     from topos.app import app
     from topos.core.logging import get_uvicorn_log_config
 
@@ -235,7 +307,23 @@ def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_ch
     start_background_housekeeping()
 
     _emit_startup_banner(host=host, port=port)
-    uvicorn.run(app, host=host, port=port, log_config=get_uvicorn_log_config())
+
+    from topos.cli import tray as tray_module
+
+    if tray_module.should_enable_tray(cli_flag=tray):
+        from topos.core.logging import get_log_file_path
+
+        tray_module.serve_with_tray(
+            app,
+            host=host,
+            port=port,
+            log_config=get_uvicorn_log_config(),
+            version=_get_runtime_version(),
+            package_name=DEFAULT_PACKAGE_NAME,
+            log_path=get_log_file_path(),
+        )
+    else:
+        uvicorn.run(app, host=host, port=port, log_config=get_uvicorn_log_config())
 
 
 if __name__ == "__main__":