@maudecode/talaria-web 1.18.0 → 1.20.0

package/sidecar/talaria_sidecar/runtime.py

@@ -10,12 +10,15 @@ from __future__ import annotations
 
 import errno
 import importlib
+import hashlib
 import json
 import math
 import os
+import re
 import stat
 import subprocess
 import sys
+import sysconfig
 import threading
 import time
 from pathlib import Path
@@ -24,11 +27,8 @@ from . import SIDECAR_RPC_VERSION
 from .errors import RpcError
 
 PIN_PATH = Path(__file__).resolve().parent.parent / "agent_dependency.json"
-_RESTART_REQUIRED_MESSAGE = (
-    "Hermes Agent was updated while Talaria Web was running. "
-    "Talaria Web cannot verify that the Agent update completed safely. "
-    "Check the Agent update outcome and environment first. "
-    "Restart Talaria Web manually before retrying this action."
+_RUNTIME_UNAVAILABLE_MESSAGE = (
+    "Agent runtime is unavailable. Check the Agent update outcome before retrying this action."
 )
 _AGENT_UPDATE_MARKER = ".hermes-update-in-progress"
 _AGENT_RECOVERY_MARKERS = (".update-incomplete", ".lazy-refresh-incomplete")
@@ -40,11 +40,16 @@ _MARKER_SAFE_OPEN_AVAILABLE = bool(_O_NOFOLLOW) and bool(_O_NONBLOCK)
 
 
 class AgentRuntimeStale(RpcError):
-    def __init__(self, update_state: str | None):
-        data = {"retryable": True, "restart_scheduled": False}
+    def __init__(self, update_state: str | None, message: str | None = None, *, source_changed: bool = False):
+        data = {"retryable": True, "restart_scheduled": False, "agent_source_changed": source_changed}
         if update_state is not None:
             data["agent_update_state"] = update_state
-        super().__init__(_RESTART_REQUIRED_MESSAGE, condition="agent_runtime_stale", data=data)
+        if message is None:
+            message = {
+                "active": "Agent update is in progress. Wait for it to finish before starting new work.",
+                "incomplete": "Agent update recovery is incomplete. Finish the Agent update before starting new work.",
+            }.get(update_state, _RUNTIME_UNAVAILABLE_MESSAGE)
+        super().__init__(message, condition="agent_runtime_stale", data=data)
 
 
 class AgentIncompatible(RpcError):
@@ -217,6 +222,45 @@ def installed_agent_version() -> str | None:
     return get_version_info().base_version
 
 
+def _python_abi(major: int | str, minor: int | str, free_threaded: bool) -> str:
+    """``3.14`` or ``3.14t``: regular and free-threaded builds of one version load different native extensions."""
+    return f"{major}.{minor}{'t' if free_threaded else ''}"
+
+
+def _site_packages_python(entry: str) -> tuple[str, Path] | None:
+    """The Python ABI a ``sys.path`` site-packages directory was built for, and that venv's interpreter."""
+    path = Path(entry)
+    if path.name != "site-packages" or not path.is_dir():
+        return None
+    match = re.fullmatch(r"python(\d+)\.(\d+)(t?)", path.parent.name)
+    if match and path.parent.parent.name in {"lib", "lib64"}:
+        return _python_abi(match[1], match[2], bool(match[3])), path.parent.parent.parent / "bin" / "python"
+    if path.parent.name.lower() == "lib":
+        venv = path.parent.parent
+        try:
+            config = (venv / "pyvenv.cfg").read_text(encoding="utf-8")
+        except OSError:
+            return None
+        found = re.search(r"^\s*version(?:_info)?\s*=\s*(\d+)\.(\d+)", config, re.MULTILINE)
+        if found:
+            free_threaded = re.search(r"^\s*executable\s*=.*python\d+\.\d+t(?:\.exe)?\s*$", config, re.MULTILINE | re.IGNORECASE)
+            return _python_abi(found[1], found[2], bool(free_threaded)), venv / "Scripts" / "python.exe"
+    return None
+
+
+def _check_site_packages_python() -> None:
+    """Compiled Agent dependencies load lazily on the first chat; fail the handshake when ``sys.path`` holds
+    site-packages built for another Python (a stale ``HERMES_WEBUI_PYTHON`` after a PM environment update)."""
+    running = _python_abi(sys.version_info[0], sys.version_info[1], bool(sysconfig.get_config_var("Py_GIL_DISABLED")))
+    for entry in sys.path:
+        built = _site_packages_python(entry)
+        if built is not None and built[0] != running:
+            raise ImportError(
+                f"interpreter Python {running} cannot load Agent packages built for Python {built[0]} ({entry}); "
+                f"unset HERMES_WEBUI_PYTHON or point it at {built[1]}"
+            )
+
+
 class AgentRuntime:
     """Loads the Agent once and guards against a changed checkout."""
 
@@ -224,7 +268,9 @@ class AgentRuntime:
         self.hermes_home = Path(hermes_home)
         self._stale_lock = threading.Lock()
         self._stale = False
+        self._source_changed = False
         self._stale_stamp: tuple | None = None
+        self._receipt_discovery: dict = {}
         self.agent_dir = Path(agent_dir).resolve() if agent_dir else None
         self.pin = read_pin()
         self.loaded = False
@@ -232,20 +278,43 @@ class AgentRuntime:
         self.revision: str | None = None
         self.import_error: str | None = None
         self._lock = threading.Lock()
+        self._handoff = None
+        self._retired = False
 
     # ── loading ───────────────────────────────────────────────────────────
     def load(self) -> None:
         with self._lock:
+            if self._retired:
+                raise AgentRuntimeStale(None)
             if self.loaded:
                 return
             try:
+                # Direct Agent imports skip CLI startup's PM tool PATH activation.
+                if self.agent_dir is not None and (self.agent_dir / "pm").is_dir():
+                    compose_path = getattr(importlib.import_module("pm"), "store_first_path", None)
+                    if compose_path is not None:
+                        os.environ["PATH"] = compose_path(os.environ.get("PATH", ""))
                 module = importlib.import_module("run_agent")
                 getattr(module, "AIAgent")
                 # Agent 0.21.3 snapshots its auth provider registry, discovered plugins included, when hermes_cli.auth
                 # first imports. Take it here, under the launch profile and before any profile-scoped method runs, so
                 # a named profile's plugin loaded later never enters that process-wide snapshot.
                 importlib.import_module("hermes_cli.auth")
+                _check_site_packages_python()
+                try:
+                    handoff = importlib.import_module("hermes_cli.guest_handoff")
+                except ModuleNotFoundError as exc:
+                    if exc.name != "hermes_cli.guest_handoff":
+                        raise
+                else:
+                    # Retain custody even when startup raises after creating its thread.
+                    if not callable(handoff.start_worker) or not callable(handoff.stop_worker):
+                        raise RuntimeError("Native handoff lifecycle API is incomplete")
+                    self._handoff = handoff
+                    if not handoff.start_worker().is_alive():
+                        raise RuntimeError("Native handoff worker did not start")
             except Exception as exc:  # noqa: BLE001 - reported as a handshake condition
+                self._stop_handoff()
                 self.import_error = f"{type(exc).__name__}: {exc}"
                 raise AgentIncompatible(f"Hermes Agent could not be imported: {self.import_error}", import_error=self.import_error)
             module_file = getattr(module, "__file__", None)
@@ -255,6 +324,21 @@ class AgentRuntime:
             self.revision = read_agent_revision(self.agent_dir, self.module_path)
             self.loaded = True
 
+    def _stop_handoff(self) -> None:
+        if self._handoff is not None:
+            # Native requests are bounded. Join fully before code/dependencies may change.
+            self._handoff.stop_worker(timeout=None)
+            self._handoff = None
+
+    def retire(self) -> None:
+        """Release native background writes; only a fresh process may own them again."""
+        with self._lock:
+            if self._handoff is None:
+                return
+            self._retired = True
+            self.loaded = False
+            self._stop_handoff()
+
     @property
     def agent_version(self) -> str | None:
         try:
@@ -276,9 +360,12 @@ class AgentRuntime:
 
     def update_transaction_state(self) -> str:
         live = _read_live_agent_update(self.hermes_home / _AGENT_UPDATE_MARKER)
-        if live == "unknown":
+        if live in {"unknown", "active"}:
+            return live
+        repair = self.web_repair_state()
+        if repair == "unknown":
             return "unknown"
-        recovery = False
+        recovery = repair == "present"
         for root in self._install_roots():
             for name in _AGENT_RECOVERY_MARKERS:
                 presence = _marker_presence(root / name)
@@ -289,6 +376,17 @@ class AgentRuntime:
             return "incomplete"
         return "unverified" if live == "absent" else live
 
+    def web_repair_state(self) -> str:
+        if self.agent_dir is None:
+            return "absent"
+        from .agent_mutation import recovery_receipts
+        try:
+            with self._stale_lock:
+                receipts, _ = recovery_receipts(self, discovery_cache=self._receipt_discovery)
+            return 'present' if receipts else 'absent'
+        except (OSError, UnicodeError):
+            return 'unknown'
+
     def is_stale(self) -> bool:
         """True when the checkout revision no longer matches the loaded module.
 
@@ -310,19 +408,28 @@ class AgentRuntime:
                     fresh = None
                 if fresh is not None:
                     break
+            self._source_changed = fresh is not None and fresh != self.revision
             self._stale = fresh != self.revision
             self._stale_stamp = stamp if fresh is not None else None
-            return self._stale
+            stale = self._stale
+        if stale:
+            self.retire()
+        return stale
 
     def ensure_current(self) -> None:
-        """Raise ``agent_runtime_stale`` when the checkout changed since import."""
+        """Refuse Agent work until source drift or a durable Web update obligation is reconciled."""
+        repair = self.web_repair_state()
+        if repair != "absent":
+            self.retire()
+            raise AgentRuntimeStale("unknown" if repair == "unknown" else self.update_transaction_state())
         if self.is_stale():
-            raise AgentRuntimeStale(self.update_transaction_state())
+            raise AgentRuntimeStale(self.update_transaction_state(), source_changed=self._source_changed)
 
     # ── handshake ─────────────────────────────────────────────────────────
     def describe(self) -> dict:
         # The pin records official test coverage, not runtime capability. Each operation still checks its imports,
         # profile isolation and loaded-revision guard at the point of use.
+        stale = self.is_stale() or self._retired
         return {
             "rpc_version": SIDECAR_RPC_VERSION,
             "python": sys.executable,
@@ -334,7 +441,8 @@ class AgentRuntime:
             "pinned_version": self.pin["version"],
             "pinned_image": self.pin["image"],
             "compatible": self.loaded,
-            "stale": self.is_stale(),
+            "stale": stale,
+            "agent_source_changed": self._source_changed,
             "update_state": self.update_transaction_state(),
             "import_error": self.import_error,
         }

package/sidecar/talaria_sidecar/speed.py

@@ -0,0 +1,47 @@
+"""One route-aware speed gate for the model catalog and chat request overrides."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from urllib.parse import urlparse
+
+
+def fast_overrides(model: str, provider: str, base_url: str, tier: str) -> dict | None:
+    if tier not in ("priority", "ultrafast"):
+        return None
+    from hermes_cli import models
+
+    resolver = getattr(models, "resolve_fast_mode_overrides", None)
+    if resolver is not None:
+        if "tier" in inspect.signature(resolver).parameters:
+            return resolver(model, provider=provider, base_url=base_url, tier=tier)
+        return resolver(model, provider=provider, base_url=base_url) if tier == "priority" else None
+    # Older Agents have no resolver. Keep the former GPT-5/o-series gate, restricted to first-party routes.
+    hosts = {"openai": "api.openai.com", "openai-api": "api.openai.com", "openai-codex": "chatgpt.com"}
+    model = model.strip().lower().removeprefix("openai/")
+    host = urlparse(base_url).hostname if base_url else None
+    if tier == "priority" and provider in hosts and (not host or host == hosts[provider]) and (model.startswith("gpt-5") or re.match(r"o[0-9]", model)):
+        return {"service_tier": "priority"}
+    return None
+
+
+def supported_speed_tiers(model: str, provider: str, base_url: str) -> list[dict]:
+    tiers = []
+    for tier in ("priority", "ultrafast"):
+        override = fast_overrides(model, provider, base_url, tier)
+        if override and (tier != "ultrafast" or ultrafast_offered(model, provider, base_url)):
+            tiers.append({"id": "fast" if override.get("speed") == "fast" else tier, "service_tier": tier})
+    return [{"id": "standard", "service_tier": "default"}, *tiers] if tiers else []
+
+
+def ultrafast_offered(model: str, provider: str, base_url: str) -> bool:
+    """The Agent's account check: a Codex plan without Ultrafast accepts the tier and silently serves default."""
+    try:
+        from agent import codex_service_tiers
+    except ModuleNotFoundError as error:
+        if error.name not in ("agent", "agent.codex_service_tiers"):
+            raise
+        return True
+    offered = getattr(codex_service_tiers, "ultrafast_offered", None)
+    return offered is None or bool(offered(model, provider=provider, base_url=base_url))

package/sidecar/talaria_sidecar/startup_timing.py

@@ -0,0 +1,119 @@
+"""Bounded startup diagnostics; payloads and exception messages never enter this recorder."""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import logging
+import threading
+import time
+import uuid
+
+log = logging.getLogger("talaria_sidecar.startup_timing")
+SPANS = frozenset({"rpc_wait", "mcp_discovery", "runtime_resolution", "agent_binding", "conversation_setup"})
+OBSERVATIONS = frozenset({"rpc_receipt", "rpc_start", "conversation_entry", "first_sidecar_output", "first_visible_token", "first_visible_reasoning", "first_visible_tool", "first_visible_interim"})
+OUTCOMES = frozenset({"ok", "noop", "cache_hit", "timeout", "refused", "cancelled", "unknown", "error"})
+
+
+def outcome_for(error):
+    condition = getattr(error, "data", {}).get("condition")
+    if condition == "cancelled":
+        return "cancelled"
+    if condition in {"timeout", "sidecar_timeout"}:
+        return "timeout"
+    if condition == "sidecar_unavailable":
+        return "unknown"
+    if condition in {"session_busy", "profile_unavailable", "invalid_params"} or getattr(error, "code", None) == -32602:
+        return "refused"
+    return "error"
+
+
+def _timing_key(value):
+    # Match JavaScript's UTF-8 replacement of unpaired surrogates without rejecting the RPC.
+    text = value.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "replace")
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+class StartupTiming:
+    def __init__(self, request, *, now=None, write=None):
+        self._now = now or time.monotonic
+        self._write = write or log.info
+        self._origin = self._now()
+        self._lock = threading.RLock()
+        raw_trace = request.get("trace_id")
+        try:
+            self.trace_id = str(uuid.UUID(raw_trace)) if isinstance(raw_trace, str) else str(uuid.uuid4())
+        except (ValueError, AttributeError):
+            self.trace_id = str(uuid.uuid4())
+        self.rpc_id = request.get("id") if type(request.get("id")) is int else None
+        params = request.get("params") or {}
+        self._keys = {name + "_key": _timing_key(value) for name in ("session", "stream")
+                      if isinstance(value := params.get(name + "_id"), str)} if isinstance(params, dict) else {}
+        self.spans = {}
+        self.observations = {}
+        self._emitted = set()
+        self._ended = False
+        self.observe("rpc_receipt")
+        self.begin("rpc_wait")
+
+    def elapsed(self):
+        return max(0, (self._now() - self._origin) * 1000)
+
+    def begin(self, name):
+        with self._lock:
+            if name in SPANS and name not in self.spans and not self._ended:
+                self.spans[name] = {"start_ms": self.elapsed(), "duration_ms": None, "outcome": None}
+
+    def end(self, name, outcome="ok"):
+        with self._lock:
+            span = self.spans.get(name)
+            if span and span["duration_ms"] is None:
+                span.update(duration_ms=max(0, self.elapsed() - span["start_ms"]), outcome=outcome if outcome in OUTCOMES else "error")
+
+    @contextlib.contextmanager
+    def span(self, name):
+        self.begin(name)
+        try:
+            yield
+        except BaseException as error:
+            self.end(name, outcome_for(error))
+            raise
+        else:
+            self.end(name)
+
+    def observe(self, name):
+        with self._lock:
+            if name in OBSERVATIONS and name not in self.observations and not self._ended:
+                self.observations[name] = self.elapsed()
+                return True
+            return False
+
+    def frame(self, event, data):
+        self.observe("first_sidecar_output")
+        if not isinstance(data, dict):
+            return
+        name = {"token": "first_visible_token", "reasoning": "first_visible_reasoning", "tool": "first_visible_tool", "interim_assistant": "first_visible_interim"}.get(event)
+        if name and (event == "tool" or isinstance(data.get("text"), str) and data["text"].strip()) and self.observe(name):
+            self.emit("first_visible")
+
+    def emit(self, stage, outcome="ok"):
+        with self._lock:
+            if stage not in {"conversation_entry", "first_visible", "terminal"} or stage in self._emitted:
+                return
+            self._emitted.add(stage)
+            try:
+                self._write(json.dumps({"event": "chat_start_timing", "version": 1, "process": "sidecar", "trace_id": self.trace_id, "rpc_id": self.rpc_id,
+                                        **self._keys, "stage": stage, "outcome": outcome if outcome in OUTCOMES else "error", "elapsed_ms": self.elapsed(),
+                                        "spans": self.spans, "observations": self.observations,
+                                        "provider_boundaries": {"first_call": "unavailable", "first_chunk": "unavailable"}}, separators=(",", ":")))
+            except Exception:  # Diagnostics never affect the call.
+                pass
+
+    def finish(self, outcome):
+        with self._lock:
+            if self._ended:
+                return
+            for name in self.spans:
+                self.end(name, outcome)
+            self.emit("terminal", outcome)
+            self._ended = True