@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/integrations/hermes/open_gsd_hermes/commands.py

@@ -0,0 +1,186 @@
+"""`/gsd` slash command router — bind, status, auto, cancel, reply."""
+
+from __future__ import annotations
+
+import shlex
+from typing import Any, Callable
+
+from open_gsd_hermes.binding import (
+    BindingError,
+    SessionBindStore,
+    resolve_explicit_project_dir,
+    resolve_project_dir,
+)
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.notifications import NotificationService
+from open_gsd_hermes.snapshot import format_snapshot
+from open_gsd_hermes.supervisor import SupervisorContext, SupervisorFsm, SupervisorState
+from open_gsd_hermes.types import BindingContext
+
+
+class GsdCommandRouter:
+    def __init__(
+        self,
+        config: GsdConfig,
+        client: GsdMcpClient,
+        bind_store: SessionBindStore,
+        supervisor: SupervisorFsm,
+        get_session_key: Callable[[], str],
+        get_binding_ctx: Callable[[], BindingContext],
+        get_supervisor_ctx: Callable[[], SupervisorContext],
+        set_supervisor_ctx: Callable[[SupervisorContext], None],
+        get_platform_channel: Callable[[], tuple[str | None, str | None]],
+        notifications: NotificationService | None = None,
+    ) -> None:
+        self._config = config
+        self._client = client
+        self._bind_store = bind_store
+        self._supervisor = supervisor
+        self._get_session_key = get_session_key
+        self._get_binding_ctx = get_binding_ctx
+        self._get_supervisor_ctx = get_supervisor_ctx
+        self._set_supervisor_ctx = set_supervisor_ctx
+        self._get_platform_channel = get_platform_channel
+        self._notifications = notifications
+
+    async def handle(self, args: str = "", **_kwargs: Any) -> str:
+        try:
+            tokens = shlex.split(args) if args else []
+        except ValueError as e:
+            return f"Invalid arguments: {e}"
+        sub = (tokens[0] if tokens else "help").lower()
+        rest = tokens[1:]
+
+        handlers = {
+            "bind": self._cmd_bind,
+            "status": self._cmd_status,
+            "auto": self._cmd_auto,
+            "cancel": self._cmd_cancel,
+            "reply": self._cmd_reply,
+            "help": self._cmd_help,
+        }
+        handler = handlers.get(sub, self._cmd_help)
+        return await handler(rest)
+
+    async def _cmd_help(self, _rest: list[str]) -> str:
+        return (
+            "**GSD commands**\n"
+            "- `/gsd bind <path>` — bind this chat to a project\n"
+            "- `/gsd status` — show progress snapshot\n"
+            "- `/gsd auto` — start auto mode (MCP)\n"
+            "- `/gsd cancel` — cancel running session\n"
+            "- `/gsd reply <text>` — resolve blocker"
+        )
+
+    def _binding_ctx(self, slash_path: str | None = None) -> BindingContext:
+        sk = self._get_session_key()
+        platform, channel = self._get_platform_channel()
+        base = self._get_binding_ctx()
+        return BindingContext(
+            slash_path=slash_path,
+            session_bind=self._bind_store.get(sk) or base.session_bind,
+            platform=platform or base.platform,
+            channel_id=channel or base.channel_id,
+            cron_project=base.cron_project,
+            cwd=base.cwd,
+        )
+
+    async def _cmd_bind(self, rest: list[str]) -> str:
+        if not rest:
+            return "Usage: `/gsd bind <project-path>`"
+        path = rest[0]
+        sk = self._get_session_key()
+        try:
+            project_dir = resolve_explicit_project_dir(path)
+        except BindingError as e:
+            return str(e)
+        self._bind_store.set(sk, project_dir)
+        self._client.invalidate_cache(project_dir)
+        return f"Bound to `{project_dir}`"
+
+    async def _cmd_status(self, _rest: list[str]) -> str:
+        try:
+            project_dir = resolve_project_dir(
+                self._config, self._binding_ctx()
+            )
+            progress = self._client.progress(project_dir)
+            return format_snapshot(progress)
+        except BindingError as e:
+            return str(e)
+        except Exception as e:
+            return f"GSD status unavailable: {e}"
+
+    async def _cmd_auto(self, _rest: list[str]) -> str:
+        try:
+            project_dir = resolve_project_dir(
+                self._config, self._binding_ctx()
+            )
+        except BindingError as e:
+            return str(e)
+        try:
+            result = self._client.execute(project_dir)
+        except Exception as e:
+            return f"Could not start GSD auto mode: {e}"
+        session_id = result.get("sessionId") or result.get("session_id")
+        if not session_id:
+            return "Could not start GSD auto mode: missing session ID"
+        self._supervisor.stop()
+        ctx = self._get_supervisor_ctx()
+        ctx.session_id = session_id
+        ctx.project_dir = project_dir
+        ctx.state = SupervisorState.RUNNING
+        ctx.last_progress = None
+        ctx.last_status = None
+        ctx.pending_blocker_id = None
+        ctx.notified_terminal = False
+        self._set_supervisor_ctx(ctx)
+        self._supervisor.start()
+        return f"Started GSD auto mode (session `{session_id}`)"
+
+    async def _cmd_cancel(self, _rest: list[str]) -> str:
+        ctx = self._get_supervisor_ctx()
+        try:
+            try:
+                if ctx.session_id and ctx.project_dir:
+                    project_dir = resolve_explicit_project_dir(ctx.project_dir)
+                else:
+                    project_dir = resolve_project_dir(
+                        self._config, self._binding_ctx()
+                    )
+            except BindingError as e:
+                result = str(e)
+            else:
+                try:
+                    if ctx.session_id:
+                        self._client.cancel(
+                            session_id=ctx.session_id, project_dir=project_dir
+                        )
+                    else:
+                        self._client.cancel_by_project(project_dir)
+                except Exception as e:
+                    result = f"Cancel request failed: {e}"
+                else:
+                    if self._notifications is not None:
+                        self._notifications.notify_terminal("cancelled")
+                        ctx.notified_terminal = True
+                    result = "Cancel requested."
+        finally:
+            self._supervisor.stop()
+            ctx.state = SupervisorState.CANCELLED
+            self._set_supervisor_ctx(ctx)
+        return result
+
+    async def _cmd_reply(self, rest: list[str]) -> str:
+        if not rest:
+            return "Usage: `/gsd reply <your answer>`"
+        text = " ".join(rest)
+        ctx = self._get_supervisor_ctx()
+        if not ctx.session_id:
+            return "No active GSD session. Run `/gsd auto` first."
+        try:
+            self._client.resolve_blocker(ctx.session_id, text)
+            self._client.invalidate_cache(ctx.project_dir)
+        except Exception as e:
+            return f"Could not send blocker response: {e}"
+        return "Blocker response sent."

