cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/outbound_queue.py

@@ -0,0 +1,289 @@
+"""Outbound frame queue for the cloudagent daemon.
+
+Serializes all outgoing daemon→server sends through a lock (concurrent
+spawn supervisors may call simultaneously — must avoid interleaved JSON
+on the wire). Also provides high-level helpers for each outbound frame
+type. The actual wire (WebSocket vs HTTP-POST) is hidden behind a
+``Transport`` protocol — see ``transport.py``.
+
+Spec §4.2 / §4.3.
+
+Design note on pending_tool_calls ownership
+-------------------------------------------
+OutboundQueue creates and owns ``pending_tool_calls``.  FrameDispatcher
+accepts it via its ``tool_result_pending`` constructor parameter so that
+incoming ``tool_result`` frames resolve the same futures that
+``send_tool_call`` is awaiting.  Caller wires them together::
+
+    oq = OutboundQueue(transport)
+    dispatcher = FrameDispatcher(..., tool_result_pending=oq.pending_tool_calls)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from cloudagent_daemon.transport import Transport
+
+logger = logging.getLogger(__name__)
+
+
+def _new_frame_id() -> str:
+    return f"frm_{uuid4().hex[:16]}"
+
+
+def _new_request_id() -> str:
+    return f"req_{uuid4().hex}"
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+class OutboundQueue:
+    """Serialize outbound frames and provide frame-type helpers.
+
+    Parameters
+    ----------
+    transport:
+        A ``Transport`` (WS or HTTP) — anything with
+        ``async send_frame(frame: dict)``. ``None`` is allowed for
+        construction-before-connect; sends will raise until ``transport``
+        is rebound. Tests may pass a fake with a ``send`` method via the
+        legacy positional ``ws=`` keyword for back-compat (deprecated;
+        prefer ``transport=``).
+    default_tool_call_timeout:
+        Seconds to wait for a ``tool_result`` before returning a synthetic
+        ``SERVER_TIMEOUT`` response.
+    """
+
+    def __init__(
+        self,
+        transport: "Transport | None" = None,
+        *,
+        ws: object = None,  # legacy alias — accepts old WSClient or test
+                            # FakeWS objects with .send(frame)
+        default_tool_call_timeout: float = 30.0,
+        pending_tool_calls: dict[str, asyncio.Future] | None = None,
+    ) -> None:
+        # Back-compat: pre-1j call-sites and unit tests pass a WSClient or
+        # FakeWS as the first positional arg. Detect that shape (has
+        # ``send`` but no ``send_frame``) and wrap it with the legacy
+        # adapter so existing tests keep passing without edits.
+        if transport is not None and not hasattr(transport, "send_frame"):
+            if hasattr(transport, "send"):
+                transport = _LegacyWSAdapter(transport)
+            else:
+                # Anything else is a programming error — let it fail loudly
+                # downstream rather than silently produce a broken queue.
+                pass
+        if transport is None and ws is not None:
+            transport = _LegacyWSAdapter(ws)
+        self.transport: "Transport | None" = transport
+        self.default_tool_call_timeout = default_tool_call_timeout
+        self._send_lock = asyncio.Lock()
+        # Shared with FrameDispatcher — see module docstring. Accepting it as
+        # a constructor parameter lets ``main_loop.run_daemon`` build the dict
+        # once and pass the same instance to both the dispatcher and the
+        # outbound queue, avoiding a "rebind on connect" dance for the dict.
+        self.pending_tool_calls: dict[str, asyncio.Future] = (
+            pending_tool_calls if pending_tool_calls is not None else {}
+        )
+
+    @property
+    def ws(self) -> object:
+        """Legacy alias kept for ``main_loop._on_connect`` compatibility.
+
+        Reads return the underlying WSClient when running on the legacy
+        WS transport; ``None`` for HTTP/SSE or before connect. Writes
+        rebind the transport via ``_LegacyWSAdapter`` so existing
+        ``outbound.ws = client`` call-sites keep working unchanged.
+        """
+        if isinstance(self.transport, _LegacyWSAdapter):
+            return self.transport._ws
+        return None
+
+    @ws.setter
+    def ws(self, value: object) -> None:
+        if value is None:
+            self.transport = None
+            return
+        # If the caller hands us something that already looks like a
+        # Transport (has ``send_frame``), use it directly. Otherwise
+        # adapt a WSClient-shaped object.
+        if hasattr(value, "send_frame"):
+            self.transport = value  # type: ignore[assignment]
+        else:
+            self.transport = _LegacyWSAdapter(value)
+
+    # ------------------------------------------------------------------
+    # High-level helpers
+    # ------------------------------------------------------------------
+
+    async def send_ack(
+        self,
+        seq: int | None,
+        message_id: str,
+        status: str,
+        retry_after_ms: int | None = None,
+    ) -> None:
+        """Send a ``delivery_ack`` frame.
+
+        *seq=None* for non-deliver acks; the field is omitted from the
+        payload in that case (backend accepts missing seq).
+        """
+        payload: dict = {"message_id": message_id, "status": status}
+        if seq is not None:
+            payload["seq"] = seq
+        if retry_after_ms is not None:
+            payload["retry_after_ms"] = retry_after_ms
+
+        await self.send_raw({
+            "v": 1,
+            "type": "delivery_ack",
+            "id": _new_frame_id(),
+            "ts": _now_iso(),
+            "payload": payload,
+        })
+
+    async def send_agent_status(
+        self,
+        agent_id: str,
+        status: str,
+        exit_code: int | None = None,
+    ) -> None:
+        """Send an ``agent_status`` frame."""
+        payload: dict = {"agent_id": agent_id, "status": status}
+        if exit_code is not None:
+            payload["exit_code"] = exit_code
+
+        await self.send_raw({
+            "v": 1,
+            "type": "agent_status",
+            "id": _new_frame_id(),
+            "ts": _now_iso(),
+            "payload": payload,
+        })
+
+    async def send_agent_session_start(
+        self,
+        agent_id: str,
+        claude_session_id: str,
+        workdir_path: str | None = None,
+    ) -> None:
+        """Send an ``agent_session_start`` frame."""
+        payload: dict = {"agent_id": agent_id, "claude_session_id": claude_session_id}
+        if workdir_path:
+            payload["workdir_path"] = workdir_path
+
+        await self.send_raw({
+            "v": 1,
+            "type": "agent_session_start",
+            "id": _new_frame_id(),
+            "ts": _now_iso(),
+            "payload": payload,
+        })
+
+    async def send_tool_call(
+        self,
+        agent_id: str,
+        session_id: str | None,
+        tool_name: str,
+        args: dict,
+        *,
+        timeout: float | None = None,
+    ) -> dict:
+        """Send a ``tool_call`` frame and await the matching ``tool_result``.
+
+        Returns the tool_result payload dict on success.
+        On timeout returns a synthetic error::
+
+            {"request_id": rid, "ok": False, "error": {"code": "SERVER_TIMEOUT"}}
+        """
+        effective_timeout = timeout if timeout is not None else self.default_tool_call_timeout
+        rid = _new_request_id()
+
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future = loop.create_future()
+        self.pending_tool_calls[rid] = fut
+
+        # 1k #55 — fine-grained observability for the multi-tool wake bug.
+        # Logs at every state transition let us reconstruct timing of
+        # concurrent calls (rid is unique so log lines are unambiguous).
+        logger.info(
+            "outbound_queue: send_tool_call ENTER tool=%s agent=%s rid=%s "
+            "pending_count=%d",
+            tool_name, agent_id, rid, len(self.pending_tool_calls),
+        )
+
+        await self.send_raw({
+            "v": 1,
+            "type": "tool_call",
+            "id": _new_frame_id(),
+            "ts": _now_iso(),
+            "payload": {
+                "request_id": rid,
+                "agent_id": agent_id,
+                "session_id": session_id,
+                "tool_name": tool_name,
+                "args": args,
+            },
+        })
+        logger.info(
+            "outbound_queue: send_tool_call SENT rid=%s — awaiting tool_result",
+            rid,
+        )
+
+        try:
+            result = await asyncio.wait_for(fut, timeout=effective_timeout)
+            self.pending_tool_calls.pop(rid, None)
+            logger.info(
+                "outbound_queue: send_tool_call RESOLVED rid=%s ok=%s "
+                "pending_count=%d",
+                rid, result.get("ok"), len(self.pending_tool_calls),
+            )
+            return result
+        except asyncio.TimeoutError:
+            self.pending_tool_calls.pop(rid, None)
+            logger.warning(
+                "outbound_queue: send_tool_call TIMEOUT rid=%s after %.1fs "
+                "pending_count=%d",
+                rid, effective_timeout, len(self.pending_tool_calls),
+            )
+            return {
+                "request_id": rid,
+                "ok": False,
+                "error": {"code": "SERVER_TIMEOUT"},
+            }
+
+    async def send_raw(self, frame: dict) -> None:
+        """Lock-protected raw send. All other helpers call this."""
+        async with self._send_lock:
+            if self.transport is None:
+                # Daemon constructed the outbound queue but is not yet
+                # connected (or just disconnected). Surface a clear error
+                # rather than ``AttributeError`` on .send.
+                raise RuntimeError("OutboundQueue.transport is not bound")
+            await self.transport.send_frame(frame)
+
+
+class _LegacyWSAdapter:
+    """Adapt a WSClient (or test fake with ``async send(frame)``) to Transport.
+
+    This keeps the unit tests in ``test_outbound_queue.py`` and the legacy
+    ``main_loop`` WS path running while new code uses Transport directly.
+    """
+
+    def __init__(self, ws: object) -> None:
+        self._ws = ws
+
+    async def send_frame(self, frame: dict) -> None:
+        await self._ws.send(frame)  # type: ignore[attr-defined]
+
+    async def close(self) -> None:
+        # Lifecycle owned elsewhere — see ``WSTransport.close`` rationale.
+        return

cloudagent_daemon/paths.py

@@ -0,0 +1,204 @@
+"""Per-profile path resolution for the cloudagent daemon.
+
+A *profile* lets one host nurse multiple cloudagent backends in parallel
+(prod, fr, staging, …) by namespacing every persistent resource the
+daemon owns. The ``"default"`` profile keeps the legacy paths
+byte-for-byte unchanged — that is the foundation of our zero-migration
+guarantee for users already running the daemon.
+
+Layout (M6 multi-profile proposal 2026-05-18):
+
+  default profile                       named profile "fr"
+  ─────────────────                     ─────────────────
+  ~/.cloudagent/daemon/                 ~/.cloudagent/daemon/profiles/fr/
+    ├── config.json                       ├── config.json
+    ├── state.json                        ├── state.json
+    ├── bridge.sock                       ├── bridge.sock
+    ├── daemon.lock                       ├── daemon.lock
+    └── logs/                             └── logs/
+
+  ~/.cloudagent/agents/                 ~/.cloudagent/agents-fr/
+
+  launchd label:                        launchd label:
+    chat.cloudagent.daemon                chat.cloudagent.daemon.fr
+  systemd unit:                         systemd unit:
+    cloudagent-daemon.service             cloudagent-daemon-fr.service
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+DEFAULT_PROFILE = "default"
+
+# kebab-case, first char alnum, total length 1..31. Disallow ``.``, ``/``,
+# ``..``, whitespace, uppercase, underscores. Constraints come from:
+#  - launchd label segments (RFC-1035-ish, no dots / colons in the suffix)
+#  - filesystem safety (no path traversal)
+#  - cross-platform sanity (no case-sensitivity surprises on macOS HFS+)
+_PROFILE_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,30}$")
+
+# Env var name daemon spawns surface to subprocesses (mcp_bridge, future
+# helpers). Keeps the active profile pinned across exec boundaries even
+# when the parent never gets a chance to pass an explicit ``--profile``
+# flag. ``cli.py`` reads it as fallback for ``agent register`` /
+# ``agent unregister`` etc.
+ENV_VAR = "CLOUDAGENT_DAEMON_PROFILE"
+
+
+def validate_profile_name(name: str) -> str:
+    """Return *name* if it is safe to use; raise ``ValueError`` otherwise.
+
+    ``"default"`` is reserved and always valid (treated as the legacy /
+    unnamed profile). Anything else must match ``[a-z0-9][a-z0-9-]{0,30}``.
+    """
+    if name == DEFAULT_PROFILE:
+        return name
+    if not isinstance(name, str) or not _PROFILE_NAME_RE.fullmatch(name):
+        raise ValueError(
+            f"invalid profile name: {name!r} — must match "
+            f"[a-z0-9][a-z0-9-]{{0,30}} (e.g. 'fr', 'prod', 'staging-eu')"
+        )
+    return name
+
+
+def resolve_profile(name: str | None) -> str:
+    """Resolve the effective profile name.
+
+    Order: explicit *name* > ``CLOUDAGENT_DAEMON_PROFILE`` env > default.
+    Always validated. Empty string / ``None`` collapse to default.
+    """
+    if name:
+        return validate_profile_name(name)
+    env = os.environ.get(ENV_VAR, "").strip()
+    if env:
+        return validate_profile_name(env)
+    return DEFAULT_PROFILE
+
+
+# ---------- Filesystem layout ----------
+
+
+def _home() -> Path:
+    """Return ``$HOME``. Indirection so tests can monkeypatch ``HOME``."""
+    return Path.home()
+
+
+def profile_base_dir(profile: str | None = None) -> Path:
+    """Per-profile root: ``~/.cloudagent/daemon`` (default) or
+    ``~/.cloudagent/daemon/profiles/<name>`` (named)."""
+    p = resolve_profile(profile)
+    base = _home() / ".cloudagent" / "daemon"
+    if p == DEFAULT_PROFILE:
+        return base
+    return base / "profiles" / p
+
+
+def profile_config_path(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "config.json"
+
+
+def profile_state_path(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "state.json"
+
+
+def profile_socket_path(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "bridge.sock"
+
+
+def profile_lock_path(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "daemon.lock"
+
+
+def profile_pid_path(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "daemon.pid"
+
+
+def profile_log_dir(profile: str | None = None) -> Path:
+    return profile_base_dir(profile) / "logs"
+
+
+def profile_workspace_root(profile: str | None = None) -> Path:
+    """Default agent workspace root.
+
+    The default profile keeps the legacy ``~/.cloudagent/agents``;
+    named profiles get a sibling ``~/.cloudagent/agents-<name>`` so
+    file managers / terminals visually group them next to the
+    original tree rather than burying them under another nesting
+    level. Callers who want a fully-custom path keep using
+    ``--workspace-root`` exactly as before.
+    """
+    p = resolve_profile(profile)
+    if p == DEFAULT_PROFILE:
+        return _home() / ".cloudagent" / "agents"
+    return _home() / ".cloudagent" / f"agents-{p}"
+
+
+# ---------- Service identifiers ----------
+
+
+def profile_launchd_label(profile: str | None = None) -> str:
+    """launchd Label. Default profile keeps the legacy ``chat.cloudagent.daemon``;
+    named profiles append ``.<name>`` so multiple plists coexist."""
+    p = resolve_profile(profile)
+    base = "chat.cloudagent.daemon"
+    return base if p == DEFAULT_PROFILE else f"{base}.{p}"
+
+
+def profile_systemd_unit_name(profile: str | None = None) -> str:
+    """systemd unit filename. Default keeps legacy ``cloudagent-daemon.service``;
+    named profiles use a literal ``cloudagent-daemon-<name>.service``."""
+    p = resolve_profile(profile)
+    return (
+        "cloudagent-daemon.service"
+        if p == DEFAULT_PROFILE
+        else f"cloudagent-daemon-{p}.service"
+    )
+
+
+# ---------- Discovery ----------
+
+
+def list_installed_profiles() -> list[str]:
+    """Enumerate profiles that have a ``config.json`` on disk.
+
+    Default is included whenever its config exists; named profiles
+    show up under ``~/.cloudagent/daemon/profiles/<name>/``. Returns
+    a sorted list with ``default`` first (when present) so output
+    order is stable for ``list-profiles``.
+    """
+    found: list[str] = []
+    if profile_config_path(DEFAULT_PROFILE).exists():
+        found.append(DEFAULT_PROFILE)
+    profiles_dir = _home() / ".cloudagent" / "daemon" / "profiles"
+    if profiles_dir.is_dir():
+        for child in sorted(profiles_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            try:
+                validate_profile_name(child.name)
+            except ValueError:
+                continue
+            if (child / "config.json").exists():
+                found.append(child.name)
+    return found
+
+
+__all__ = [
+    "DEFAULT_PROFILE",
+    "ENV_VAR",
+    "validate_profile_name",
+    "resolve_profile",
+    "profile_base_dir",
+    "profile_config_path",
+    "profile_state_path",
+    "profile_socket_path",
+    "profile_lock_path",
+    "profile_pid_path",
+    "profile_log_dir",
+    "profile_workspace_root",
+    "profile_launchd_label",
+    "profile_systemd_unit_name",
+    "list_installed_profiles",
+]

cloudagent_daemon/protocol.py

@@ -0,0 +1,141 @@
+"""WebSocket frame schemas — vendored from backend/src/cloudagent/services/daemon_protocol.py.
+
+Spec: docs/superpowers/specs/2026-05-08-local-daemon-runtime-design.md §4
+
+Vendored (not imported from backend) so daemon_cli can be installed
+independently. If a schema changes on the backend, update this file
+in lock-step. A bigger Phase 2 refactor moves these to a shared package.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+# ---- Payload models ----
+
+class HelloAgentEntry(BaseModel):
+    agent_id: str
+    claude_session_id: str | None = None
+    runtime_config: dict[str, Any] | None = None
+
+
+class HelloPayload(BaseModel):
+    host_id: str
+    agents: list[HelloAgentEntry]
+
+
+class ReadyPayload(BaseModel):
+    daemon_ver: str
+    runtimes: list[dict[str, Any]]
+    hostname: str
+    os: str
+
+
+class AssignPayload(BaseModel):
+    agent_id: str
+    claude_session_id: str | None = None
+
+
+class UnassignPayload(BaseModel):
+    agent_id: str
+    reason: str
+
+
+class DeliverPayload(BaseModel):
+    agent_id: str
+    session_id: str
+    message_id: str
+    kind: str
+    body: str
+    sender: str
+    target: str
+
+
+class DeliveryAckPayload(BaseModel):
+    seq: int
+    message_id: str
+    status: Literal["received", "started", "failed", "queue_full"]
+    retry_after_ms: int | None = None
+
+
+class ToolCallPayload(BaseModel):
+    request_id: str
+    agent_id: str
+    session_id: str | None = None
+    tool_name: str
+    args: dict[str, Any]
+
+
+class ToolResultPayload(BaseModel):
+    request_id: str
+    ok: bool
+    data: dict[str, Any] | None = None
+    error: dict[str, Any] | None = None
+
+
+class AgentSessionStartPayload(BaseModel):
+    agent_id: str
+    claude_session_id: str
+    workdir_path: str | None = None
+
+
+class AgentStatusPayload(BaseModel):
+    agent_id: str
+    status: Literal["running", "idle", "crashed", "quarantined", "backpressure_dropped"]
+    exit_code: int | None = None
+    error: str | None = None
+
+
+class PingPayload(BaseModel):
+    pass  # empty payload
+
+
+class PongPayload(BaseModel):
+    pass
+
+
+class ByePayload(BaseModel):
+    reason: str
+
+
+# ---- Frame envelope ----
+
+FrameType = Literal[
+    "hello", "ready", "assign", "unassign",
+    "deliver", "delivery_ack",
+    "tool_call", "tool_result",
+    "agent_session_start", "agent_status",
+    "ping", "pong", "bye",
+]
+
+_PAYLOAD_TYPES = {
+    "hello": HelloPayload, "ready": ReadyPayload,
+    "assign": AssignPayload, "unassign": UnassignPayload,
+    "deliver": DeliverPayload, "delivery_ack": DeliveryAckPayload,
+    "tool_call": ToolCallPayload, "tool_result": ToolResultPayload,
+    "agent_session_start": AgentSessionStartPayload,
+    "agent_status": AgentStatusPayload,
+    "ping": PingPayload, "pong": PongPayload, "bye": ByePayload,
+}
+
+
+class Frame(BaseModel):
+    v: Literal[1]
+    type: FrameType
+    id: str
+    ts: datetime
+    seq: int | None = None
+    payload: Any  # validated post-init
+
+    def model_post_init(self, _ctx: Any) -> None:
+        cls = _PAYLOAD_TYPES.get(self.type)
+        if cls is None:
+            raise ValueError(f"unknown frame type: {self.type}")
+        if not isinstance(self.payload, cls):
+            self.payload = cls.model_validate(self.payload)
+
+
+def parse_frame(raw: dict[str, Any]) -> Frame:
+    return Frame.model_validate(raw)