cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/frame_dispatch.py

@@ -0,0 +1,216 @@
+"""Inbound frame dispatcher for the cloudagent daemon.
+
+Routes WebSocket frames received from the server to the appropriate
+handler/callback. Actual spawn logic (Task 8), outbound queue (Task 7),
+and workspace management (Task 11) are injected via callbacks so this
+module stays dependency-free beyond DaemonState and stdlib.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cloudagent_daemon.config import DaemonState
+
+if TYPE_CHECKING:
+    from cloudagent_daemon.spawn_outbox import SpawnOutbox
+
+logger = logging.getLogger(__name__)
+
+
+class FrameDispatcher:
+    """Route inbound frames to registered callbacks.
+
+    Parameters
+    ----------
+    state:
+        Live DaemonState; mutated on accepted deliver frames.
+    state_path:
+        Path passed to ``state.save()`` after each accepted deliver.
+    ack_callback:
+        Called as ``ack_callback(seq, message_id, status)`` immediately
+        after a deliver frame passes the idempotency check.
+    spawn_callback:
+        Called with the deliver payload dict for new (non-duplicate) frames.
+    tool_result_pending:
+        Shared dict mapping ``request_id`` → ``asyncio.Future``.  The
+        dispatcher pops and resolves futures as ``tool_result`` frames arrive.
+    workspace_assign_callback:
+        Optional; called with the assign payload dict.
+    workspace_unassign_callback:
+        Optional; called with the unassign payload dict.
+    bye_callback:
+        Optional; called with the bye payload dict to trigger shutdown.
+    spawn_outbox:
+        Optional; durable journal of accepted deliver frames. When
+        provided, every new (non-duplicate) frame is persisted via
+        :meth:`SpawnOutbox.record_received` BEFORE the server-side ack
+        so a daemon crash between ack and spawn doesn't silently lose
+        the frame. See ``spawn_outbox.py`` for details (Bug 4).
+    """
+
+    def __init__(
+        self,
+        *,
+        state: DaemonState,
+        state_path: Path,
+        ack_callback: Callable[[int, str, str], Awaitable[None]],
+        spawn_callback: Callable[[dict], Awaitable[None]],
+        tool_result_pending: dict[str, asyncio.Future],
+        workspace_assign_callback: Callable[[dict], Awaitable[None]] | None = None,
+        workspace_unassign_callback: Callable[[dict], Awaitable[None]] | None = None,
+        bye_callback: Callable[[dict], Awaitable[None]] | None = None,
+        spawn_outbox: "SpawnOutbox | None" = None,
+    ) -> None:
+        self.state = state
+        self.state_path = state_path
+        self.ack_callback = ack_callback
+        self.spawn_callback = spawn_callback
+        self.tool_result_pending = tool_result_pending
+        self.workspace_assign_callback = workspace_assign_callback
+        self.workspace_unassign_callback = workspace_unassign_callback
+        self.bye_callback = bye_callback
+        self.spawn_outbox = spawn_outbox
+
+    # ------------------------------------------------------------------
+    # Public entry point
+    # ------------------------------------------------------------------
+
+    async def dispatch(self, frame: dict) -> None:
+        """Dispatch *frame* to the appropriate handler."""
+        t = frame.get("type")
+        if t == "deliver":
+            await self._on_deliver(frame)
+        elif t == "tool_result":
+            self._on_tool_result(frame)
+        elif t == "assign":
+            await self._on_assign(frame)
+        elif t == "unassign":
+            await self._on_unassign(frame)
+        elif t == "bye":
+            await self._on_bye(frame)
+        elif t == "hello":
+            pass  # WSClient already consumed this in __aenter__
+        else:
+            logger.warning("unknown frame type: %s", t)
+
+    # ------------------------------------------------------------------
+    # Handlers
+    # ------------------------------------------------------------------
+
+    async def _on_deliver(self, frame: dict) -> None:
+        seq = frame["seq"]
+        payload = frame["payload"]
+        msg_id = payload["message_id"]
+        # K1 §护栏 9 — server-stamped wake idempotency key. When set, dedupe
+        # by wake_id in addition to message_id so reconnect-catchup of a
+        # frame whose wake was already handled lands as ack-only. Frames
+        # without ``wake_id`` (test-chat / direct task creation) keep the
+        # legacy message_id-only path.
+        wake_id = payload.get("wake_id") if isinstance(payload, dict) else None
+
+        # Idempotency: already processed (by either key) → ack-only, skip spawn
+        if self.state.has_processed(msg_id):
+            logger.info(
+                "frame_dispatch: deliver duplicate (msg_id already processed) "
+                "agent=%s msg=%s seq=%d",
+                payload.get("agent_id"),
+                msg_id,
+                seq,
+            )
+            await self.ack_callback(seq, msg_id, "received")
+            return
+        if wake_id and self.state.has_processed(wake_id):
+            logger.info(
+                "frame_dispatch: deliver duplicate (wake_id already processed) "
+                "agent=%s msg=%s wake=%s seq=%d",
+                payload.get("agent_id"),
+                msg_id,
+                wake_id,
+                seq,
+            )
+            # Still record the message_id so further re-deliveries of the
+            # same row hit the cheap msg_id branch above.
+            self.state.add_processed(msg_id)
+            self.state.last_seq = max(self.state.last_seq, seq)
+            self.state.save(self.state_path)
+            await self.ack_callback(seq, msg_id, "received")
+            return
+
+        # 1i Bug C — Phase 1 demo visibility for the spawn pipeline.
+        logger.info(
+            "frame_dispatch: dispatching deliver agent=%s msg=%s wake=%s seq=%d body_len=%d",
+            payload.get("agent_id"),
+            msg_id,
+            wake_id,
+            seq,
+            len(payload.get("body") or ""),
+        )
+
+        # Bug 4 (2026-05-12) — persist the frame BEFORE the ack so a
+        # crash between ack and spawn doesn't silently lose it. The
+        # outbox is the authoritative replay source on next boot.
+        # If the outbox write fails we deliberately do NOT ack —
+        # server will redeliver on reconnect and we'll try again.
+        if self.spawn_outbox is not None:
+            try:
+                await self.spawn_outbox.record_received(payload)
+            except Exception:
+                logger.exception(
+                    "frame_dispatch: spawn_outbox.record_received failed "
+                    "agent=%s msg=%s — skipping ack, server will redeliver",
+                    payload.get("agent_id"),
+                    msg_id,
+                )
+                return
+
+        self.state.add_processed(msg_id)
+        if wake_id:
+            self.state.add_processed(wake_id)
+        self.state.last_seq = max(self.state.last_seq, seq)
+        self.state.save(self.state_path)
+
+        await self.ack_callback(seq, msg_id, "received")
+        await self.spawn_callback(payload)
+
+    def _on_tool_result(self, frame: dict) -> None:
+        payload = frame["payload"]
+        rid = payload["request_id"]
+        fut = self.tool_result_pending.pop(rid, None)
+        # 1k #55 — observability for the multi-tool wake bug. Without this
+        # we cannot tell whether a tool_result reached the dispatcher at
+        # all, whether it matched a pending future, or whether it was a
+        # late arrival (future already done).
+        if fut is None:
+            logger.warning(
+                "frame_dispatch: tool_result rid=%s — NO PENDING FUTURE "
+                "(late arrival, duplicate, or unknown rid)",
+                rid,
+            )
+            return
+        if fut.done():
+            logger.warning(
+                "frame_dispatch: tool_result rid=%s — future ALREADY DONE",
+                rid,
+            )
+            return
+        logger.info(
+            "frame_dispatch: tool_result rid=%s ok=%s — resolving future",
+            rid, payload.get("ok"),
+        )
+        fut.set_result(payload)
+
+    async def _on_assign(self, frame: dict) -> None:
+        if self.workspace_assign_callback:
+            await self.workspace_assign_callback(frame["payload"])
+
+    async def _on_unassign(self, frame: dict) -> None:
+        if self.workspace_unassign_callback:
+            await self.workspace_unassign_callback(frame["payload"])
+
+    async def _on_bye(self, frame: dict) -> None:
+        if self.bye_callback:
+            await self.bye_callback(frame["payload"])

cloudagent_daemon/http_outbound.py

@@ -0,0 +1,80 @@
+"""HTTP POST sender for daemon→server frames.
+
+The SSE transport replaces the WebSocket's bidirectionality with an SSE
+stream (server→daemon) plus per-frame-type POST endpoints (daemon→server).
+``HTTPOutbound`` owns the shared httpx.AsyncClient and is reused across all
+POST calls so connection pooling, HTTP/2 multiplexing, and TLS sessions
+amortise.
+"""
+from __future__ import annotations
+
+import logging
+import ssl
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Outbound POST timeout. Tight enough that a hung server doesn't block
+# the daemon's SpawnQueue serialise; loose enough that a slow but healthy
+# server (cold-start container, GC pause) doesn't get spuriously aborted.
+_POST_TIMEOUT_SECONDS = 10.0
+
+
+class HTTPOutbound:
+    """Authorised POST sender backed by a single httpx.AsyncClient.
+
+    All POSTs share:
+      * Bearer authorisation (set as a default header).
+      * The same TLS verification policy (``insecure=True`` disables cert
+        validation — used for dev environments with self-signed certs).
+      * The base URL (``server_url``) so callers pass relative paths.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        api_key: str,
+        *,
+        insecure: bool = False,
+    ) -> None:
+        self._server_url = server_url.rstrip("/")
+        self._api_key = api_key
+        self._insecure = insecure
+
+        verify: ssl.SSLContext | bool = not insecure
+        self._client = httpx.AsyncClient(
+            base_url=self._server_url,
+            verify=verify,
+            timeout=httpx.Timeout(_POST_TIMEOUT_SECONDS),
+            headers={"Authorization": f"Bearer {api_key}"},
+            trust_env=True,
+        )
+
+    async def post(self, path: str, json_body: dict) -> dict:
+        """POST ``json_body`` to ``path``; return parsed JSON or ``{}``.
+
+        Raises ``httpx.HTTPStatusError`` for any 4xx/5xx response so
+        the caller (Transport) can surface auth failures vs. transient.
+        """
+        r = await self._client.post(path, json=json_body)
+        r.raise_for_status()
+        # Some endpoints reply 204 No Content (e.g. heartbeat tolerates it
+        # in testing fakes); handle that without choking on empty bodies.
+        if r.status_code == 204 or not r.content:
+            return {}
+        try:
+            return r.json()
+        except ValueError:
+            # Non-JSON 200 body — treat as empty rather than crash. Real
+            # backend always returns JSON; this is defensive for proxies
+            # that inject HTML error pages.
+            logger.warning(
+                "http_outbound: non-JSON 2xx body for %s (%d bytes)",
+                path,
+                len(r.content),
+            )
+            return {}
+
+    async def close(self) -> None:
+        await self._client.aclose()

