alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/subscribers/session_presence.py

@@ -0,0 +1,467 @@
+"""SessionPresenceWriter - projects cross-host CC presence into the shared cache.
+
+The Worker holds a /queries/presence projection that aggregates session_presence
+intent rows across hosts (the alter monorepo's ``.claude/hooks/cc-broadcast.sh``
+emits these as start/heartbeat/stop). This subscriber polls the projection on
+a configurable cadence and writes the result to
+``~/.local/share/org-alter/state/sessions.json``. The bash awareness hook
+(``.claude/hooks/cc-awareness.sh`` in the alter monorepo) merges that cache
+with same-host ``/dev/shm`` sibling files to give every CC session a unified
+view of all parallel sessions across hosts.
+
+D-RT1 (local sovereign daemon), D-RT9 (graceful fallback). Designed to be the
+canonical L3 writer the Phase B handover called out - the alternative was a
+standalone systemd timer that would have been deprecated as soon as
+alter-runtime caught up. Landing it here from the start avoids the churn.
+
+Auth flow per cycle:
+
+1. **Cap mint.** ``POST {api}/api/v1/org-alter/caps`` body
+   ``{"scopes":["alter_org.read"], "residual_seconds": 240}`` with
+   ``Authorization: Bearer <session.jwt>``. Returns
+   ``{capability, expires_at, jti, sub, aud_recipient, scopes, uses?, mode?}``.
+2. **Query.** ``GET {worker}/orgs/{slug}/queries/presence`` with
+   ``Authorization: Bearer <cap>`` and ``X-Cap-Use-Index: <index>``.
+
+Caps are kept in-memory with a 30s lead refresh; bounded multi-use caps
+(proposed-D-CAP-1) are honoured. The reader does not subscribe to the bus -
+awareness is a file-mediated handoff to bash hooks, and the bus would add
+nothing useful.
+
+Cache file shape mirrors the Worker's PresenceResponse so the bash hook's
+``jq`` path stays simple::
+
+    {
+        "presence": [
+            {"actor": "~blake", "tool": "cc", "session_id": "abc...",
+             "started_at": "...", "last_seen": "...", "state": "heartbeat"},
+            ...
+        ],
+        "window_ms": 1800000,
+        "now": "2026-05-07T...",
+        "writer": "alter-runtime",
+        "writer_at": "2026-05-07T..."
+    }
+
+Failure modes:
+
+* No session.json - log once, idle until the next poll. The daemon never
+  manages login.
+* Cap-mint reject (4xx, 503) - exponential back-off up to MAX_POLL_BACKOFF.
+* Worker reject - exponential back-off; cache file is left as-is so stale
+  cross-host data keeps rendering for the rolling-window grace period.
+* Network error - exponential back-off.
+
+The subscriber never raises out of :meth:`run` - the supervisor's
+exponential-backoff restart machinery is a last-resort safety net only.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from alter_runtime.config import DaemonConfig
+from alter_runtime.daemon import Component
+from alter_runtime.http_auth import backend_default_headers
+from alter_runtime.subscribers.do_sse import _build_tls_context
+
+if TYPE_CHECKING:
+    from alter_runtime.config import Session
+
+__all__ = ["SessionPresenceWriter", "session_presence_cache_path"]
+
+logger = logging.getLogger("alter_runtime.subscribers.session_presence")
+
+#: Cap scope required for /queries/presence reads.
+READ_SCOPE: str = "alter_org.read"
+
+#: Default residual-lifetime ceiling at mint time. The backend caps this at
+#: 300s for read scopes and the cache refreshes 30s before expiry, so the
+#: effective re-mint cadence is ~210s.
+DEFAULT_CAP_RESIDUAL_SECONDS: int = 240
+
+#: Refresh leeway - re-mint when expiry is closer than this.
+CAP_REFRESH_LEAD_SECONDS: float = 30.0
+
+#: Upper bound on the subscriber's exponential backoff when either cap-mint
+#: or the Worker query is failing.
+MAX_POLL_BACKOFF_SECONDS: float = 60.0
+
+#: Filename under the org-alter state directory that the bash awareness hook
+#: reads. Co-ordinated with .claude/hooks/cc-awareness.sh in the alter
+#: monorepo - changing this requires a paired edit there.
+CACHE_FILENAME: str = "sessions.json"
+
+
+def session_presence_cache_path() -> Path:
+    """Return the canonical sessions.json cache path.
+
+    Honours ``ORG_ALTER_STATE_DIR`` for parity with mcp-alter-collective.
+    """
+    override = os.environ.get("ORG_ALTER_STATE_DIR")
+    if override:
+        base = Path(override).expanduser()
+    else:
+        base = Path.home() / ".local" / "share" / "org-alter"
+    return base / "state" / CACHE_FILENAME
+
+
+# ---------------------------------------------------------------------------
+# In-memory cap cache
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _CachedCap:
+    capability: str
+    expires_at_unix: float
+    uses_available: int
+    use_counter: int
+
+    def is_fresh(self, now: float) -> bool:
+        return self.expires_at_unix - now > CAP_REFRESH_LEAD_SECONDS
+
+    def has_uses(self) -> bool:
+        return self.use_counter < self.uses_available
+
+    def take_use(self) -> int:
+        index = self.use_counter
+        self.use_counter += 1
+        return index
+
+
+# ---------------------------------------------------------------------------
+# Subscriber state - mirrors McpFallbackSubscriber's _FallbackState pattern
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _PresenceState:
+    """Internal state (exposed for tests)."""
+
+    poll_count: int = 0
+    write_count: int = 0
+    backoff: float = 0.0
+    last_response_at: float = 0.0
+    history: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Component
+# ---------------------------------------------------------------------------
+
+
+class SessionPresenceWriter(Component):
+    """Polls the org-alter presence projection and writes a local cache.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig`. Reads the new
+        ``session_presence_*`` and ``org_alter_*`` fields.
+    session:
+        Authenticated alter-cli :class:`Session`. Used for the bearer JWT
+        when minting caps. Without a session the component idles silently
+        and re-checks on every poll cycle.
+    cache_path:
+        Override the cache file path. Tests inject ``tmp_path``.
+    http_client:
+        Optional ``httpx.AsyncClient`` override for tests.
+    """
+
+    name = "session_presence"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        session: Session | None,
+        *,
+        cache_path: Path | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._config = config
+        self._session = session
+        self._cache_path: Path = (
+            cache_path if cache_path is not None else session_presence_cache_path()
+        )
+        self._http_client = http_client
+        self._owns_client = http_client is None
+        self._stop_event = asyncio.Event()
+        self._state = _PresenceState()
+        self._cap: _CachedCap | None = None
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        if not self._config.session_presence_enabled:
+            logger.info("session_presence disabled by config - idle")
+            await self._stop_event.wait()
+            return
+
+        logger.info(
+            "session_presence starting cache=%s interval=%.1fs",
+            self._cache_path,
+            self._config.session_presence_poll_interval_seconds,
+        )
+
+        client = self._http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(connect=5.0, read=10.0, write=5.0, pool=5.0),
+            verify=_build_tls_context(),
+            # Backend default headers — CF Access service-token bundle
+            # (D-SUBSTRATE-UNIFIED-1 §2.3 Option A) merged with the
+            # canonical ``X-Alter-Client-*`` identity headers
+            # (D-MIN-VERSION-FLOOR-1 §3) so the server-side floor
+            # middleware can identify the daemon.
+            headers=backend_default_headers(),
+        )
+
+        try:
+            while not self._stop_event.is_set():
+                await self._poll_once_safe(client)
+                await self._sleep_interruptible(self._config.session_presence_poll_interval_seconds)
+        finally:
+            if self._owns_client:
+                with contextlib.suppress(Exception):
+                    await client.aclose()
+            logger.info("session_presence stopped")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # Poll loop
+    # ------------------------------------------------------------------
+
+    async def _poll_once_safe(self, client: httpx.AsyncClient) -> None:
+        """Wrap _poll_once with backoff + last-resort exception swallowing.
+
+        The supervisor restarts on bare exceptions, so we'd rather log and
+        continue than tear down the component for a transient blip.
+        """
+        try:
+            await self._poll_once(client)
+            self._state.backoff = 0.0
+        except asyncio.CancelledError:
+            raise
+        except _SessionMissing:
+            # No alter session - log once, sleep through cycle.
+            if "no_session" not in self._state.history:
+                self._state.history.append("no_session")
+                logger.info(
+                    "session_presence: no alter session - run `alter login`. "
+                    "Will retry on the next poll silently."
+                )
+            self._state.backoff = max(self._state.backoff, 5.0)
+        except (httpx.HTTPError, _CapMintError, _WorkerQueryError) as exc:
+            self._state.backoff = min(
+                max(self._state.backoff * 2 if self._state.backoff else 2.0, 2.0),
+                MAX_POLL_BACKOFF_SECONDS,
+            )
+            logger.warning(
+                "session_presence poll failed: %s - backoff %.1fs",
+                exc,
+                self._state.backoff,
+            )
+        except Exception as exc:  # noqa: BLE001 - last-resort safety net
+            logger.exception("session_presence poll unexpected error: %s", exc)
+            self._state.backoff = MAX_POLL_BACKOFF_SECONDS
+
+    async def _poll_once(self, client: httpx.AsyncClient) -> None:
+        """Mint cap if needed, GET presence, write cache."""
+        session = self._session
+        if session is None:
+            raise _SessionMissing()
+
+        cap, use_index = await self._get_cap(client, session)
+        response = await self._fetch_presence(client, cap, use_index)
+        self._write_cache(response)
+        self._state.poll_count += 1
+        self._state.write_count += 1
+        self._state.last_response_at = time.time()
+
+    # ------------------------------------------------------------------
+    # Cap minting
+    # ------------------------------------------------------------------
+
+    async def _get_cap(
+        self,
+        client: httpx.AsyncClient,
+        session: Session,
+    ) -> tuple[str, int]:
+        """Return (capability, use_index). Mints a new cap if cache is stale."""
+        now = time.time()
+        if self._cap is not None and self._cap.is_fresh(now) and self._cap.has_uses():
+            return self._cap.capability, self._cap.take_use()
+
+        url = f"{session.api.rstrip('/')}/api/v1/org-alter/caps"
+        body = {
+            "scopes": [READ_SCOPE],
+            "residual_seconds": DEFAULT_CAP_RESIDUAL_SECONDS,
+        }
+        headers = {
+            "Authorization": f"Bearer {session.jwt}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        response = await client.post(url, json=body, headers=headers)
+        if response.status_code == 401 or response.status_code == 403:
+            raise _CapMintError(
+                f"cap-mint rejected (HTTP {response.status_code}): {response.text[:200]}"
+            )
+        response.raise_for_status()
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise _CapMintError("cap-mint returned non-JSON body") from exc
+
+        if not isinstance(data, dict):
+            raise _CapMintError("cap-mint returned non-object body")
+
+        capability = data.get("capability")
+        expires_at = data.get("expires_at")
+        if not isinstance(capability, str) or not capability:
+            raise _CapMintError("cap-mint response missing capability")
+        if not isinstance(expires_at, str) or not expires_at:
+            raise _CapMintError("cap-mint response missing expires_at")
+
+        try:
+            from datetime import datetime
+
+            expires_at_unix = datetime.fromisoformat(expires_at.replace("Z", "+00:00")).timestamp()
+        except ValueError as exc:
+            raise _CapMintError(f"cap-mint returned non-ISO expires_at: {expires_at}") from exc
+
+        # Worker rejects mode=stream caps client-side via the same gate as
+        # mcp-alter-collective - surface it as a clean error here too.
+        mode = data.get("mode")
+        if mode is not None and mode != "office":
+            raise _CapMintError(f"cap-mint returned unsupported mode: {mode!r}")
+
+        uses_raw = data.get("uses")
+        uses_available = uses_raw if isinstance(uses_raw, int) and uses_raw >= 1 else 1
+
+        cap = _CachedCap(
+            capability=capability,
+            expires_at_unix=expires_at_unix,
+            uses_available=uses_available,
+            use_counter=1,
+        )
+        self._cap = cap
+        return capability, 0
+
+    # ------------------------------------------------------------------
+    # Worker query
+    # ------------------------------------------------------------------
+
+    async def _fetch_presence(
+        self,
+        client: httpx.AsyncClient,
+        capability: str,
+        use_index: int,
+    ) -> dict[str, Any]:
+        """GET /queries/presence with the cap. Returns parsed JSON dict."""
+        endpoint = self._config.org_alter_presence_endpoint
+        headers = {
+            "Authorization": f"Bearer {capability}",
+            "Accept": "application/json",
+            "X-Cap-Use-Index": str(use_index),
+        }
+        response = await client.get(endpoint, headers=headers)
+        if response.status_code == 401 or response.status_code == 403:
+            # Cap was rejected - drop it so the next cycle re-mints.
+            self._cap = None
+            raise _WorkerQueryError(
+                f"presence query auth rejected (HTTP {response.status_code}): {response.text[:200]}"
+            )
+        response.raise_for_status()
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise _WorkerQueryError("presence query returned non-JSON body") from exc
+
+        if not isinstance(data, dict):
+            raise _WorkerQueryError("presence query returned non-object body")
+        return data
+
+    # ------------------------------------------------------------------
+    # Atomic write
+    # ------------------------------------------------------------------
+
+    def _write_cache(self, worker_response: dict[str, Any]) -> None:
+        """Augment the Worker payload with writer metadata, atomic-write to disk."""
+        from datetime import datetime, timezone
+
+        envelope = dict(worker_response)
+        envelope["writer"] = "alter-runtime"
+        envelope["writer_at"] = datetime.now(tz=timezone.utc).isoformat()
+
+        self._cache_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        tmp_path = self._cache_path.with_suffix(self._cache_path.suffix + ".tmp")
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        fd = os.open(tmp_path, flags, 0o600)
+        try:
+            with contextlib.suppress(OSError):
+                os.fchmod(fd, 0o600)
+            payload = json.dumps(envelope, separators=(",", ":"), ensure_ascii=False)
+            os.write(fd, payload.encode("utf-8"))
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(tmp_path, self._cache_path)
+        with contextlib.suppress(OSError):
+            os.chmod(self._cache_path, 0o600)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    async def _sleep_interruptible(self, seconds: float) -> None:
+        """Sleep ``seconds`` or until stop is set, whichever comes first."""
+        effective = max(seconds, self._state.backoff)
+        if effective <= 0:
+            return
+        try:
+            await asyncio.wait_for(self._stop_event.wait(), timeout=effective)
+        except (TimeoutError, asyncio.TimeoutError):
+            return
+
+    @property
+    def state(self) -> _PresenceState:
+        """Current state (used by tests)."""
+        return self._state
+
+    @property
+    def cache_path(self) -> Path:
+        return self._cache_path
+
+
+# ---------------------------------------------------------------------------
+# Internal exception types - kept private so callers can't grep for them
+# outside this module
+# ---------------------------------------------------------------------------
+
+
+class _SessionMissing(Exception):
+    """Raised when the alter-cli session is absent."""
+
+
+class _CapMintError(Exception):
+    """Raised when /api/v1/org-alter/caps refuses or returns malformed body."""
+
+
+class _WorkerQueryError(Exception):
+    """Raised when /queries/presence refuses or returns malformed body."""

alter_runtime/subscribers/sse.py

@@ -0,0 +1,125 @@
+"""Minimal Server-Sent Events parser for the alter-runtime daemon.
+
+This is a deliberately self-contained, stdlib-only port of
+``backend/app/services/identity_events/subscriber.py`` (lines ~128-192). The
+runtime daemon ships to user devices and must not import from the backend
+package (different runtime, different deploy boundary), so we copy the parser
+verbatim rather than vendoring the backend module.
+
+The parser is intentionally minimal: it understands ``event``, ``data`` and
+``id`` fields per the SSE spec, joins multi-line ``data:`` payloads with
+newlines, and silently drops keepalive comments (lines starting with ``:``).
+Unknown fields (``retry``, etc.) are ignored. The wire contract is locked in
+``cloudflare/workers/handle-alter/src/sse.ts`` and the only producer on the
+other side of the socket is ALTER's own DO, so we do not bother handling
+arbitrary SSE producer quirks.
+
+Usage::
+
+    buffer = ""
+    async for chunk in stream.aiter_text():
+        buffer += chunk
+        frames, buffer = parse_sse_frames(buffer)
+        for frame in frames:
+            ...
+
+The returned ``remainder`` is the partial trailing frame (if any) and must be
+prepended to the next chunk so that frames split across read boundaries are
+reassembled correctly.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+__all__ = ["SSEFrame", "parse_sse_frames"]
+
+
+@dataclass
+class SSEFrame:
+    """A single parsed Server-Sent Events frame."""
+
+    event: str
+    """Value of the ``event:`` field, or ``"message"`` per the spec default."""
+
+    data: str
+    """Concatenated ``data:`` values (newline-joined)."""
+
+    id: str | None = None
+    """Value of the ``id:`` field, if supplied. Used as the SSE
+    ``Last-Event-ID`` header on reconnect."""
+
+    @property
+    def json(self) -> dict:
+        """Parse ``data`` as JSON. Raises ``ValueError`` if malformed."""
+        return json.loads(self.data)
+
+
+def parse_sse_frames(buffer: str) -> tuple[list[SSEFrame], str]:
+    """Parse SSE frames out of a raw text buffer.
+
+    Returns ``(frames, remainder)`` where ``remainder`` is the trailing
+    partial frame (if any) that should be prepended to the next chunk.
+    Comments (lines starting with ``:``) and blank-only buffers are
+    tolerated and simply produce no frames.
+    """
+
+    frames: list[SSEFrame] = []
+
+    # Frames are separated by a blank line. A trailing blank line may be
+    # absent if the chunk ends mid-frame; that portion is returned as the
+    # remainder.
+    parts = buffer.split("\n\n")
+    remainder = parts[-1]
+    complete_parts = parts[:-1]
+
+    for raw in complete_parts:
+        frame = _parse_single_frame(raw)
+        if frame is not None:
+            frames.append(frame)
+
+    return frames, remainder
+
+
+def _parse_single_frame(raw: str) -> SSEFrame | None:
+    """Parse a single (complete) SSE frame.
+
+    Returns ``None`` if the frame is a pure comment or has no data.
+    """
+
+    event_name = "message"
+    data_lines: list[str] = []
+    event_id: str | None = None
+
+    for line in raw.split("\n"):
+        if not line:
+            continue
+        if line.startswith(":"):
+            # Comment - silently ignored (keepalive).
+            continue
+        if ":" not in line:
+            field_name = line
+            value = ""
+        else:
+            field_name, _, value = line.partition(":")
+            # Per SSE spec, a single leading space after ':' is ignored.
+            if value.startswith(" "):
+                value = value[1:]
+
+        if field_name == "event":
+            event_name = value
+        elif field_name == "data":
+            data_lines.append(value)
+        elif field_name == "id":
+            event_id = value
+        # ``retry:`` and unknown fields are ignored.
+
+    if not data_lines:
+        return None
+
+    return SSEFrame(
+        event=event_name,
+        data="\n".join(data_lines),
+        id=event_id,
+    )