alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/subscribers/cache_writer.py

@@ -0,0 +1,347 @@
+"""CacheWriter - projects identity state into the shared shell cache file.
+
+This is the W2.2d *first pixel* glue. The existing shell-side tools -
+``scripts/alter-identity.sh`` (neofetch / waybar / prompt integration) and
+``.claude/hooks/alter-identity.sh`` (CC session context injection) - read
+live identity state from a file at ``$XDG_CACHE_HOME/alter/identity.json``.
+Before this component existed, the shell script hit the backend MCP
+endpoint directly on every cache miss; that path is slow (HTTPS round-trip)
+and fails offline.
+
+With CacheWriter registered in the daemon, every ``identity.event`` that
+looks like a state snapshot (whether from the live DO SSE stream or the
+cold-start MCP fallback) projects into the cache file with an atomic
+``tmp → rename`` write. The shell script's existing ``cache_is_fresh``
++ ``read_cache`` flow therefore transparently picks up live state as
+soon as the daemon is running - no shell script changes needed for the
+first pixel.
+
+The cache schema matches the JSON already written by the legacy
+``alter-identity.sh`` API path (see ``scripts/alter-identity.sh:242``):
+
+::
+
+    {
+        "handle":     "blake",     - bare handle, no leading ~
+        "level":      "3",         - bare numeric tier, no leading L
+        "attunement": "0.42",      - decimal 0..1 or integer percentage
+        "income":     "1.23"       - stringified USD earnings
+    }
+
+All fields are strings to match the shell script's ``jq -r`` consumers.
+When a field is missing in the source event the output key is an empty
+string (``""``) rather than omitted, so ``jq -r '.handle // ""'``
+produces consistent behaviour across cache misses.
+
+**Why strip the ``~`` and ``L`` prefixes?** The shell script prepends
+them at render time (``scripts/alter-identity.sh:264-265``):
+
+.. code-block:: bash
+
+    display_handle="${handle:+~$handle}"
+    display_level="${level:+L$level}"
+
+If we stored ``"~blake"`` / ``"L3"``, the script would render
+``"~~blake"`` / ``"LL3"``. The W2.2d *first pixel* design is to feed
+the existing shell scripts live data with **zero script changes**, so
+the CacheWriter matches the raw shape the scripts already expect.
+
+Design notes
+------------
+
+* The projection is *idempotent and lossy*. We keep only the four fields
+  the shell script cares about; anything else from the source event is
+  dropped. If a field is unchanged from the last write we still rewrite
+  the file - atomic rename is cheap and the shell script uses file mtime
+  as its TTL probe, so we want the mtime to bump on every refresh.
+* The writer is tolerant of a variety of source shapes. State sync
+  events from ``mcp_fallback`` wrap their payload under ``payload``;
+  direct DO state frames put fields at the top level. The
+  :func:`_extract_state` helper checks both.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from alter_runtime.config import cache_dir
+from alter_runtime.daemon import Component
+
+if TYPE_CHECKING:
+    from alter_runtime.subscribers.bus import EventBus
+
+__all__ = ["CacheWriter", "project_state_to_cache"]
+
+logger = logging.getLogger("alter_runtime.subscribers.cache_writer")
+
+#: Filename inside ``cache_dir()`` that the shell script reads.
+CACHE_FILENAME: str = "identity.json"
+
+#: Event kinds we recognise as carrying identity state.
+STATE_KINDS: frozenset[str] = frozenset(
+    {
+        "state_sync",
+        "alter_whoami",
+        "attunement_transition",
+        "identity_state",
+    }
+)
+
+
+class CacheWriter(Component):
+    """Writes identity state into ``$XDG_CACHE_HOME/alter/identity.json``.
+
+    Parameters
+    ----------
+    bus:
+        The shared :class:`EventBus`. Subscribes to ``identity.event``.
+    cache_path:
+        Override the cache file path. Tests inject a ``tmp_path`` value.
+    """
+
+    name = "cache_writer"
+
+    def __init__(
+        self,
+        bus: EventBus,
+        *,
+        cache_path: Path | None = None,
+    ) -> None:
+        self._bus = bus
+        self._cache_path: Path = (
+            cache_path if cache_path is not None else cache_dir() / CACHE_FILENAME
+        )
+        self._stop_event = asyncio.Event()
+        self._last_written: dict[str, str] | None = None
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        self._bus.subscribe("identity.event", self._on_event)
+        logger.info("cache_writer started cache=%s", self._cache_path)
+        try:
+            await self._stop_event.wait()
+        finally:
+            self._bus.unsubscribe("identity.event", self._on_event)
+            logger.info("cache_writer stopped")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    # ------------------------------------------------------------------
+    # Bus callback
+    # ------------------------------------------------------------------
+
+    async def _on_event(self, event: dict[str, Any]) -> None:
+        """Project a bus event to the cache file (if it's a state snapshot)."""
+        if not isinstance(event, dict):
+            return
+        kind = event.get("kind")
+        if kind not in STATE_KINDS:
+            return
+
+        projected = project_state_to_cache(event)
+        if not projected:
+            logger.debug("cache_writer ignored event kind=%s - no extractable state", kind)
+            return
+
+        try:
+            self._atomic_write(projected)
+        except OSError as exc:
+            logger.warning("cache_writer: write failed: %s - keeping previous cache", exc)
+            return
+        self._last_written = projected
+        logger.info(
+            "cache_writer wrote handle=%s level=%s attunement=%s",
+            projected.get("handle"),
+            projected.get("level"),
+            projected.get("attunement"),
+        )
+
+    # ------------------------------------------------------------------
+    # Atomic write
+    # ------------------------------------------------------------------
+
+    def _atomic_write(self, data: dict[str, str]) -> None:
+        """Write ``data`` to the cache file via a tmp-and-rename sequence."""
+        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(data, 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)
+
+    # ------------------------------------------------------------------
+    # Test introspection
+    # ------------------------------------------------------------------
+
+    @property
+    def cache_path(self) -> Path:
+        return self._cache_path
+
+    @property
+    def last_written(self) -> dict[str, str] | None:
+        return self._last_written
+
+
+# ---------------------------------------------------------------------------
+# Pure projection helper
+# ---------------------------------------------------------------------------
+
+
+def project_state_to_cache(event: dict[str, Any]) -> dict[str, str]:
+    """Project a bus event dict into the shell-script cache schema.
+
+    Returns an empty dict if the event doesn't carry any recognisable
+    identity state. The result always contains the four fields the shell
+    script reads (``handle``, ``level``, ``attunement``, ``income``) with
+    empty strings filling any missing values - this keeps ``jq -r`` consumers
+    happy across variant source shapes.
+
+    The function is pure (no filesystem access, no bus calls) so it can be
+    unit-tested independently of the component lifecycle.
+    """
+
+    # State can live at the top level (direct identity events from the DO)
+    # or nested under ``payload`` (synthetic state_sync events from the MCP
+    # fallback subscriber). Try both.
+    sources: list[dict[str, Any]] = []
+    payload = event.get("payload")
+    if isinstance(payload, dict):
+        sources.append(payload)
+    sources.append(event)
+
+    def pick(field: str) -> str:
+        for src in sources:
+            value = src.get(field)
+            if value is not None and value != "":
+                return _stringify(value)
+        return ""
+
+    handle = _strip_tilde(pick("handle"))
+    # ``level`` - accept the string label "L3" or an integer engagement_level
+    level = _normalise_level(pick("level"))
+    if not level:
+        engagement = ""
+        for src in sources:
+            engagement = src.get("engagement_level") or engagement
+        if engagement:
+            level = _normalise_level(engagement)
+    if not level:
+        tier = ""
+        for src in sources:
+            tier = src.get("consent_tier") or tier
+        if tier:
+            level = _normalise_level(tier)
+
+    attunement = pick("attunement")
+    if not attunement:
+        for src in sources:
+            value = src.get("attunement_score")
+            if value is not None and value != "":
+                attunement = _stringify(value)
+                break
+
+    income = pick("income")
+    if not income:
+        for src in sources:
+            value = src.get("total_earnings") or src.get("identity_income")
+            if value is not None and value != "":
+                income = _stringify(value)
+                break
+
+    # Empty projection - nothing useful to cache.
+    if not any((handle, level, attunement, income)):
+        return {}
+
+    return {
+        "handle": handle,
+        "level": level,
+        "attunement": attunement,
+        "income": income,
+    }
+
+
+def _stringify(value: Any) -> str:
+    """Convert a Python value into the string form the shell script expects."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    # dicts / lists don't fit the shell schema - coerce to JSON and let the
+    # shell script decide whether to render them.
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def _normalise_level(value: Any) -> str:
+    """Normalise any engagement-level representation to ``"1".."4"``.
+
+    Accepts integers (``1``), strings (``"L3"`` or ``"3"``), or labels
+    (``"augmented"``). Returns the bare numeric tier as a string so the
+    cache matches the raw shape ``scripts/alter-identity.sh`` already
+    expects (the shell script prepends ``L`` at render time). Unknown
+    inputs become an empty string.
+    """
+    if isinstance(value, bool):
+        return ""
+    if isinstance(value, int):
+        if 1 <= value <= 4:
+            return str(value)
+        return ""
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return ""
+        # "L1".."L4"
+        if len(stripped) == 2 and stripped[0] in ("L", "l") and stripped[1].isdigit():
+            tier = int(stripped[1])
+            if 1 <= tier <= 4:
+                return str(tier)
+        # Raw numeric "1".."4"
+        try:
+            tier = int(stripped)
+        except ValueError:
+            # Known label fallbacks - mirrors the alter-identity types file.
+            label_map = {
+                "explorer": "1",
+                "learner": "2",
+                "augmented": "3",
+                "deployed": "4",
+            }
+            return label_map.get(stripped.lower(), "")
+        if 1 <= tier <= 4:
+            return str(tier)
+    return ""
+
+
+def _strip_tilde(value: str) -> str:
+    """Strip a single leading ``~`` from a handle, if present.
+
+    The shell script prepends ``~`` at render time, so storing the bare
+    handle keeps ``scripts/alter-identity.sh`` rendering correctly without
+    any shell changes (see the module docstring for the full rationale).
+    """
+    if value.startswith("~"):
+        return value[1:]
+    return value

alter_runtime/subscribers/ceremony_echo.py

@@ -0,0 +1,290 @@
+"""CeremonyEchoWriter - projects recognition events into a 72h echo state.
+
+Wave 2 of *D-CUST-1* (proposed; ratification pending). The CeremonyEchoWriter
+is a long-lived :class:`alter_runtime.daemon.Component` that sits next to
+:class:`InboxWriter` on the SSE bus. Where the InboxWriter projects the full
+inbox JSONL, the CeremonyEchoWriter watches for recognition-class events and
+maintains a tiny single-file state - the most-recent recognition event, its
+declared kind, and the absolute timestamp at which the echo expires (72 h
+after the event).
+
+A consumer (``alter room`` in alter-cli, or any future shell-greeting
+renderer) reads ``ceremony-echo.json`` from the runtime data directory at
+each invocation and renders an echo line iff the current time is before the
+expiry. The user cannot author the echo, cannot extend it, cannot dismiss it
+early - "the house noticed" (brief §3 surface 21). The echo is observation,
+not affordance.
+
+Filtered content_types
+   * ``x-alter-recognition`` - the canonical recognition event
+   * ``x-alter-ceremony``    - broader ceremony class (Seat, Mirror, Discovery,
+                               Accord) that should also surface a 72 h echo
+   Both are members of ``ALLOWED_CONTENT_TYPES`` in
+   ``backend/app/mcp/tools/messaging.py``.
+
+The component is designed to swallow and log all errors so a single
+malformed frame, full disk, or transient SSE disconnect cannot crash the
+daemon supervisor. Like InboxWriter, the supervisor will restart on
+:meth:`run` exceptions but :meth:`handle_event` only ever logs and returns.
+
+Refs:
+   * proposed-D-CUST-1 (alter-internal #140) - surface 21 (ceremony echo)
+   * embedded-messenger/05-design-synthesis.md - content_type taxonomy
+   * .claude/handovers/2026-04-24-alter-myspace-customisation-m2-and-c-spike.md
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import tempfile
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from alter_runtime.config import DaemonConfig, data_dir
+from alter_runtime.daemon import Component
+from alter_runtime.subscribers.sse import SSEFrame
+
+if TYPE_CHECKING:
+    from alter_runtime.config import Session
+
+__all__ = [
+    "CEREMONY_ECHO_FILENAME",
+    "DEFAULT_ECHO_DURATION",
+    "RECOGNITION_CONTENT_TYPES",
+    "CeremonyEchoWriter",
+]
+
+logger = logging.getLogger("alter_runtime.subscribers.ceremony_echo")
+
+#: Filename for the ceremony-echo state (within ``data_dir()``).
+CEREMONY_ECHO_FILENAME: str = "ceremony-echo.json"
+
+#: How long an echo remains visible after the event arrives. The brief
+#: locks this at 72 h - long enough to catch the user across multiple
+#: shell sessions and a working week's natural cadence, short enough that
+#: the echo doesn't become wallpaper.
+DEFAULT_ECHO_DURATION: timedelta = timedelta(hours=72)
+
+#: Content_type values that produce a ceremony echo. Both are in
+#: ``backend/app/mcp/tools/messaging.py``'s ``ALLOWED_CONTENT_TYPES``
+#: frozenset; if that taxonomy expands, this set should be revisited.
+RECOGNITION_CONTENT_TYPES: frozenset[str] = frozenset(
+    {
+        "x-alter-recognition",
+        "x-alter-ceremony",
+    }
+)
+
+
+class CeremonyEchoWriter(Component):
+    """Tails the per-handle SSE stream and persists the most-recent
+    recognition-class event to ``ceremony-echo.json`` for shell-greeting
+    consumers.
+
+    Parameters
+    ----------
+    config:
+        Loaded :class:`DaemonConfig`. Reserved for future use; not consulted
+        in the M2 implementation.
+    session:
+        Authenticated alter-cli session. Used for log context only - the
+        bus delivers the per-handle frames, the writer does not need to
+        construct an SSE URL itself.
+    echo_path:
+        Override the state file path. Tests use this to redirect writes
+        to a ``tmp_path`` fixture without touching ``$HOME``.
+    echo_duration:
+        Override the echo-visible window. Tests pass a short duration to
+        exercise the expiry path without wall-clock waits.
+    """
+
+    name = "ceremony_echo"
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        session: Session,
+        *,
+        echo_path: Path | None = None,
+        echo_duration: timedelta = DEFAULT_ECHO_DURATION,
+    ) -> None:
+        self._config = config
+        self._session = session
+        self._echo_duration = echo_duration
+
+        self._echo_path: Path = (
+            echo_path if echo_path is not None else data_dir() / CEREMONY_ECHO_FILENAME
+        )
+
+        self._lock = asyncio.Lock()
+        self._shutdown_event = asyncio.Event()
+
+    # ------------------------------------------------------------------
+    # Component lifecycle
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        """Long-lived idle loop. The bus is the actual ingress path -
+        :meth:`handle_raw_frame` is the seam the supervisor wires into
+        ``identity.frame``. We just block on shutdown so the supervisor
+        can register us as a peer of InboxWriter without opening any
+        sockets of our own.
+        """
+        logger.info(
+            "ceremony_echo started handle=%s echo_path=%s",
+            self._session.handle,
+            self._echo_path,
+        )
+        try:
+            await self._shutdown_event.wait()
+        except asyncio.CancelledError:
+            raise
+        finally:
+            logger.info("ceremony_echo stopped handle=%s", self._session.handle)
+
+    async def stop(self) -> None:
+        """Cooperative shutdown - release the run loop."""
+        self._shutdown_event.set()
+
+    # ------------------------------------------------------------------
+    # Frame ingest - public surface for the SSE bus and tests
+    # ------------------------------------------------------------------
+
+    async def handle_raw_frame(self, frame: SSEFrame) -> None:
+        """Parse an SSE frame and dispatch to :meth:`handle_event`.
+
+        Errors are logged and swallowed - the supervisor never sees a
+        write failure (per the project convention "swallow and continue").
+        """
+        try:
+            payload = frame.json
+        except (ValueError, json.JSONDecodeError) as exc:
+            logger.warning("ceremony_echo: malformed SSE frame body: %s", exc)
+            return
+        if not isinstance(payload, dict):
+            logger.warning("ceremony_echo: SSE frame payload is not a dict: %r", type(payload))
+            return
+        await self.handle_event(payload)
+
+    async def handle_event(self, event: dict[str, Any]) -> None:
+        """Project a single parsed IdentityEvent dict.
+
+        This is the unit-test seam - the test suite calls this directly
+        with synthesised dicts to avoid having to drive a real SSE socket.
+
+        We accept ``alter_message`` events whose payload's ``content_type``
+        is in :data:`RECOGNITION_CONTENT_TYPES`. Other kinds and other
+        content_types are silently dropped (the InboxWriter handles the
+        full inbox projection - we only care about the echo subset).
+        """
+        # ---- 1. Filter on kind ---------------------------------------
+        if event.get("kind") != "alter_message":
+            return
+
+        # The DO emits the IdentityEvent envelope with the message
+        # payload either at the top level or nested under ``payload``.
+        # Tolerate both shapes during the wire-contract rollout - same
+        # tolerance pattern as InboxWriter.
+        body = event.get("payload") if isinstance(event.get("payload"), dict) else event
+
+        content_type = body.get("content_type")
+        if content_type not in RECOGNITION_CONTENT_TYPES:
+            return
+
+        # ---- 2. Extract the echo-state fields ------------------------
+        sender = body.get("sender_handle") or body.get("sender")
+        body_md = body.get("body_md")
+        message_id = event.get("id") or body.get("id")
+        received_at = (
+            event.get("timestamp") or body.get("sent_at") or datetime.now(timezone.utc).isoformat()
+        )
+
+        if not sender:
+            logger.warning(
+                "ceremony_echo: %s frame missing sender - dropping (id=%r)",
+                content_type,
+                message_id,
+            )
+            return
+
+        # ---- 3. Compute expiry --------------------------------------
+        # Anchor the expiry on the event's own timestamp where possible
+        # so a delayed delivery does not extend the user-visible window.
+        try:
+            event_time = datetime.fromisoformat(received_at.replace("Z", "+00:00"))
+        except (ValueError, AttributeError):
+            event_time = datetime.now(timezone.utc)
+        expires_at = (event_time + self._echo_duration).isoformat()
+
+        # ---- 4. Persist atomically ----------------------------------
+        state = {
+            "schema_version": 1,
+            "last_recognition": {
+                "sender": sender,
+                "kind": content_type,
+                "body_md": str(body_md) if body_md is not None else "",
+                "received_at": received_at,
+            },
+            "expires_at": expires_at,
+        }
+
+        async with self._lock:
+            try:
+                self._write_state(state)
+            except OSError as exc:
+                logger.warning(
+                    "ceremony_echo: state write failed: %s - dropping event",
+                    exc,
+                )
+                return
+
+        logger.info(
+            "ceremony_echo: persisted %s from %s expires_at=%s",
+            content_type,
+            sender,
+            expires_at,
+        )
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def _write_state(self, state: dict[str, Any]) -> None:
+        """Atomic-rename a JSON state file with mode 0o600.
+
+        The temp file is created in the same directory as the target so
+        the rename is atomic (cross-device renames are not). Parent
+        directory is created with mode 0o700 if absent.
+        """
+        target = self._echo_path
+        target.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=str(target.parent),
+            prefix=f".{target.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as fh:
+            tmp_path = Path(fh.name)
+            try:
+                json.dump(state, fh, separators=(",", ":"), ensure_ascii=False)
+                fh.flush()
+                os.fsync(fh.fileno())
+            except Exception:
+                with contextlib.suppress(OSError):
+                    tmp_path.unlink()
+                raise
+
+        try:
+            os.chmod(tmp_path, 0o600)
+            os.replace(tmp_path, target)
+        except OSError:
+            with contextlib.suppress(OSError):
+                tmp_path.unlink()
+            raise