cloudagent_daemon/jsonl_logging.py

@@ -0,0 +1,98 @@
+"""Wave C #3 — opt-in JSONL log formatter.
+
+Default off (preserves the grep-based ops flow over launchd.err.log).
+When ``CLOUDAGENT_DAEMON_JSON_LOG=1`` is exported BEFORE the daemon
+starts, every log record is rendered as a single-line JSON object —
+key tokens (``msg`` / ``level`` / ``name``) still appear so existing
+``grep frame_dispatch`` -style searches keep working.
+
+Schema (one object per line)::
+
+  {"ts": "2026-05-12T10:31:53Z", "level": "INFO",
+   "name": "cloudagent_daemon.main_loop",
+   "msg": "daemon ready: host_id=...", "pid": 51624,
+   "thread": "MainThread"}
+
+If a log record carries ``extra={"event": ...}`` style fields, those
+are merged into the top-level object (e.g. structured spawn events).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from datetime import UTC, datetime
+
+
+_ENV_VAR = "CLOUDAGENT_DAEMON_JSON_LOG"
+
+
+class JsonlFormatter(logging.Formatter):
+    """One-line JSON per record."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Parity with :class:`logging.Formatter.format` — set
+        # ``record.message`` so downstream tooling (pytest's caplog,
+        # third-party Sentry hooks) that reads the attribute keeps
+        # working after the formatter runs.
+        record.message = record.getMessage()
+        # Build the canonical envelope first so the order is stable
+        # across records — easier on humans tailing the log.
+        out: dict = {
+            "ts": datetime.now(UTC).isoformat(),
+            "level": record.levelname,
+            "name": record.name,
+            "msg": record.message,
+            "pid": os.getpid(),
+            "thread": threading.current_thread().name,
+        }
+        if record.exc_info:
+            out["exc"] = self.formatException(record.exc_info)
+        # Merge any structured extras carried on the record. ``record.__dict__``
+        # contains a fixed set of LogRecord fields + whatever ``extra=``
+        # caller passed; we keep only the latter.
+        reserved = {
+            "name", "msg", "args", "levelname", "levelno", "pathname",
+            "filename", "module", "exc_info", "exc_text", "stack_info",
+            "lineno", "funcName", "created", "msecs", "relativeCreated",
+            "thread", "threadName", "processName", "process", "message",
+        }
+        for key, value in record.__dict__.items():
+            if key in reserved or key in out:
+                continue
+            try:
+                json.dumps(value)
+                out[key] = value
+            except (TypeError, ValueError):
+                # Non-JSON-able extras get a string repr — never drop
+                # them silently, an operator may need that hint.
+                out[key] = repr(value)
+        return json.dumps(out, ensure_ascii=False)
+
+
+def jsonl_logging_enabled() -> bool:
+    """Return True when the env switch is set."""
+    return os.environ.get(_ENV_VAR, "").lower() in ("1", "true", "yes")
+
+
+def configure_logging() -> None:
+    """Apply :class:`JsonlFormatter` to the root logger if env enables it.
+
+    Called from ``cli.start`` AFTER ``logging.basicConfig`` so we can
+    safely overwrite the default formatter on the root logger's
+    first (and only) handler.
+    """
+    if not jsonl_logging_enabled():
+        return
+    root = logging.getLogger()
+    fmt = JsonlFormatter()
+    for h in root.handlers:
+        h.setFormatter(fmt)
+
+
+__all__ = [
+    "JsonlFormatter",
+    "configure_logging",
+    "jsonl_logging_enabled",
+]

cloudagent_daemon/login.py

@@ -0,0 +1,34 @@
+"""Login verification logic for cloudagent-daemon.
+
+Separated from cli.py for testability.
+"""
+from __future__ import annotations
+
+
+async def verify_and_capture_host_id(
+    server_url: str,
+    api_key: str,
+    *,
+    insecure: bool = False,
+) -> str:
+    """Open a quick WS connection to verify key, capture host_id, then close.
+
+    Raises AuthFailed if 401/403; raises RuntimeError on other connect failures.
+
+    ``insecure=True`` skips TLS certificate verification — only use for known
+    self-signed dev/staging hosts (e.g. fr pre-Wave-7).
+    """
+    from .ws_client import WSClient
+
+    async with WSClient(server_url, api_key, insecure=insecure) as ws:
+        return ws.host_id
+
+
+def normalize_server_url(url: str) -> str:
+    """Trim trailing /, strip /v1 suffix if present, validate http(s) scheme."""
+    url = url.rstrip("/")
+    if url.endswith("/v1"):
+        url = url[:-3]
+    if not url.startswith(("http://", "https://")):
+        raise ValueError(f"server URL must start with http:// or https://: {url!r}")
+    return url