multi-agent-platform 0.1.0__py3-none-any.whl

cli/agent_client.py

@@ -0,0 +1,554 @@
+"""Persistent in-process Claude SDK client with session resume.
+
+Used by map-runtime-waker (event-driven wake) and legacy bridges. The process
+holds ONE ``ClaudeSDKClient`` for its lifetime; ``claude_session_id`` is
+persisted in local state so the next restart resumes the same Claude session
+(via ``ClaudeAgentOptions(resume=...)``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal, Protocol, TypedDict
+
+from cli.session_wake_log import (
+    DEFAULT_SESSION_LOG_DIR,
+    append_session_event,
+    append_session_wake_log,
+    resolve_session_log_path,
+    text_summary,
+    tool_result_summary,
+    tool_use_summary,
+)
+
+logger = logging.getLogger("map.agent_client")
+
+DEFAULT_ALLOWED_TOOLS: list[str] = [
+    "Skill",
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Glob",
+    "Grep",
+    "TodoWrite",
+]
+
+_CREDENTIAL_ENV_KEYS: tuple[str, ...] = (
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_BASE_URL",
+)
+_MODEL_ENV_KEYS: tuple[str, ...] = ("ANTHROPIC_MODEL", "CLAUDE_MODEL")
+
+_EXPORT_RE = re.compile(r"^\s*export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+IntegrationMode = Literal["bridge", "waker", "manual"]
+
+
+class WakeUpEvent(TypedDict, total=False):
+    """Streamed wake-up event consumed by bridge / waker cycle logs."""
+
+    type: str  # "text" | "result" | "tool"
+    content: str
+    session_id: str
+    is_error: bool
+
+
+class PersonaAgentLike(Protocol):
+    """Minimal Claude SDK client surface used by PersonaAgentClient."""
+
+    async def connect(self, prompt: str | None = None) -> None: ...
+    async def disconnect(self) -> None: ...
+    async def query(self, prompt: str) -> None: ...
+    def receive_response(self) -> Any: ...
+
+
+class PersonaAgentClient:
+    """Per-persona persistent Claude SDK client with long-lived connection."""
+
+    def __init__(
+        self,
+        *,
+        persona: str,
+        state: dict[str, Any],
+        save_state_fn: Callable[[], None],
+        project_root: Path,
+        extra_env: dict[str, str] | None = None,
+        model: str | None = None,
+        allowed_tools: list[str] | None = None,
+        integration: IntegrationMode = "bridge",
+        session_log_dir: Path | None = None,
+        _client_factory: Callable[[Any], PersonaAgentLike] | None = None,
+        wake_timeout: float = 1800.0,
+    ) -> None:
+        self.persona = persona
+        self.state = state
+        self._save_state_fn = save_state_fn
+        self.project_root = project_root
+        self.extra_env = dict(extra_env or {})
+        self.model = model or self._resolve_model()
+        self.allowed_tools = list(allowed_tools or DEFAULT_ALLOWED_TOOLS)
+        self.integration = integration
+        self.session_log_dir = session_log_dir
+        # 单次 wake 内，两条 agent 消息之间的最大间隔（秒）。超过则判定 Agent
+        # Runtime 卡死并中断，避免 bridge / waker 永久阻塞在 receive_response()
+        # 上。合法长任务期间 Agent 会持续流式发消息，不会触发；真正挂起（网络
+        # 掉线、SDK 无响应）才会被超时打断。
+        self.wake_timeout = wake_timeout
+        self._client_factory = _client_factory
+        self._client: PersonaAgentLike | None = None
+        self._connected = False
+
+    async def connect(self) -> None:
+        if self._connected:
+            return
+        resume_session_id = self.state.get("claude_session_id")
+        options = self._build_options(resume=resume_session_id)
+        client = self._make_client(options)
+        await client.connect()
+        self._client = client
+        self._connected = True
+        logger.info(
+            "[%s] Claude SDK connected (resume=%s, integration=%s)",
+            self.persona,
+            resume_session_id or "<new>",
+            self.integration,
+        )
+
+    async def wake_up(
+        self,
+        prompt: str,
+        *,
+        on_event: Callable[[WakeUpEvent], None] | None = None,
+        event_id: str | None = None,
+        event_source: str = "polling",
+        fingerprint: str | None = None,
+    ) -> str:
+        if not self._connected or self._client is None:
+            await self.connect()
+        assert self._client is not None
+
+        from claude_agent_sdk import (
+            AssistantMessage,
+            ResultMessage,
+            TextBlock,
+            ToolResultBlock,
+            ToolUseBlock,
+            UserMessage,
+        )
+
+        resume_session_id = self.state.get("claude_session_id")
+        # Resolve the session log path up front so every event of this wake
+        # (wake/text/tool_use/tool_result/result) lands in one file, even when
+        # the real session_id only arrives with the ResultMessage. A long
+        # running turn is then observable live — a stuck agent shows up as the
+        # last event ts going stale.
+        pre_sid = resume_session_id or f"new-{datetime.now(UTC).strftime('%Y%m%dT%H%M%S%f')}"
+        log_path = resolve_session_log_path(self._resolve_session_log_dir(), pre_sid, self.persona)
+        self._log_event(
+            log_path,
+            event="wake",
+            summary=text_summary(prompt),
+            event_id=event_id,
+            event_source=event_source,
+            fingerprint=fingerprint,
+        )
+
+        await self._client.query(prompt)
+        result: ResultMessage | None = None
+        response_parts: list[str] = []
+        _response_iter = self._client.receive_response().__aiter__()
+        while True:
+            # 单步超时：两条 agent 消息之间最多等 wake_timeout 秒。Agent 流式
+            # 响应期间持续有消息；只有真正卡死（无任何消息）才超时中断，
+            # 防止 bridge / waker 永久阻塞在 receive_response() 上。
+            try:
+                msg = await asyncio.wait_for(
+                    _response_iter.__anext__(), timeout=self.wake_timeout
+                )
+            except StopAsyncIteration:
+                break
+            except TimeoutError:
+                self._log_event(
+                    log_path,
+                    event="timeout",
+                    summary=f"no agent message for {self.wake_timeout}s; aborting wake",
+                    event_id=event_id,
+                    event_source=event_source,
+                    fingerprint=fingerprint,
+                )
+                result = None
+                break
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock):
+                        response_parts.append(block.text)
+                        if on_event is not None:
+                            on_event({"type": "text", "content": block.text})
+                        self._log_event(
+                            log_path,
+                            event="text",
+                            summary=text_summary(block.text),
+                            event_id=event_id,
+                            event_source=event_source,
+                            fingerprint=fingerprint,
+                        )
+                    elif isinstance(block, ToolUseBlock):
+                        if on_event is not None:
+                            on_event(
+                                {
+                                    "type": "tool_use",
+                                    "name": block.name,
+                                    "content": tool_use_summary(block.name, block.input),
+                                }
+                            )
+                        self._log_event(
+                            log_path,
+                            event="tool_use",
+                            summary=tool_use_summary(block.name, block.input),
+                            event_id=event_id,
+                            event_source=event_source,
+                            fingerprint=fingerprint,
+                        )
+            elif isinstance(msg, UserMessage):
+                # UserMessage.content may be a plain str; only scan block lists.
+                if isinstance(msg.content, list):
+                    for block in msg.content:
+                        if isinstance(block, ToolResultBlock):
+                            if on_event is not None:
+                                on_event(
+                                    {
+                                        "type": "tool_result",
+                                        "is_error": bool(block.is_error),
+                                        "content": tool_result_summary(block.content, block.is_error),
+                                    }
+                                )
+                            self._log_event(
+                                log_path,
+                                event="tool_result",
+                                summary=tool_result_summary(block.content, block.is_error),
+                                event_id=event_id,
+                                event_source=event_source,
+                                fingerprint=fingerprint,
+                            )
+            elif isinstance(msg, ResultMessage):
+                result = msg
+                if on_event is not None:
+                    on_event(
+                        {
+                            "type": "result",
+                            "session_id": msg.session_id,
+                            "is_error": bool(getattr(msg, "is_error", False)),
+                        }
+                    )
+
+        if result is not None and getattr(result, "session_id", None):
+            new_sid = result.session_id
+            if new_sid != self.state.get("claude_session_id"):
+                self.state["claude_session_id"] = new_sid
+                self._save_state_fn()
+        if result is not None and getattr(result, "is_error", False):
+            status = "error"
+        elif result is None:
+            status = "no_response"
+        else:
+            status = "ok"
+
+        self.state["last_wakeup_at"] = datetime.now(UTC).isoformat()
+        self.state["last_wakeup_status"] = status
+        self._save_state_fn()
+
+        response_text = "".join(response_parts)
+        log_session_id = self._wake_log_session_id(result, resume_session_id)
+        # Result summary goes into the same file as the live events above; keep
+        # the A3-audit field set by routing through append_session_wake_log with
+        # the pre-resolved log_path.
+        self._append_wake_session_log(
+            session_id=log_session_id,
+            prompt=prompt,
+            response_text=response_text,
+            status=status,
+            event_id=event_id,
+            event_source=event_source,
+            fingerprint=fingerprint,
+            log_path=log_path,
+        )
+        return status
+
+    async def disconnect(self) -> None:
+        if self._client is None or not self._connected:
+            self._connected = False
+            return
+        try:
+            await self._client.disconnect()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("[%s] Claude SDK disconnect failed: %s", self.persona, exc)
+        finally:
+            self._client = None
+            self._connected = False
+
+    def _make_client(self, options: Any) -> PersonaAgentLike:
+        if self._client_factory is not None:
+            return self._client_factory(options)
+        from claude_agent_sdk import ClaudeSDKClient
+
+        return ClaudeSDKClient(options=options)
+
+    def _build_options(self, *, resume: str | None) -> Any:
+        from claude_agent_sdk import ClaudeAgentOptions
+
+        env = self._resolve_env()
+        append_prompt = self._system_append_prompt()
+        kwargs: dict[str, Any] = dict(
+            cwd=str(self.project_root),
+            setting_sources=["project"],
+            system_prompt={"type": "preset", "preset": "claude_code", "append": append_prompt},
+            allowed_tools=self.allowed_tools,
+            permission_mode="acceptEdits",
+            env=env,
+        )
+        if resume:
+            kwargs["resume"] = resume
+        if self.model:
+            kwargs["model"] = self.model
+        return ClaudeAgentOptions(**kwargs)
+
+    def _resolve_session_log_dir(self) -> Path:
+        if self.session_log_dir is not None:
+            return self.session_log_dir
+        override = os.environ.get("MAP_SESSION_WAKE_LOG_DIR", "").strip()
+        if override:
+            return Path(override)
+        return self.project_root / DEFAULT_SESSION_LOG_DIR
+
+    @staticmethod
+    def _wake_log_session_id(
+        result: Any,
+        resume_session_id: str | None,
+    ) -> str:
+        if result is not None and getattr(result, "session_id", None):
+            return str(result.session_id)
+        if resume_session_id:
+            return str(resume_session_id)
+        return f"unknown-{datetime.now(UTC).strftime('%Y%m%dT%H%M%S%fZ')}"
+
+    def _log_event(
+        self,
+        log_path: Path,
+        *,
+        event: str,
+        summary: str,
+        event_id: str | None = None,
+        event_source: str = "polling",
+        fingerprint: str | None = None,
+    ) -> None:
+        if os.environ.get("MAP_SESSION_WAKE_LOG", "1").strip().lower() in {
+            "0",
+            "false",
+            "no",
+            "off",
+        }:
+            return
+        try:
+            append_session_event(
+                log_path=log_path,
+                persona=self.persona,
+                integration=self.integration,
+                event=event,
+                summary=summary,
+                event_id=event_id,
+                event_source=event_source,
+                fingerprint=fingerprint,
+            )
+        except OSError as exc:
+            logger.warning("[%s] session event log write failed: %s", self.persona, exc)
+
+    def _append_wake_session_log(
+        self,
+        *,
+        session_id: str,
+        prompt: str,
+        response_text: str,
+        status: str,
+        event_id: str | None = None,
+        event_source: str = "polling",
+        fingerprint: str | None = None,
+        log_path: Path | None = None,
+    ) -> None:
+        if os.environ.get("MAP_SESSION_WAKE_LOG", "1").strip().lower() in {
+            "0",
+            "false",
+            "no",
+            "off",
+        }:
+            return
+        try:
+            append_session_wake_log(
+                log_dir=self._resolve_session_log_dir(),
+                session_id=session_id,
+                persona=self.persona,
+                integration=self.integration,
+                prompt=prompt,
+                response_text=response_text,
+                status=status,
+                event_id=event_id,
+                event_source=event_source,
+                fingerprint=fingerprint,
+                log_path=log_path,
+            )
+        except OSError as exc:
+            logger.warning("[%s] session wake log write failed: %s", self.persona, exc)
+
+    def _system_append_prompt(self) -> str:
+        if self.integration == "waker":
+            return (
+                f"You are the **{self.persona}** persona of the MAP (Multi-Agent Platform) "
+                "project. When woken by map-runtime-waker you receive a single wake event. "
+                f"Confirm identity with `map --persona {self.persona} persona whoami`, read "
+                f"latest work with `map --persona {self.persona} todos`, then handle only the "
+                "event in the wake prompt using the appropriate skill from `.cursor/skills/`. "
+                "Gather missing context via the `map` CLI; do not wait for the waker to supply "
+                "a full plan."
+            )
+        if self.integration == "manual":
+            return (
+                f"You are the **{self.persona}** persona of the MAP (Multi-Agent Platform) "
+                "project. A human operator resumed this session via `map runtime chat`. "
+                f"Use `map --persona {self.persona}` CLI and skills under `.cursor/skills/` "
+                "(topic-host, topic-participant, experiment-host, experiment-reviewer, "
+                "map-project-collab). Follow the operator's instructions for the current task. "
+                "Do not assume map-runtime-waker will send another wake for the same work item."
+            )
+        return (
+            f"You are the **{self.persona}** persona of the MAP (Multi-Agent Platform) "
+            "project. When woken up by the bridge, ALWAYS start by running "
+            f"`map --persona {self.persona} todos` to inspect pending work, then invoke "
+            "the appropriate skill from `.cursor/skills/` (topic-host, topic-participant, "
+            "topic-reviewer, experiment-host, or map-project-collab) to act on each item. "
+            "Do not wait for the bridge to feed you a complete plan; gather state "
+            "yourself via the `map` CLI."
+        )
+
+    def _resolve_env(self) -> dict[str, str]:
+        env: dict[str, str] = {}
+        for key in _CREDENTIAL_ENV_KEYS:
+            value = self._resolve_env_key(key)
+            if value:
+                env[key] = value
+        env.update(self.extra_env)
+        return env
+
+    def _resolve_env_key(self, name: str) -> str | None:
+        existing = os.environ.get(name, "").strip()
+        if existing:
+            return existing
+        for path in self._candidate_rc_files():
+            found = self._read_export(path, name)
+            if found:
+                return found
+        return None
+
+    def _resolve_model(self) -> str | None:
+        for key in _MODEL_ENV_KEYS:
+            value = self._resolve_env_key(key)
+            if value:
+                return value
+        return None
+
+    def _candidate_rc_files(self) -> list[Path]:
+        home = Path.home()
+        return [
+            self.project_root / ".map" / ".claude-env",
+            home / ".bashrc",
+            home / ".profile",
+            home / ".bash_profile",
+        ]
+
+    @staticmethod
+    def _read_export(path: Path, name: str) -> str | None:
+        if not path.is_file():
+            return None
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+        for line in text.splitlines():
+            match = _EXPORT_RE.match(line)
+            if match and match.group(1) == name:
+                value = match.group(2).strip()
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+                    value = value[1:-1]
+                elif value and value[0] not in {"'", '"'}:
+                    value = re.sub(r"\s+#.*$", "", value).strip()
+                if value:
+                    return value
+        return None
+
+
+def make_wakeup_prompt(persona: str, todos: dict[str, Any]) -> str:
+    """Build a brief bridge wake-up prompt from a todos snapshot."""
+    lines = [
+        f"You are the **{persona}** persona of MAP.",
+        "",
+        "You have pending work. Inspect it, then act:",
+        "",
+        f"  $ map --persona {persona} todos",
+        "",
+    ]
+    pending_replies = todos.get("pending_replies") or []
+    pending_topic_replies = todos.get("pending_topic_replies") or []
+    pending_reviews = todos.get("pending_reviews") or []
+    my_open_experiments = todos.get("my_open_experiments") or []
+    my_open_topics = todos.get("my_open_topics") or []
+    mentions = todos.get("mentions") or []
+
+    if pending_replies:
+        lines.append(f"- {len(pending_replies)} pending review reply(ies)")
+    if pending_topic_replies:
+        lines.append(f"- {len(pending_topic_replies)} pending topic reply(ies)")
+    if pending_reviews:
+        lines.append(f"- {len(pending_reviews)} pending review(s)")
+    if my_open_experiments:
+        lines.append(f"- {len(my_open_experiments)} open experiment(s)")
+    if my_open_topics:
+        lines.append(f"- {len(my_open_topics)} open topic(s)")
+    if mentions:
+        lines.append(f"- {len(mentions)} mention(s)")
+    if not any(
+        [
+            pending_replies,
+            pending_topic_replies,
+            pending_reviews,
+            my_open_experiments,
+            my_open_topics,
+            mentions,
+        ]
+    ):
+        lines.append("(no pending items — short-circuit and report idle)")
+
+    lines.extend(
+        [
+            "",
+            "Use the appropriate skill from `.cursor/skills/` (topic-host, "
+            "topic-participant, topic-reviewer, experiment-host, or "
+            "map-project-collab). Report a brief status when done.",
+        ]
+    )
+    return "\n".join(lines)
+
+
+__all__ = [
+    "DEFAULT_ALLOWED_TOOLS",
+    "IntegrationMode",
+    "PersonaAgentClient",
+    "PersonaAgentLike",
+    "WakeUpEvent",
+    "make_wakeup_prompt",
+]

cli/bridge_state.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from cli.host_worker_types import WorkerError
+
+
+def load_bridge_state(
+    path: Path | None,
+    *,
+    bridge_name: str,
+    default_collections: tuple[str, ...],
+    validate_schema: bool = True,
+) -> dict[str, Any]:
+    if path is None or not path.exists():
+        return _default_state(default_collections)
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise WorkerError(f"Invalid {bridge_name} bridge state file: {path}") from exc
+    if not isinstance(state, dict):
+        raise WorkerError(f"Invalid {bridge_name} bridge state file: {path}")
+    if validate_schema and state.get("schema_version", 1) != 1:
+        raise WorkerError(f"Unsupported {bridge_name} bridge state schema: {state.get('schema_version')}")
+    state.setdefault("schema_version", 1)
+    for collection in default_collections:
+        state.setdefault(collection, {})
+    return state
+
+
+def save_bridge_state(path: Path | None, state: dict[str, Any]) -> None:
+    if path is None:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(json.dumps(state, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    tmp_path.replace(path)
+
+
+def _default_state(default_collections: tuple[str, ...]) -> dict[str, Any]:
+    return {"schema_version": 1, **{collection: {} for collection in default_collections}}

cli/commands/__init__.py

@@ -0,0 +1,13 @@
+"""cli.commands — sub-app command modules (arch experiment 0519e2a3 PR3+).
+
+Each module in this package owns one Typer ``*_app`` sub-application
+(``agent_app``, ``topic_app``, etc.) and registers its commands. The
+parent ``cli/main.py`` only does ``app.add_typer(..., name=...)`` to
+expose them under the user-visible ``map <name> ...`` path.
+
+Helpers (``_run``, ``_client_ctx``, ``_print_json``, ``_cli_options``)
+live in ``cli/main.py`` and are imported lazily inside command bodies
+to keep ``cli.main`` importable without instantiating the sub-apps
+(avoids the circular import: ``cli.main → cli.commands.agent →
+cli.main._run``).
+"""