package/integrations/hermes/open_gsd_hermes/config.py

@@ -0,0 +1,59 @@
+"""Load ~/.hermes/gsd.yaml configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class GsdConfig:
+    cli_path: str = "gsd"
+    mcp_server_path: str = "gsd-mcp-server"
+    credential_source: str = "gsd"
+    default_project: str | None = None
+    bindings: dict[str, dict[str, str]] = field(default_factory=dict)
+    poll_interval_seconds: int = 12
+    cache_ttl_seconds: int = 45
+    notification_level: str = "normal"
+    gsd_version_min: str = "2.53"
+    gsd_version_max: str = "3.0"
+    hermes_memory_path: str | None = None
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> GsdConfig:
+        gsd = raw.get("gsd") or raw
+        return cls(
+            cli_path=str(gsd.get("cli_path", "gsd")),
+            mcp_server_path=str(gsd.get("mcp_server_path", "gsd-mcp-server")),
+            credential_source=str(gsd.get("credential_source", "gsd")),
+            default_project=gsd.get("default_project"),
+            bindings=dict(gsd.get("bindings") or {}),
+            poll_interval_seconds=int(gsd.get("poll_interval_seconds", 12)),
+            cache_ttl_seconds=int(gsd.get("cache_ttl_seconds", 45)),
+            notification_level=str(gsd.get("notification_level", "normal")),
+            gsd_version_min=str(gsd.get("gsd_version_min", "2.53")),
+            gsd_version_max=str(gsd.get("gsd_version_max", "3.0")),
+            hermes_memory_path=gsd.get("hermes_memory_path"),
+        )
+
+
+def config_path() -> Path:
+    explicit = os.environ.get("HERMES_GSD_CONFIG")
+    if explicit:
+        return Path(explicit).expanduser()
+    hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+    return hermes_home.expanduser() / "gsd.yaml"
+
+
+def load_config(path: Path | None = None) -> GsdConfig:
+    cfg_path = path or config_path()
+    if not cfg_path.exists():
+        return GsdConfig()
+    with cfg_path.open(encoding="utf-8") as f:
+        data = yaml.safe_load(f) or {}
+    return GsdConfig.from_dict(data)

package/integrations/hermes/open_gsd_hermes/credentials.py

@@ -0,0 +1,51 @@
+"""Hermes credential passthrough for MCP sidecar and headless (6b)."""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+# Allowlisted env vars when credential_source is "hermes"
+HERMES_CRED_ALLOWLIST = frozenset(
+    {
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GEMINI_API_KEY",
+        "OPENROUTER_API_KEY",
+        "GROQ_API_KEY",
+    }
+)
+
+
+class CredentialPassthrough:
+    """Map Hermes-resolved credentials to subprocess env."""
+
+    def __init__(
+        self,
+        source: str,
+        hermes_creds: Mapping[str, str] | None = None,
+    ) -> None:
+        self._source = source
+        self._hermes_creds = dict(hermes_creds or {})
+
+    def apply(self, base_env: dict[str, str] | None = None) -> dict[str, str]:
+        env = dict(base_env or os.environ)
+        if self._source != "hermes":
+            return env
+        for key, value in self._hermes_creds.items():
+            if key in HERMES_CRED_ALLOWLIST and value:
+                env[key] = value
+        return env
+
+    def validate(self) -> list[str]:
+        """Return warnings when hermes source is selected but no creds mapped."""
+        if self._source != "hermes":
+            return []
+        missing = [k for k in HERMES_CRED_ALLOWLIST if not self._hermes_creds.get(k)]
+        if len(missing) == len(HERMES_CRED_ALLOWLIST):
+            return [
+                "credential_source=hermes but no allowlisted keys provided; "
+                "falling back to gsd environment"
+            ]
+        return []

package/integrations/hermes/open_gsd_hermes/cron.py

@@ -0,0 +1,85 @@
+"""Cron integration — gsd headless auto --json with explicit project_dir."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from open_gsd_hermes.config import GsdConfig, load_config
+from open_gsd_hermes.credentials import CredentialPassthrough
+
+
+@dataclass
+class CronResult:
+    exit_code: int
+    output: dict[str, Any] | str
+    project_dir: str
+
+
+def run_headless_auto(
+    project_dir: str,
+    config: GsdConfig | None = None,
+    *,
+    timeout_seconds: int = 3600,
+    hermes_creds: dict[str, str] | None = None,
+) -> CronResult:
+    """Run `gsd headless auto --json` for scheduled Hermes cron jobs."""
+    cfg = config or load_config()
+    project = str(Path(project_dir).expanduser().resolve())
+    creds = CredentialPassthrough(cfg.credential_source, hermes_creds)
+    env = creds.apply()
+    cmd = [
+        cfg.cli_path,
+        "headless",
+        "auto",
+        "--json",
+        "--timeout",
+        str(timeout_seconds * 1000),
+    ]
+    result = subprocess.run(
+        cmd,
+        cwd=project,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds + 60,
+    )
+    output: dict[str, Any] | str
+    if result.stdout.strip():
+        try:
+            output = json.loads(result.stdout.strip().splitlines()[-1])
+        except json.JSONDecodeError:
+            output = result.stdout
+    else:
+        output = result.stderr or ""
+    return CronResult(
+        exit_code=result.returncode,
+        output=output,
+        project_dir=project,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry: hermes-gsd-cron <project_dir> [--timeout N]"""
+    args = argv if argv is not None else sys.argv[1:]
+    if not args:
+        print("Usage: hermes-gsd-cron <project_dir> [--timeout SECONDS]", file=sys.stderr)
+        return 1
+    project_dir = args[0]
+    timeout = 3600
+    if "--timeout" in args:
+        idx = args.index("--timeout")
+        if idx + 1 < len(args):
+            timeout = int(args[idx + 1])
+    cfg = load_config()
+    res = run_headless_auto(project_dir, cfg, timeout_seconds=timeout)
+    print(json.dumps({"exit_code": res.exit_code, "project_dir": res.project_dir, "output": res.output}))
+    return res.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/integrations/hermes/open_gsd_hermes/formatting.py

@@ -0,0 +1,13 @@
+"""Shared formatting helpers for GSD display values."""
+
+from __future__ import annotations
+
+
+def format_ref(ref: dict[str, str] | None, *, include_title: bool = True) -> str:
+    if not ref:
+        return "—"
+    rid = ref.get("id", "")
+    title = ref.get("title") or ""
+    if include_title and rid and title:
+        return f"{rid}: {title}"
+    return rid or title or "—"

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