@opengsd/gsd-pi 1.3.0 → 1.4.0

package/integrations/hermes/open_gsd_hermes/gsd_client.py

@@ -0,0 +1,269 @@
+"""Persistent gsd-mcp-server MCP client (stdio JSON-RPC)."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from packaging import version
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.types import ProgressSnapshot, SessionStatus
+
+
+class GsdVersionError(Exception):
+    pass
+
+
+class McpProtocolError(Exception):
+    pass
+
+
+@dataclass
+class _CacheEntry:
+    value: Any
+    expires_at: float
+
+
+class GsdMcpClient:
+    """JSON-RPC client for gsd-mcp-server with TTL cache for read tools."""
+
+    def __init__(self, config: GsdConfig) -> None:
+        self._config = config
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._lock = threading.Lock()
+        self._request_id = 0
+        self._cache: dict[str, _CacheEntry] = {}
+        self._version_checked = False
+
+    def _env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        env["GSD_CLI_PATH"] = self._config.cli_path
+        return env
+
+    def ensure_version(self) -> None:
+        if self._version_checked:
+            return
+        result = subprocess.run(
+            [self._config.cli_path, "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+        out = (result.stdout or result.stderr or "").strip()
+        # gsd --version may print "1.0.2" or "gsd 1.0.2"
+        ver_str = out.split()[-1] if out else "0"
+        try:
+            ver = version.parse(ver_str)
+        except version.InvalidVersion as e:
+            raise GsdVersionError(f"Could not parse gsd version from: {out!r}") from e
+        min_v = version.parse(self._config.gsd_version_min)
+        max_v = version.parse(self._config.gsd_version_max)
+        if ver < min_v or ver >= max_v:
+            raise GsdVersionError(
+                f"gsd {ver} not in supported range "
+                f">={self._config.gsd_version_min},<{self._config.gsd_version_max}"
+            )
+        self._version_checked = True
+
+    def _ensure_process(self) -> subprocess.Popen[bytes]:
+        if self._proc is not None and self._proc.poll() is None:
+            return self._proc
+        self._proc = subprocess.Popen(
+            [self._config.mcp_server_path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env=self._env(),
+        )
+        self._initialize()
+        return self._proc
+
+    def _send(self, payload: dict[str, Any]) -> None:
+        proc = self._ensure_process()
+        assert proc.stdin is not None
+        body = json.dumps(payload).encode("utf-8")
+        header = f"Content-Length: {len(body)}\r\n\r\n".encode("ascii")
+        proc.stdin.write(header + body)
+        proc.stdin.flush()
+
+    def _read_message(self) -> dict[str, Any]:
+        proc = self._ensure_process()
+        assert proc.stdout is not None
+        headers: dict[str, str] = {}
+        while True:
+            line = proc.stdout.readline()
+            if not line:
+                raise McpProtocolError("MCP server closed stdout")
+            decoded = line.decode("utf-8").strip()
+            if decoded == "":
+                break
+            key, _, val = decoded.partition(":")
+            headers[key.strip().lower()] = val.strip()
+        length = int(headers.get("content-length", "0"))
+        body = proc.stdout.read(length)
+        return json.loads(body.decode("utf-8"))
+
+    def _initialize(self) -> None:
+        self._request_id += 1
+        self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": self._request_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "open-gsd-hermes", "version": "1.2.0"},
+                },
+            }
+        )
+        _ = self._read_message()
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def _call_tool(
+        self, name: str, arguments: dict[str, Any], *, check_version: bool = True
+    ) -> dict[str, Any]:
+        with self._lock:
+            if check_version:
+                self.ensure_version()
+            self._request_id += 1
+            req_id = self._request_id
+            self._send(
+                {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "method": "tools/call",
+                    "params": {"name": name, "arguments": arguments},
+                }
+            )
+            while True:
+                msg = self._read_message()
+                if msg.get("id") == req_id:
+                    if "error" in msg:
+                        raise McpProtocolError(str(msg["error"]))
+                    result = msg.get("result") or {}
+                    content = result.get("content") or []
+                    if not content:
+                        return {}
+                    text = content[0].get("text", "{}")
+                    if result.get("isError"):
+                        raise McpProtocolError(text)
+                    return json.loads(text) if isinstance(text, str) else text
+
+    def _cached(self, key: str, fetch: Any) -> Any:
+        now = time.monotonic()
+        entry = self._cache.get(key)
+        if entry and entry.expires_at > now:
+            return entry.value
+        value = fetch()
+        self._cache[key] = _CacheEntry(
+            value=value,
+            expires_at=now + self._config.cache_ttl_seconds,
+        )
+        return value
+
+    def invalidate_cache(self, project_dir: str | None = None) -> None:
+        if project_dir is None:
+            self._cache.clear()
+            return
+        self._cache.pop(f"progress:{project_dir}", None)
+
+    def _read_progress_cli(self, project_dir: str) -> ProgressSnapshot:
+        """Read progress via `gsd read progress --json` (6c hot path)."""
+        result = subprocess.run(
+            [
+                self._config.cli_path,
+                "read",
+                "progress",
+                "--json",
+                "--project",
+                project_dir,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=60,
+            env=self._env(),
+        )
+        if result.returncode != 0:
+            raise McpProtocolError(
+                (result.stderr or result.stdout or "gsd read progress failed").strip()
+            )
+        envelope = json.loads(result.stdout)
+        data = envelope.get("data") or {}
+        return ProgressSnapshot.from_mcp(data)
+
+    def progress(self, project_dir: str) -> ProgressSnapshot:
+        def fetch() -> ProgressSnapshot:
+            try:
+                self.ensure_version()
+                return self._read_progress_cli(project_dir)
+            except (
+                GsdVersionError,
+                McpProtocolError,
+                json.JSONDecodeError,
+                AttributeError,
+                TypeError,
+                KeyError,
+                OSError,
+                subprocess.TimeoutExpired,
+            ):
+                data = self._call_tool(
+                    "gsd_progress",
+                    {"projectDir": project_dir},
+                    check_version=False,
+                )
+                return ProgressSnapshot.from_mcp(data)
+
+        key = f"progress:{project_dir}"
+        return self._cached(key, fetch)
+
+    def status(self, session_id: str) -> SessionStatus:
+        data = self._call_tool("gsd_status", {"sessionId": session_id})
+        return SessionStatus.from_mcp(data)
+
+    def execute(self, project_dir: str, *, command: str = "/gsd auto") -> dict[str, Any]:
+        self.invalidate_cache(project_dir)
+        return self._call_tool(
+            "gsd_execute",
+            {"projectDir": project_dir, "command": command},
+        )
+
+    def cancel(self, *, session_id: str | None = None, project_dir: str | None = None) -> dict[str, Any]:
+        args: dict[str, Any] = {}
+        if session_id:
+            args["sessionId"] = session_id
+        if project_dir:
+            args["projectDir"] = project_dir
+        return self._call_tool("gsd_cancel", args)
+
+    def cancel_by_project(self, project_dir: str) -> dict[str, Any]:
+        return self._call_tool("gsd_cancel_by_project", {"projectDir": project_dir})
+
+    def resolve_blocker(self, session_id: str, response: str) -> dict[str, Any]:
+        return self._call_tool(
+            "gsd_resolve_blocker",
+            {"sessionId": session_id, "response": response},
+        )
+
+    def memory_query(self, project_dir: str, query: str) -> dict[str, Any]:
+        return self._call_tool(
+            "gsd_memory_query",
+            {"projectDir": project_dir, "query": query},
+        )
+
+    def close(self) -> None:
+        if self._proc and self._proc.poll() is None:
+            self._proc.terminate()
+            try:
+                self._proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+        self._proc = None

package/integrations/hermes/open_gsd_hermes/inject.py

@@ -0,0 +1,31 @@
+"""pre_llm_call hook — inject live GSD project snapshot."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from open_gsd_hermes.binding import BindingError, resolve_project_dir
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.snapshot import format_snapshot
+from open_gsd_hermes.types import BindingContext
+
+
+def make_pre_llm_call_handler(
+    config: GsdConfig,
+    client: GsdMcpClient,
+    get_binding_ctx: Callable[[], BindingContext],
+) -> Callable[..., dict[str, str]]:
+    """Return Hermes pre_llm_call hook that injects compact project context."""
+
+    def pre_llm_call(**_kwargs: Any) -> dict[str, str]:
+        try:
+            project_dir = resolve_project_dir(config, get_binding_ctx())
+            progress = client.progress(project_dir)
+            return {"context": format_snapshot(progress)}
+        except BindingError as e:
+            return {"context": f"## GSD\n{e}"}
+        except Exception as e:
+            return {"context": f"## GSD\n(snapshot unavailable: {e})"}
+
+    return pre_llm_call

