alter-runtime 0.3.0__py3-none-any.whl

alter_runtime/daemon.py

@@ -0,0 +1,518 @@
+"""Asyncio supervisor for the alter-runtime daemon.
+
+This is the Wave 1 stream 1c skeleton: it wires the supervisor loop, signal
+handling, and the configuration loader but leaves the actual subscribers
+(L1 DO SSE client and MCP fallback), socket servers, and adapters as
+Wave 2 expansions. Running ``alter-runtime daemon`` will cleanly start, log,
+and shut down without needing those components.
+
+Architecture:
+
+                 ┌──────────────────────────────────────┐
+                 │        alter_runtime.daemon          │
+                 │         Supervisor (asyncio)         │
+                 └──────┬───────────────┬───────────────┘
+                        │               │
+            ┌───────────▼──┐   ┌────────▼──────────┐
+            │ subscribers  │   │  sockets / dbus   │
+            │  do_sse      │   │  unix / dbus      │
+            │  mcp_fallback│   │                   │
+            └──────────────┘   └───────────────────┘
+                        │               │
+                    Event bus (in-process asyncio.Queue)
+                        │
+                ┌───────▼────────┐
+                │  adapters      │
+                │  git_watcher   │
+                │  cc_hook_bridge│
+                └────────────────┘
+
+Each component registers with the supervisor via ``Supervisor.register(...)``.
+The supervisor runs them as long-lived tasks and restarts them on failure
+with exponential backoff. On SIGTERM/SIGINT, the supervisor cancels all
+tasks and awaits clean shutdown.
+
+D-RT1 (local sovereign daemon), D-RT2 (three transports in parallel),
+D-RT9 (graceful fallback).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import sys
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from alter_runtime.config import DaemonConfig, ensure_directories, load_config, load_session
+
+if TYPE_CHECKING:
+    from alter_runtime.config import Session
+
+__all__ = ["Component", "Supervisor", "run_daemon"]
+
+logger = logging.getLogger("alter_runtime.daemon")
+
+
+# ---------------------------------------------------------------------------
+# Component ABC - everything the supervisor runs implements this
+# ---------------------------------------------------------------------------
+
+
+class Component(ABC):
+    """A long-running component managed by the supervisor.
+
+    Subclasses implement :meth:`run` as an async method that blocks until
+    the component should exit. The supervisor cancels the task on shutdown
+    and awaits cancellation propagation.
+    """
+
+    #: Human-readable name used in logs
+    name: str = "component"
+
+    @abstractmethod
+    async def run(self) -> None:
+        """Main event loop for the component."""
+
+    async def stop(self) -> None:
+        """Optional graceful shutdown hook.
+
+        Called before task cancellation. Components can use this to drain
+        pending work (flush queues, close sockets) before being cancelled.
+        """
+
+
+@dataclass
+class _ManagedTask:
+    """Bookkeeping for a registered component."""
+
+    component: Component
+    task: asyncio.Task[None] | None = None
+    restart_count: int = 0
+    restart_at: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Supervisor
+# ---------------------------------------------------------------------------
+
+
+class Supervisor:
+    """Supervises a set of Components with restart-on-failure semantics."""
+
+    #: Base backoff in seconds; exponential to a maximum
+    BASE_BACKOFF_SECONDS: float = 1.0
+    MAX_BACKOFF_SECONDS: float = 60.0
+
+    def __init__(self, config: DaemonConfig) -> None:
+        self.config = config
+        self._managed: list[_ManagedTask] = []
+        self._stopping = asyncio.Event()
+        self._on_stop_callbacks: list[Callable[[], Awaitable[None]]] = []
+
+    def register(self, component: Component) -> None:
+        """Register a component to be managed.
+
+        May only be called before :meth:`run` starts. After startup, use
+        ``add_component`` for dynamic registration.
+        """
+        self._managed.append(_ManagedTask(component=component))
+
+    def on_stop(self, callback: Callable[[], Awaitable[None]]) -> None:
+        """Register a callback to run during shutdown.
+
+        Callbacks run sequentially after component tasks are cancelled.
+        """
+        self._on_stop_callbacks.append(callback)
+
+    async def run(self) -> None:
+        """Start the supervisor and block until shutdown is requested."""
+        logger.info(
+            "alter-runtime daemon starting pid=%d components=%d",
+            _getpid(),
+            len(self._managed),
+        )
+
+        if not self._managed:
+            # Wave 1 skeleton: no components wired yet. We still start the
+            # supervisor so that operators can verify `alter-runtime daemon`
+            # works end-to-end - it just idles until signalled.
+            logger.warning(
+                "supervisor started with zero registered components "
+                "(Wave 1 skeleton - subscribers, sockets, adapters come in Wave 2)"
+            )
+
+        # Install signal handlers for clean shutdown
+        self._install_signal_handlers()
+
+        # Launch each component
+        for managed in self._managed:
+            managed.task = asyncio.create_task(
+                self._supervise(managed),
+                name=f"alter-{managed.component.name}",
+            )
+
+        # Block until stop is requested
+        await self._stopping.wait()
+
+        logger.info("alter-runtime daemon stopping")
+
+        # Stop phase - give each component a chance to flush
+        for managed in self._managed:
+            try:
+                await asyncio.wait_for(managed.component.stop(), timeout=5.0)
+            except (TimeoutError, Exception) as exc:
+                logger.warning("component %s stop() raised: %s", managed.component.name, exc)
+
+        # Cancel tasks
+        for managed in self._managed:
+            if managed.task and not managed.task.done():
+                managed.task.cancel()
+
+        # Await cancellation
+        for managed in self._managed:
+            if managed.task:
+                try:
+                    await managed.task
+                except asyncio.CancelledError:
+                    pass
+                except Exception as exc:
+                    logger.warning(
+                        "component %s exited with error: %s",
+                        managed.component.name,
+                        exc,
+                    )
+
+        # Run stop callbacks
+        for callback in self._on_stop_callbacks:
+            try:
+                await callback()
+            except Exception as exc:
+                logger.warning("stop callback raised: %s", exc)
+
+        logger.info("alter-runtime daemon stopped")
+
+    async def stop(self) -> None:
+        """Request graceful shutdown."""
+        self._stopping.set()
+
+    async def _supervise(self, managed: _ManagedTask) -> None:
+        """Run a component and restart it with backoff on failure."""
+        name = managed.component.name
+        while not self._stopping.is_set():
+            try:
+                logger.info("starting component %s", name)
+                await managed.component.run()
+                logger.info("component %s exited cleanly", name)
+                return
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                managed.restart_count += 1
+                backoff = min(
+                    self.BASE_BACKOFF_SECONDS * (2 ** (managed.restart_count - 1)),
+                    self.MAX_BACKOFF_SECONDS,
+                )
+                logger.warning(
+                    "component %s crashed (attempt %d): %s - restarting in %.1fs",
+                    name,
+                    managed.restart_count,
+                    exc,
+                    backoff,
+                )
+                try:
+                    await asyncio.wait_for(
+                        self._stopping.wait(),
+                        timeout=backoff,
+                    )
+                    return  # stop requested during backoff
+                except (TimeoutError, asyncio.TimeoutError):
+                    continue
+
+    def _install_signal_handlers(self) -> None:
+        loop = asyncio.get_running_loop()
+        # Windows doesn't support add_signal_handler; use signal.signal as a fallback
+        if sys.platform == "win32":
+            signal.signal(signal.SIGINT, lambda *_: loop.call_soon_threadsafe(self._stopping.set))
+            return
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            try:
+                loop.add_signal_handler(sig, self._stopping.set)
+            except NotImplementedError:
+                # Fallback for exotic event loops
+                signal.signal(sig, lambda *_: self._stopping.set())
+
+
+# ---------------------------------------------------------------------------
+# Top-level entrypoint used by the CLI `alter-runtime daemon`
+# ---------------------------------------------------------------------------
+
+
+async def run_daemon(config: DaemonConfig | None = None) -> None:
+    """Start the supervisor and block until shutdown.
+
+    Called by ``alter_runtime.cli.cmd_daemon``. Wave 1 registers no
+    components; Wave 2 will wire subscribers, sockets, and adapters here.
+    """
+    if config is None:
+        config = load_config()
+
+    _configure_logging(config.log_level)
+    ensure_directories()
+
+    session: Session | None = load_session()
+    if session is None:
+        logger.warning(
+            "no alter-cli session found at %s - daemon starting in degraded mode. "
+            "Run `alter login` to enable identity-aware subscribers.",
+            "~/.config/alter/session.json",
+        )
+    else:
+        logger.info(
+            "session loaded handle=%s consent_tier=L%d api=%s",
+            session.handle,
+            session.consent_tier,
+            session.api,
+        )
+
+    supervisor = Supervisor(config)
+
+    # Tighten the umask before any subscriber writes the inbox / state files
+    # so that O_CREAT | 0o600 always lands at the requested mode regardless
+    # of the inherited shell umask (§6.5 of Alter-to-Alter Messaging).
+    try:
+        import os as _os
+
+        _os.umask(0o077)
+    except Exception:  # pragma: no cover - exotic environments
+        pass
+
+    # D-AUTOUPDATE-1 Phase 1 — daemon-side update observer.
+    #
+    # Polls the release substrate on cadence and logs what it sees. No
+    # download, no verify, no apply this phase. Runs regardless of session
+    # state because the manifest is a public read surface — the loop never
+    # touches an authenticated endpoint.
+    if config.autoupdate_enabled:
+        from alter_runtime.update_loop import UpdateLoop
+
+        supervisor.register(
+            UpdateLoop(
+                manifest_url=config.autoupdate_manifest_url,
+                poll_interval_seconds=config.autoupdate_poll_interval_seconds,
+            )
+        )
+
+    # D-MIN-VERSION-FLOOR-1 Phase 3 — daemon-side floor preflight + gate.
+    #
+    # Sister loop to UpdateLoop: polls the server-side floor on the same
+    # 24h cadence, verifies the HMAC signature, and writes a shared
+    # FloorState. The Unix-socket server reads the state on every method
+    # dispatch and refuses to serve when below floor — emitting the
+    # canonical ``client_below_floor`` envelope (byte-shape-equal to the
+    # Phase 1 server middleware reject body). The A15.3 carve-out lets
+    # ``urgency: critical`` ingest payloads through even when locked.
+    #
+    # The floor endpoint is a public read; the loop runs regardless of
+    # session state.
+    from alter_runtime.floor_loop import FloorLoop, FloorState
+
+    floor_state = FloorState()
+    supervisor.register(FloorLoop(config, floor_state))
+
+    # Construct the in-process event bus that couples subscribers, sockets,
+    # and adapters. The bus is a transient coupling layer - durable state
+    # lives in the DO (replayable via Last-Event-ID) and the backend audit DB.
+    from alter_runtime.subscribers import (
+        ActiveSessionsCronEmitter,
+        ActiveSessionsDoPublisher,
+        ActiveSessionsGc,
+        ActiveSessionsWriter,
+        AdaptersWriter,
+        AgentFrameSubscriber,
+        CacheWriter,
+        CeremonyEchoWriter,
+        DoSseSubscriber,
+        EventBus,
+        InboxWriter,
+        McpFallbackSubscriber,
+        PresenceWriter,
+        SessionPresenceWriter,
+    )
+
+    event_bus = EventBus()
+
+    # Wave 2: register the full ingress/egress stack when we have an
+    # authenticated session. Without a session there's no handle to
+    # subscribe against, so the daemon idles in degraded mode until
+    # `alter login` populates session.json.
+    if session is not None:
+        # --- Ingress (L1) -------------------------------------------------
+        # Primary: DO SSE. Fallback: direct MCP polling per D-RT9. Both
+        # publish to ``identity.frame`` / ``identity.event`` - the fan-out
+        # layer below consumes from the bus so it never learns which path
+        # served a given event.
+        supervisor.register(DoSseSubscriber(config, session, event_bus))
+        supervisor.register(McpFallbackSubscriber(config, session, event_bus))
+
+        # InboxWriter was Wave 1's projection component; in Wave 2 we
+        # drive its ``handle_raw_frame`` entrypoint from the bus rather
+        # than having it open its own socket. This preserves the existing
+        # unit tests (which call handle_event directly) while hooking it
+        # into the real network path.
+        inbox = InboxWriter(config, session)
+        supervisor.register(inbox)
+        event_bus.subscribe("identity.frame", inbox.handle_raw_frame)
+
+        # CeremonyEchoWriter sits next to InboxWriter on the same bus.
+        # It filters the same frame stream for x-alter-recognition and
+        # x-alter-ceremony content_types and persists a tiny "echo
+        # state" file with a 72 h expiry. Shell-greeting consumers
+        # (alter-cli `alter room`, future menu greeting) read that
+        # file and render the echo iff still within the window.
+        # Per proposed-D-CUST-1 surface 21 (alter-internal #140).
+        ceremony = CeremonyEchoWriter(config, session)
+        supervisor.register(ceremony)
+        event_bus.subscribe("identity.frame", ceremony.handle_raw_frame)
+
+        # --- Local fan-out surfaces (L3 transports) -----------------------
+        # Import lazily so the top of the module stays cheap and so that
+        # missing optional deps (dbus-next) only fail on Linux installs
+        # that asked for them.
+        from alter_runtime.sockets import UnixSocketServer
+        from alter_runtime.sockets.dbus import DBusService
+
+        # CacheWriter projects identity state into the shared shell cache
+        # file (``$XDG_CACHE_HOME/alter/identity.json``) that
+        # ``scripts/alter-identity.sh`` and the CC ``alter-identity.sh``
+        # hook already read from. This is the W2.2d *first pixel* glue -
+        # when the daemon is running, existing shell tools transparently
+        # start showing live identity state without any shell changes.
+        supervisor.register(CacheWriter(event_bus))
+
+        # SessionPresenceWriter polls the org-alter /queries/presence
+        # projection on a cadence and writes ~/.local/share/org-alter/state/
+        # sessions.json. The alter monorepo's bash awareness hook merges
+        # that cache with same-host /dev/shm sibling files so every CC
+        # session sees parallel sessions across hosts. Cap-minted with the
+        # alter_org.read scope; idle when ``session_presence_enabled`` is
+        # false. No bus coupling - file-mediated handoff to bash hooks.
+        supervisor.register(SessionPresenceWriter(config, session))
+
+        # Identity Presence consolidation (Wave 2) - bus-driven JSONL writers
+        # under ``~/.local/share/alter-runtime/``. Schemas locked at
+        # ``docs/schemas/{presence,active-sessions,adapters}.schema.json``.
+        supervisor.register(PresenceWriter(config, event_bus))
+        supervisor.register(ActiveSessionsWriter(config, event_bus))
+        # D-COORD-D2 Wave B - periodic GC pass over the active-sessions
+        # JSONL. Reads under LOCK_SH, emits session_heartbeat (idle) /
+        # session_ended (complete) envelopes via the shared bus so the
+        # writer's dedup + rotation + 0o600 invariants are preserved.
+        # PID-liveness probe gated on tool==cc.
+        if config.active_sessions_gc_enabled:
+            supervisor.register(ActiveSessionsGc(config, event_bus))
+        supervisor.register(AdaptersWriter(config, event_bus))
+
+        # D-COORD-D2 Wave C - DO publisher. Tails the active-sessions
+        # JSONL written by ActiveSessionsWriter (above) and POSTs each new
+        # envelope to ``{do_publish_url}/events/{handle}/sessions/ingest``.
+        # The Worker side of this contract is the parallel `/events/<handle>/
+        # sessions/ingest` route; this side just publishes, the DO is
+        # responsible for filtering `session_ended` out of live SSE.
+        supervisor.register(ActiveSessionsDoPublisher(config, session))
+
+        # D-COORD-D2 Wave D - CronCreate emitter. Subscribes to
+        # ``cron.routine.started`` / ``cron.routine.finished`` on the
+        # in-process bus and re-publishes each as a ``tool: cron``
+        # envelope on ``identity.event``. The writer above projects
+        # those envelopes into the active-sessions JSONL exactly like
+        # any other tool, so daemon-scheduled routines participate in
+        # the cross-host substrate without per-routine code.
+        supervisor.register(ActiveSessionsCronEmitter(config, event_bus, session))
+
+        # D-AGENT-CHANNEL-1 Phase 2 Wave 6 — agent_frame subscriber.
+        # Filters DO SSE for ``content_type=x-alter-agent``, projects to
+        # ``~/.cache/alter/agent-frames.jsonl``, and re-publishes per-kind
+        # bus topics (``alter.agent.frame.{kind}``).  The subscriber also
+        # maintains an in-memory instrument roster which the UnixSocketServer
+        # serves via the ``agent/roster`` method without a DO round-trip.
+        agent_frames = AgentFrameSubscriber(event_bus)
+        supervisor.register(agent_frames)
+
+        supervisor.register(
+            UnixSocketServer(
+                config,
+                event_bus,
+                session,
+                agent_frames_subscriber=agent_frames,
+                floor_state=floor_state,
+            )
+        )
+        if config.enable_dbus:
+            supervisor.register(DBusService(config, event_bus, session))
+
+        # --- Ambient signal adapters --------------------------------------
+        from alter_runtime.adapters import GitWatcher
+        from alter_runtime.adapters.worktree_watcher import WorktreeWatcher
+
+        supervisor.register(GitWatcher(config, event_bus))
+
+        # D-WEAVE-VC-2 §8 item 1 (b) — working-tree fs-watch.
+        # WorktreeWatcher observes the repo working tree and publishes
+        # local.signal kind=worktree_edit on every file save (plain-editor
+        # tap — covers non-CC editors as a coarse second producer for weave).
+        supervisor.register(WorktreeWatcher(config, event_bus))
+
+        # D-WEAVE-VC-2 §8 items 1 + 2 — intent record writer.
+        # WeaveIntentWriter subscribes to local.signal worktree_edit events
+        # and tails weave-intent.jsonl for cc-intent hook records, writing
+        # enriched intent.* records with TTL + semantic_unit to
+        # ~/.local/share/alter-runtime/weave-intent.jsonl.
+        from alter_runtime.subscribers.weave_intent_writer import WeaveIntentWriter
+
+        supervisor.register(WeaveIntentWriter(config, event_bus))
+
+        # Claude Code JSONL token-usage watcher - opt-in via config flag.
+        # Tails ~/.claude/projects/**/*.jsonl and posts token-usage events to
+        # the ALTER backend audit endpoint. Disabled by default; enable via
+        # ALTER_RUNTIME_CLAUDE_JSONL_WATCHER=1 or direct config mutation.
+        if config.enable_claude_jsonl_watcher:
+            from alter_runtime.adapters.claude_jsonl_watcher import ClaudeJsonlWatcher
+
+            supervisor.register(ClaudeJsonlWatcher(config, event_bus))
+
+        # --- Kernel attestation (Wave 5b, Patent M) -----------------------
+        # The eBPF subscriber spawns the Rust ``alter-ebpf`` loader and
+        # republishes its exec stream onto ``kernel.attest.exec`` and
+        # ``local.signal``. It silently disables itself on hosts where the
+        # binary is missing or BPF LSM is unavailable, so it's safe to
+        # always register on Linux. Other platforms skip the import - the
+        # subscriber is Linux-only by construction.
+        if sys.platform.startswith("linux"):
+            from alter_runtime.subscribers import EbpfSubscriber
+
+            supervisor.register(EbpfSubscriber(config, event_bus))
+
+    await supervisor.run()
+
+
+def _configure_logging(level: str) -> None:
+    """Structured-ish logging for the daemon. Matches backend structlog intent
+    but keeps the dependency surface small (stdlib logging only)."""
+    logging.basicConfig(
+        level=level.upper(),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S%z",
+    )
+
+
+def _getpid() -> int:
+    try:
+        import os
+
+        return os.getpid()
+    except Exception:
+        return -1