cloudagent-daemon 0.2.1__py3-none-any.whl

cloudagent_daemon/mcp_bridge.py

@@ -0,0 +1,441 @@
+"""Stdio MCP server invoked by the claude subprocess.
+
+Architecture (see spec §6.2 / §4.7):
+
+    claude (subprocess of ClaudeRunner)
+        │ MCP stdio (NDJSON, mcp protocol)
+        ▼
+    mcp_bridge subprocess (`cloudagent-daemon mcp-bridge ...`)
+        │ unix socket (line-delimited JSON request/response)
+        ▼
+    daemon-main process
+
+Each tool the bridge registers, when invoked by claude, opens a unix-socket
+connection back to daemon-main and tunnels the call as an IPC ``tool_call``
+op. The daemon-main process is the only place that owns the WebSocket.
+
+Instance-level isolation (spec §6.4): ``build_server`` reads
+``identity.json`` and only registers the 4 chief-only tools when
+``is_chief is True``. Staff agents never see those tools, so the LLM
+cannot attempt calls it is not allowed to make — no reliance on LLM
+self-restraint. Server-side enforcement (chief-hallucination-guard in
+``daemon_dispatcher.py``) still provides a second line of defence.
+
+Session ID (1k hotfix): the bridge reads the cloudagent business
+``session_id`` for the current wake from
+``~/.cloudagent/agents/<agent_id>/.meta/current-session.txt``. The
+daemon (claude_runner) writes that file BEFORE spawning ``claude`` and
+removes it AFTER the wake completes. When the file is missing (legacy
+clients, cleanup race, or stale spawns) the bridge falls back to ``None``
+and the backend dispatcher will reject the call with INVALID_ARGS — far
+preferable to a silent cross-session mix-up.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .unix_socket import DEFAULT_SOCKET_PATH, UnixSocketClient
+
+logger = logging.getLogger(__name__)
+
+# Tool set split per spec §6.4 instance-level isolation.
+COMMON_TOOLS: frozenset[str] = frozenset(
+    {"send_message", "list_messages", "upload_file", "schedule_reminder"}
+)
+CHIEF_ONLY_TOOLS: frozenset[str] = frozenset(
+    {"delegate_to_staff", "close_task", "request_user_approval", "set_company_status"}
+)
+
+
+def _read_identity(agent_id: str) -> dict:
+    """Defensive read of ``~/.cloudagent/agents/<id>/.meta/identity.json``.
+
+    Returns the parsed dict on success. On any failure (missing file,
+    invalid JSON, OS error) returns ``{}`` which causes ``build_server``
+    to treat the agent as a staff member (``is_chief`` defaults to
+    ``False`` — the safe/secure default).
+    """
+    path = Path.home() / ".cloudagent" / "agents" / agent_id / ".meta" / "identity.json"
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+
+
+async def _query_daemon_session(
+    agent_id: str, socket_path: Path
+) -> str | None:
+    """(c) IPC architecture upgrade — query daemon in-memory session map.
+
+    Sends a ``get_current_session`` request over the unix socket and
+    returns the session_id from the daemon's memory (set by ClaudeRunner
+    before spawning this very bridge). Faster and more reliable than the
+    file-based path because it bypasses filesystem caching / mode issues.
+
+    Returns ``None`` on any failure (socket missing, timeout, old daemon
+    without the op) so the caller can fall back to the file path.
+    """
+    try:
+        async with UnixSocketClient(socket_path) as ipc:
+            result = await ipc.call(
+                "get_current_session",
+                {"agent_id": agent_id},
+                timeout=5.0,
+            )
+            sid = result.get("session_id")
+            return sid if isinstance(sid, str) and sid else None
+    except Exception:  # noqa: BLE001
+        # Socket missing, old daemon (UNKNOWN_OP), or timeout — fall
+        # through to file-based path. Not an error: backward compat.
+        return None
+
+
+def _read_current_session(
+    agent_id: str, workspace_root: Path | None = None
+) -> str | None:
+    """Defensive read of ``.meta/current-session.txt`` (1k hotfix).
+
+    Returns the session_id string if present and non-empty, ``None``
+    otherwise. Tolerates a missing file — that situation is normal for
+    legacy daemons that haven't been redeployed yet, and we'd rather
+    let the backend reject with INVALID_ARGS than crash the bridge.
+
+    Profile-aware (2026-05-18 fix): named profiles store agents under
+    ``~/.cloudagent/agents-<profile>/`` (see paths.profile_workspace_root).
+    Without this resolution, the bridge read the default-profile path and
+    always missed current-session.txt for daily/staging/etc → every MCP
+    tool call dispatched ``session_id=None`` → backend rejected as
+    "missing required arg" → claude retried 30+s per turn.
+
+    (c) fallback: called after ``_query_daemon_session`` fails (old
+    daemon without the ``get_current_session`` IPC op or socket missing).
+    """
+    if workspace_root is None:
+        # Read CLOUDAGENT_DAEMON_PROFILE env var written by service.py /
+        # main_loop.py for spawned children (claude inherits it).
+        from .paths import profile_workspace_root
+        import os
+        profile_env = os.environ.get("CLOUDAGENT_DAEMON_PROFILE")
+        workspace_root = profile_workspace_root(profile_env)
+    p = workspace_root / agent_id / ".meta" / "current-session.txt"
+    try:
+        sid = p.read_text().strip()
+        return sid or None
+    except (FileNotFoundError, OSError):
+        return None
+
+
+async def _ipc_tool_call(
+    socket_path: Path,
+    agent_id: str,
+    tool_name: str,
+    tool_args: dict,
+    session_id: str | None,
+) -> dict:
+    """Single round-trip: open socket → send tool_call → return result."""
+    # 1k #55 — log the tool dispatch BEFORE we touch the socket so we can
+    # tell apart "claude never invoked the tool" vs "tool invoked but
+    # bridge couldn't reach the daemon".
+    logger.info(
+        "mcp_bridge: tool dispatch ENTER tool=%s agent=%s session=%s",
+        tool_name, agent_id, session_id,
+    )
+    try:
+        async with UnixSocketClient(socket_path) as ipc:
+            logger.info(
+                "mcp_bridge: ipc connected socket=%s tool=%s agent=%s session=%s",
+                socket_path, tool_name, agent_id, session_id,
+            )
+            result = await ipc.call(
+                "tool_call",
+                {
+                    "agent_id": agent_id,
+                    "session_id": session_id,
+                    "tool_name": tool_name,
+                    "tool_args": tool_args,
+                },
+            )
+            logger.info(
+                "mcp_bridge: tool dispatch EXIT tool=%s ok=%s",
+                tool_name, "ok" in str(result) or result,
+            )
+            return result
+    except Exception:
+        logger.exception(
+            "mcp_bridge: tool dispatch FAILED tool=%s agent=%s",
+            tool_name, agent_id,
+        )
+        raise
+
+
+def build_server(
+    agent_id: str,
+    socket_path: Path = DEFAULT_SOCKET_PATH,
+    identity: dict | None = None,
+    session_id: str | None = None,
+) -> FastMCP:
+    """Construct a FastMCP server with tools filtered by ``is_chief``.
+
+    Split out from ``run_bridge`` so unit tests can introspect the tool
+    list without spinning up stdio.
+
+    Chief agents get all 8 tools (4 common + 4 chief-only).
+    Staff agents (``is_chief`` absent or ``False``) get only the 4 common
+    tools — the LLM never sees the chief-only names, implementing the
+    instance-level isolation required by spec §6.4.
+
+    ``session_id`` (1k hotfix): the cloudagent business session_id that
+    every IPC ``tool_call`` payload must carry. Reads the current
+    deliver's session_id; the daemon's tool dispatcher requires it to
+    route the tool result back to the right business conversation.
+    Pass ``None`` only when no session is known (the backend will then
+    reject with INVALID_ARGS — that's the expected behaviour and
+    surfaces the bug rather than masking it).
+    """
+    if identity is None:
+        identity = _read_identity(agent_id)
+
+    is_chief: bool = identity.get("is_chief") is True  # False when missing or non-True
+
+    server = FastMCP(name=f"cloudagent-bridge-{agent_id}")
+
+    # ---- Common tools (all agents) ----------------------------------------
+
+    @server.tool(
+        description=(
+            "Send a message to another agent or the user. When replying "
+            "(kind=\"reply\" or \"question\"), MUST set parent_msg_id to the "
+            "inbound message's message_id (shown in the [meta] header of "
+            "your stdin) so the sender's wait_for_replies satisfies; "
+            "leave parent_msg_id=None for unsolicited kind=\"task\" / "
+            "\"report\" sends."
+        )
+    )
+    async def send_message(
+        target: str,
+        body: str,
+        kind: str = "task",
+        parent_msg_id: int | None = None,
+    ) -> dict[str, Any]:
+        # Hot-fix 2026-05-12 — local_daemon staff replies were dropping
+        # ``parent_msg_id``, which left the chief's ``wait_for_replies``
+        # forever stuck on missing parents (cloud_pod staff already
+        # passed the id by virtue of going through ``send_message`` on
+        # the chief's server-side session; the daemon path didn't have
+        # the parameter on its tool surface). Now exposed on the tool
+        # AND threaded into the IPC payload — backend
+        # ``/v1/daemon/tool-call`` keeps the field on the dispatcher
+        # call to ``message_service.send`` (林逸舟 wire-in).
+        tool_args: dict[str, Any] = {
+            "target": target,
+            "body": body,
+            "kind": kind,
+        }
+        if parent_msg_id is not None:
+            tool_args["parent_msg_id"] = parent_msg_id
+        return await _ipc_tool_call(
+            socket_path,
+            agent_id,
+            "send_message",
+            tool_args,
+            session_id,
+        )
+
+    @server.tool(description="List recent messages in the agent's inbox.")
+    async def list_messages(limit: int = 50) -> dict[str, Any]:
+        return await _ipc_tool_call(
+            socket_path, agent_id, "list_messages", {"limit": limit}, session_id
+        )
+
+    @server.tool(description="Upload a local file and attach it to the conversation.")
+    async def upload_file(path: str) -> dict[str, Any]:
+        return await _ipc_tool_call(
+            socket_path, agent_id, "upload_file", {"path": path}, session_id
+        )
+
+    @server.tool(description="Schedule a reminder for the agent at a future time.")
+    async def schedule_reminder(when: str, body: str) -> dict[str, Any]:
+        return await _ipc_tool_call(
+            socket_path,
+            agent_id,
+            "schedule_reminder",
+            {"when": when, "body": body},
+            session_id,
+        )
+
+    # ---- Chief-only tools (registered only when is_chief is True) ---------
+
+    if is_chief:
+
+        @server.tool(description="[chief] Delegate work to a staff agent.")
+        async def delegate_to_staff(staff_id: str, body: str) -> dict[str, Any]:
+            return await _ipc_tool_call(
+                socket_path,
+                agent_id,
+                "delegate_to_staff",
+                {"staff_id": staff_id, "body": body},
+                session_id,
+            )
+
+        @server.tool(description="[chief] Mark a task closed with a summary.")
+        async def close_task(task_id: str, summary: str) -> dict[str, Any]:
+            return await _ipc_tool_call(
+                socket_path,
+                agent_id,
+                "close_task",
+                {"task_id": task_id, "summary": summary},
+                session_id,
+            )
+
+        @server.tool(description="[chief] Ask the user for explicit approval.")
+        async def request_user_approval(question: str) -> dict[str, Any]:
+            return await _ipc_tool_call(
+                socket_path,
+                agent_id,
+                "request_user_approval",
+                {"question": question},
+                session_id,
+            )
+
+        @server.tool(description="[chief] Update the company-wide status string.")
+        async def set_company_status(status: str) -> dict[str, Any]:
+            return await _ipc_tool_call(
+                socket_path,
+                agent_id,
+                "set_company_status",
+                {"status": status},
+                session_id,
+            )
+
+    return server
+
+
+def _configure_bridge_logging() -> None:
+    """Send bridge logs to stderr — stdout is reserved for MCP stdio framing.
+
+    ``claude`` invokes the bridge as a stdio MCP subprocess. Anything we
+    print to stdout would corrupt the MCP wire protocol (NDJSON-framed).
+    We therefore route Python logging to stderr only. ``claude`` captures
+    bridge stderr and surfaces it on its own stderr (visible to the
+    daemon's spawn supervisor and to manual ``claude --mcp-debug`` runs).
+    """
+    root = logging.getLogger()
+    # Don't double-attach if a parent already wired one.
+    if any(
+        isinstance(h, logging.StreamHandler) and h.stream is sys.stderr
+        for h in root.handlers
+    ):
+        return
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s %(levelname)s mcp_bridge: %(message)s"
+        )
+    )
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+
+
+async def run_bridge(
+    agent_id: str,
+    token_file: Path | None = None,
+    socket_path: Path | None = None,
+    profile: str | None = None,
+) -> None:
+    """Run the bridge until claude closes stdin.
+
+    Phase 1 (1i Bug B): the per-spawn token file is **not required**.
+    The original spec §6.6 token-file scheme was never wired end-to-end
+    (claude_runner only deletes the token post-spawn, never writes it
+    pre-spawn), and the bridge does not send the token on IPC calls
+    anyway. For Phase 1 we rely on filesystem-level access control —
+    the unix socket is mode 0o600 (owner-only). Task 11/1c will revisit
+    bridge↔daemon authentication when the token scheme is real.
+
+    Behaviour:
+    * If ``token_file`` is ``None`` or the file is missing → log a
+      warning and continue (do NOT abort the bridge — that would crash
+      every spawn and the user would see "MCP server cloudagent failed").
+    * If the file exists → read it (we don't use the value yet, but
+      reading proves we have access; useful for future auth wiring).
+    """
+    _configure_bridge_logging()
+
+    # Resolve socket_path lazily so the default reflects the active
+    # profile (CLOUDAGENT_DAEMON_PROFILE env var if --profile not
+    # passed). Existing callers that pass a Path keep their behaviour.
+    if socket_path is None:
+        from .unix_socket import default_socket_path
+
+        socket_path = default_socket_path(profile)
+
+    logger.info(
+        "mcp_bridge: starting agent=%s socket=%s token_file=%s",
+        agent_id,
+        socket_path,
+        token_file,
+    )
+
+    if token_file is not None and token_file.exists():
+        try:
+            _ = token_file.read_text()
+            logger.info("mcp_bridge: token file present (Phase 1: not validated)")
+        except OSError as exc:
+            logger.warning(
+                "mcp_bridge: could not read token file %s: %s "
+                "(Phase 1: continuing without token)",
+                token_file,
+                exc,
+            )
+    else:
+        logger.info(
+            "mcp_bridge: no token file (Phase 1: continuing — auth via "
+            "unix-socket 0o600 ownership)"
+        )
+
+    identity = _read_identity(agent_id)
+    # (c) IPC architecture upgrade — try daemon memory query first
+    # (faster, not subject to filesystem caching / mode issues on the
+    # freshly-written current-session.txt). Fall back to file on any
+    # failure so old daemons without the ``get_current_session`` op
+    # keep working.
+    current_session_id = await _query_daemon_session(agent_id, socket_path)
+    if current_session_id is not None:
+        logger.info(
+            "mcp_bridge: agent=%s current_session=%s (via socket IPC)",
+            agent_id,
+            current_session_id,
+        )
+    else:
+        # Fallback: file-based path (old daemon or socket unavailable).
+        current_session_id = _read_current_session(agent_id)
+        if current_session_id is not None:
+            logger.info(
+                "mcp_bridge: agent=%s current_session=%s (via file fallback)",
+                agent_id,
+                current_session_id,
+            )
+        else:
+            logger.warning(
+                "mcp_bridge: agent=%s current_session=None "
+                "(falling back to file IPC — socket miss + no file)",
+                agent_id,
+            )
+    server = build_server(
+        agent_id=agent_id,
+        socket_path=socket_path,
+        identity=identity,
+        session_id=current_session_id,
+    )
+    logger.info(
+        "mcp_bridge: ready agent=%s is_chief=%s — entering stdio loop",
+        agent_id,
+        identity.get("is_chief") is True,
+    )
+    await server.run_stdio_async()