package/integrations/hermes/open_gsd_hermes/memory.py

@@ -0,0 +1,66 @@
+"""MemoryProvider — federated read, GSD-authoritative write (6c)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.gsd_client import GsdMcpClient
+
+
+class MemoryProvider(Protocol):
+    def prefetch(self, project_dir: str, query: str | None = None) -> str: ...
+
+
+class GsdMemoryProvider:
+    """
+    Federated memory prefetch:
+    - GSD memories via gsd_memory_query (authoritative)
+    - Optional read-only Hermes MEMORY.md snippet
+    Writes go only to GSD (via MCP tools), never to Hermes memory files.
+    """
+
+    def __init__(
+        self,
+        config: GsdConfig,
+        client: GsdMcpClient,
+        *,
+        read_cli_path: str | None = None,
+    ) -> None:
+        self._config = config
+        self._client = client
+        self._read_cli = read_cli_path or config.cli_path
+
+    def prefetch(self, project_dir: str, query: str | None = None) -> str:
+        sections: list[str] = []
+        if query and len(query) >= 2:
+            try:
+                data = self._client.memory_query(project_dir, query)
+                memories = data.get("memories")
+                if memories is None:
+                    memories = data.get("results")
+                if memories is None:
+                    memories = data
+                if memories:
+                    gsd_section = ["## GSD memories"]
+                    if isinstance(memories, list):
+                        for m in memories[:8]:
+                            if isinstance(m, dict):
+                                gsd_section.append(f"- {m.get('content', m)}")
+                            else:
+                                gsd_section.append(f"- {m}")
+                    else:
+                        gsd_section.append(str(memories)[:2000])
+                    sections.append("\n".join(gsd_section))
+            except Exception as e:
+                sections.append(f"## GSD memories\n(unavailable: {e})")
+
+        hermes_path = self._config.hermes_memory_path
+        if hermes_path:
+            p = Path(hermes_path).expanduser()
+            if p.is_file():
+                text = p.read_text(encoding="utf-8")[:1500]
+                sections.append("## Hermes MEMORY.md (read-only)\n" + text)
+
+        return "\n\n".join(sections) if sections else ""

package/integrations/hermes/open_gsd_hermes/notifications.py

@@ -0,0 +1,71 @@
+"""Gateway notifications via ctx.dispatch_tool('send_message', ...)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.types import DeliveryTarget, PluginContext, SessionStatus
+
+
+class NotificationService:
+    """Format and send supervisor notifications to the gateway."""
+
+    def __init__(
+        self,
+        ctx: PluginContext,
+        config: GsdConfig,
+        get_target: Callable[[], DeliveryTarget | None],
+        dispatch: Callable[[str, dict[str, Any]], Any] | None = None,
+    ) -> None:
+        self._ctx = ctx
+        self._config = config
+        self._get_target = get_target
+        self._dispatch = dispatch or ctx.dispatch_tool
+
+    def _should_send(self, kind: str) -> bool:
+        level = self._config.notification_level
+        if level == "verbose":
+            return True
+        if level == "quiet":
+            return kind in ("blocker", "failure", "complete")
+        # normal
+        return kind in ("blocker", "transition", "failure", "complete")
+
+    def send(self, text: str, *, kind: str = "transition") -> bool:
+        if not self._should_send(kind):
+            return False
+        target = self._get_target()
+        if target is None:
+            return False
+        payload = {
+            "platform": target.platform,
+            "chat_type": target.chat_type,
+            "chat_id": target.chat_id,
+            "text": text,
+        }
+        try:
+            self._dispatch("send_message", payload)
+            return True
+        except Exception:
+            return False
+
+    def notify_blocker(self, status: SessionStatus) -> None:
+        blocker = status.pending_blocker or {}
+        q = blocker.get("question") or blocker.get("prompt") or "Action required"
+        self.send(f"🚧 GSD blocker: {q}\nReply with `/gsd reply <your answer>`", kind="blocker")
+
+    def notify_transition(self, message: str) -> None:
+        self.send(f"📋 GSD: {message}", kind="transition")
+
+    def notify_terminal(self, status: str, error: str | None = None) -> None:
+        normalized_status = status.lower()
+        if normalized_status in ("complete", "completed", "done"):
+            self.send("✅ GSD auto mode finished.", kind="complete")
+        elif normalized_status == "cancelled":
+            self.send("⏹ GSD session cancelled.", kind="complete")
+        else:
+            msg = f"❌ GSD session {status}"
+            if error:
+                msg += f": {error}"
+            self.send(msg, kind="failure")

package/integrations/hermes/open_gsd_hermes/snapshot.py

@@ -0,0 +1,42 @@
+"""Format ProgressResult into compact pre_llm_call context (~15 lines)."""
+
+from __future__ import annotations
+
+from open_gsd_hermes.formatting import format_ref
+from open_gsd_hermes.types import ProgressSnapshot
+
+
+def format_snapshot(progress: ProgressSnapshot) -> str:
+    """Compact GSD project snapshot for pre_llm_call injection."""
+    lines = [
+        "## GSD Project Snapshot",
+        f"Phase: {progress.phase}",
+        f"Active milestone: {format_ref(progress.active_milestone)}",
+        f"Active slice: {format_ref(progress.active_slice)}",
+        f"Active task: {format_ref(progress.active_task)}",
+    ]
+    if progress.milestones:
+        m = progress.milestones
+        lines.append(
+            f"Milestones: {m.get('done', 0)}/{m.get('total', 0)} done "
+            f"({m.get('active', 0)} active)"
+        )
+    if progress.slices and progress.slices.get("total", 0) > 0:
+        s = progress.slices
+        lines.append(f"Slices: {s.get('done', 0)}/{s.get('total', 0)} done")
+    if progress.tasks and progress.tasks.get("total", 0) > 0:
+        t = progress.tasks
+        lines.append(f"Tasks: {t.get('done', 0)}/{t.get('total', 0)} done")
+    if progress.requirements:
+        r = progress.requirements
+        lines.append(
+            f"Requirements: {r.get('active', 0)} active, "
+            f"{r.get('validated', 0)} validated"
+        )
+    if progress.blockers:
+        lines.append("Blockers:")
+        for b in progress.blockers[:3]:
+            lines.append(f"  - {b}")
+    if progress.next_action:
+        lines.append(f"Next: {progress.next_action}")
+    return "\n".join(lines[:15])

package/integrations/hermes/open_gsd_hermes/supervisor.py

@@ -0,0 +1,180 @@
+"""Background supervisor — poll gsd_status, diff progress, notify transitions."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.formatting import format_ref
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.notifications import NotificationService
+from open_gsd_hermes.types import ProgressSnapshot, SessionStatus
+
+
+class SupervisorState(str, Enum):
+    IDLE = "idle"
+    RUNNING = "running"
+    BLOCKED = "blocked"
+    COMPLETE = "complete"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+TERMINAL = frozenset(
+    {
+        SupervisorState.COMPLETE,
+        SupervisorState.FAILED,
+        SupervisorState.CANCELLED,
+    }
+)
+
+
+@dataclass
+class SupervisorContext:
+    session_id: str | None = None
+    project_dir: str | None = None
+    state: SupervisorState = SupervisorState.IDLE
+    last_progress: ProgressSnapshot | None = None
+    last_status: SessionStatus | None = None
+    pending_blocker_id: str | None = None
+    notified_terminal: bool = False
+
+
+class SupervisorFsm:
+    """Poll loop with transition detection for unit/blocker/terminal changes."""
+
+    def __init__(
+        self,
+        config: GsdConfig,
+        client: GsdMcpClient,
+        notifications: NotificationService,
+        get_context: Callable[[], SupervisorContext],
+        set_context: Callable[[SupervisorContext], None],
+    ) -> None:
+        self._config = config
+        self._client = client
+        self._notifications = notifications
+        self._get_context = get_context
+        self._set_context = set_context
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._loop,
+            args=(self._stop,),
+            daemon=True,
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread and self._thread is not threading.current_thread():
+            self._thread.join(timeout=5)
+        self._thread = None
+
+    def _loop(self, stop_event: threading.Event) -> None:
+        try:
+            while not stop_event.is_set():
+                try:
+                    self._tick(stop_event)
+                except Exception:
+                    pass
+                stop_event.wait(self._config.poll_interval_seconds)
+        finally:
+            if self._thread is threading.current_thread():
+                self._thread = None
+
+    def _tick(self, stop_event: threading.Event | None = None) -> None:
+        if stop_event is None:
+            stop_event = self._stop
+        ctx = self._get_context()
+        if not ctx.session_id or not ctx.project_dir:
+            return
+
+        status = self._client.status(ctx.session_id)
+        try:
+            progress = self._client.progress(ctx.project_dir)
+        except Exception:
+            progress = None
+        ctx.last_status = status
+        blocker_notification: SessionStatus | None = None
+        terminal_notification: tuple[str, str | None] | None = None
+
+        new_state = self._map_status(status.status)
+        pending_blocker_id = (
+            (status.pending_blocker or {}).get("id")
+            or (status.pending_blocker or {}).get("blockerId")
+        )
+        if (
+            status.pending_blocker
+            and new_state not in TERMINAL
+            and new_state != SupervisorState.BLOCKED
+        ):
+            new_state = SupervisorState.BLOCKED
+
+        if new_state != ctx.state:
+            ctx.state = new_state
+            if new_state == SupervisorState.BLOCKED:
+                blocker_notification = status
+            elif new_state in TERMINAL and not ctx.notified_terminal:
+                ctx.notified_terminal = True
+                terminal_notification = (status.status, status.error)
+        elif (
+            new_state == SupervisorState.BLOCKED
+            and pending_blocker_id
+            and pending_blocker_id != ctx.pending_blocker_id
+        ):
+            blocker_notification = status
+
+        if new_state == SupervisorState.BLOCKED:
+            ctx.pending_blocker_id = pending_blocker_id
+
+        if progress is not None:
+            self._diff_progress(ctx, progress)
+            ctx.last_progress = progress
+        if terminal_notification:
+            stop_event.set()
+        self._set_context(ctx)
+        if blocker_notification:
+            self._notifications.notify_blocker(blocker_notification)
+        if terminal_notification:
+            self._notifications.notify_terminal(*terminal_notification)
+
+    def _map_status(self, raw: str) -> SupervisorState:
+        mapping = {
+            "running": SupervisorState.RUNNING,
+            "blocked": SupervisorState.BLOCKED,
+            "complete": SupervisorState.COMPLETE,
+            "completed": SupervisorState.COMPLETE,
+            "done": SupervisorState.COMPLETE,
+            "failed": SupervisorState.FAILED,
+            "error": SupervisorState.FAILED,
+            "cancelled": SupervisorState.CANCELLED,
+        }
+        return mapping.get(raw.lower(), SupervisorState.RUNNING)
+
+    def _diff_progress(
+        self, ctx: SupervisorContext, progress: ProgressSnapshot
+    ) -> None:
+        prev = ctx.last_progress
+        if prev is None:
+            return
+        parts: list[str] = []
+        for label, old, new in (
+            ("milestone", prev.active_milestone, progress.active_milestone),
+            ("slice", prev.active_slice, progress.active_slice),
+            ("task", prev.active_task, progress.active_task),
+        ):
+            if old != new and new:
+                parts.append(f"{label} → {format_ref(new, include_title=False)}")
+        if parts:
+            self._notifications.notify_transition(", ".join(parts))
+            self._client.invalidate_cache(ctx.project_dir)