@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/integrations/hermes/open_gsd_hermes/binding.py

@@ -0,0 +1,107 @@
+"""Tiered project binding resolver and session bind store."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.types import BindingContext
+
+
+class BindingError(Exception):
+    """Raised when project binding cannot be resolved (fail closed)."""
+
+
+class SessionBindStore:
+    """Per-session project directory bindings (from /gsd bind)."""
+
+    def __init__(self) -> None:
+        self._by_session: dict[str, str] = {}
+
+    def set(self, session_key: str, project_dir: str) -> None:
+        self._by_session[session_key] = str(Path(project_dir).expanduser().resolve())
+
+    def get(self, session_key: str) -> str | None:
+        return self._by_session.get(session_key)
+
+    def clear(self, session_key: str) -> None:
+        self._by_session.pop(session_key, None)
+
+
+def _looks_like_gsd_project(path: Path) -> bool:
+    return (path / ".gsd").is_dir() or (path / ".planning").is_dir()
+
+
+def _resolve_channel_binding(
+    config: GsdConfig, platform: str | None, channel_id: str | None
+) -> str | None:
+    if not platform or not channel_id:
+        return None
+    platform_bindings = config.bindings.get(platform) or {}
+    return platform_bindings.get(channel_id)
+
+
+def _cwd_heuristic(cwd: str | None) -> str | None:
+    if not cwd:
+        return None
+    path = Path(cwd).resolve()
+    if _looks_like_gsd_project(path):
+        return str(path)
+    return None
+
+
+def resolve_explicit_project_dir(raw: str) -> str:
+    """Resolve a user-provided project path without falling back to other bindings."""
+    path = Path(os.path.expanduser(str(raw))).resolve()
+    if not path.is_dir() or not _looks_like_gsd_project(path):
+        raise BindingError(
+            f"`{raw}` is not a GSD project. Choose a directory containing "
+            "`.gsd/` or `.planning/`."
+        )
+    return str(path)
+
+
+def resolve_project_dir(
+    config: GsdConfig,
+    ctx: BindingContext,
+    *,
+    fail_closed: bool = True,
+) -> str | None:
+    """
+    Resolve projectDir in order:
+      1. cron explicit (cron_project)
+      2. slash arg (slash_path)
+      3. session bind
+      4. channel map
+      5. profile default
+      6. cwd heuristic
+    """
+    # Tier order: cron → slash arg → session bind → channel map → default → cwd
+    candidates: list[tuple[str, str | None]] = [
+        ("cron", ctx.cron_project),
+        ("slash", ctx.slash_path),
+        ("session", ctx.session_bind),
+        (
+            "channel",
+            _resolve_channel_binding(config, ctx.platform, ctx.channel_id),
+        ),
+        ("default", config.default_project),
+        ("cwd", _cwd_heuristic(ctx.cwd)),
+    ]
+
+    for _source, raw in candidates:
+        if not raw:
+            continue
+        path = Path(os.path.expanduser(str(raw))).resolve()
+        if not path.is_dir():
+            continue
+        if _looks_like_gsd_project(path):
+            return str(path)
+
+    if fail_closed:
+        raise BindingError(
+            "No GSD project bound. Use `/gsd bind <path>`, set `default_project` in "
+            "~/.hermes/gsd.yaml, or add a channel binding."
+        )
+    return None

package/integrations/hermes/open_gsd_hermes/commands.py

@@ -0,0 +1,327 @@
+"""`/gsd` slash command router — bind, status, auto, cancel, reply."""
+
+from __future__ import annotations
+
+import os
+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,
+            "new-milestone": self._cmd_new_milestone,
+            "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 new-milestone <spec>` or `--file <path>` — create a milestone (then `/gsd auto`)\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:
+        # Symmetric co-run guard (issue #1162): refuse if a milestone run is
+        # in progress. The MCP server's "Session already active" rejection
+        # does NOT fire for a milestone subprocess (it's not registered and
+        # writes no auto.lock during planning), so this local gate is the
+        # only thing preventing an unsafe co-run.
+        if self._client.milestone_active():
+            return (
+                "Milestone creation is in progress. Run `/gsd cancel` first."
+            )
+        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()
+        # Milestone subprocess is locally owned (issue #1162); route to the
+        # local SIGTERM path instead of MCP cancel, which cannot see it.
+        if self._client.milestone_active():
+            self._client.cancel_milestone()
+            ctx.session_id = None
+            ctx.state = SupervisorState.CANCELLED
+            ctx.notified_terminal = True
+            self._set_supervisor_ctx(ctx)
+            self._supervisor.stop()
+            if self._notifications is not None:
+                self._notifications.notify_terminal("cancelled")
+            return "Cancel requested."
+        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)
+        # Milestone planning blocker (issue #1162): the subprocess is locally
+        # owned, so its blocker replies must go to its stdin, not MCP
+        # gsd_resolve_blocker (which can't see our session).
+        if self._client.milestone_active():
+            if not self._client.milestone_pending_blocker_id():
+                return "No pending blocker for the active milestone session."
+            try:
+                self._client.respond_to_milestone_blocker(text)
+            except Exception as e:
+                return f"Could not send blocker response: {e}"
+            return "Blocker response sent."
+        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."
+
+    async def _cmd_new_milestone(self, rest: list[str]) -> str:
+        """Create a milestone via `gsd headless --supervised new-milestone`.
+
+        Planning-only: the plugin spawns the subprocess, owns its lifecycle,
+        and notifies on blocker/terminal events. Execution stays with
+        `/gsd auto`. See integrations/hermes/docs/issue-1162-grilling.md.
+        """
+        if not rest:
+            return (
+                "Usage: `/gsd new-milestone <spec>` "
+                "(or `--file <path>`)"
+            )
+        # --auto is intentionally rejected (Q5): execution is /gsd auto's job.
+        if rest[0] == "--auto":
+            return (
+                "Execution isn't chained from `/gsd new-milestone`. "
+                "Create the milestone, then run `/gsd auto`."
+            )
+        # Co-run guard (Q2): refuse if a milestone or auto session is active.
+        if self._client.milestone_active():
+            return (
+                "Milestone creation is in progress. Run `/gsd cancel` first."
+            )
+        ctx = self._get_supervisor_ctx()
+        if ctx.state in (SupervisorState.RUNNING, SupervisorState.BLOCKED):
+            return (
+                "GSD auto is running. Run `/gsd cancel` first."
+            )
+        # Resolve the bound project.
+        try:
+            project_dir = resolve_project_dir(
+                self._config, self._binding_ctx()
+            )
+        except BindingError as e:
+            return str(e)
+
+        # Input shape (Q6): bare positional → context_text, `--file <path>`
+        # → context_file.
+        context_text: str | None = None
+        context_file: str | None = None
+        if rest[0] == "--file":
+            if len(rest) < 2:
+                return "Usage: `/gsd new-milestone --file <path>`"
+            context_file = rest[1]
+            resolved_file = (
+                context_file
+                if os.path.isabs(context_file)
+                else os.path.join(project_dir, context_file)
+            )
+            if not os.path.isfile(resolved_file):
+                return f"Context file not found: `{context_file}`"
+            if not os.access(resolved_file, os.R_OK):
+                return f"Context file is not readable: `{context_file}`"
+            context_file = resolved_file
+        else:
+            context_text = " ".join(rest)
+
+        def _on_milestone_terminal(status: str) -> None:
+            milestone_ctx = self._get_supervisor_ctx()
+            if milestone_ctx.session_id != session_id:
+                return
+            normalized = status.lower()
+            if normalized in ("complete", "completed", "done"):
+                milestone_ctx.state = SupervisorState.COMPLETE
+            elif normalized == "cancelled":
+                milestone_ctx.state = SupervisorState.CANCELLED
+            else:
+                milestone_ctx.state = SupervisorState.FAILED
+            milestone_ctx.session_id = None
+            milestone_ctx.pending_blocker_id = None
+            milestone_ctx.notified_terminal = True
+            self._set_supervisor_ctx(milestone_ctx)
+
+        # Spawn the supervised subprocess; create_milestone returns a local
+        # session id immediately and continues the stream reader in the
+        # background.
+        try:
+            session_id = self._client.create_milestone(
+                project_dir,
+                context_text=context_text,
+                context_file=context_file,
+                notifications=self._notifications,
+                on_terminal=_on_milestone_terminal,
+            )
+        except ValueError:
+            return "Usage: `/gsd new-milestone <spec>` (or `--file <path>`)"
+        except Exception as e:
+            return f"Could not start milestone creation: {e}"
+
+        # Record the active milestone run so /gsd status, /gsd cancel, and the
+        # co-run gate (in _cmd_auto) see it. The supervisor poll loop is NOT
+        # used (the stream reader drives notifications); we only carry state.
+        self._supervisor.stop()
+        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)
+        return (
+            f"🚀 Milestone creation started (session `{session_id}`). "
+            "I'll notify you when it's ready; run `/gsd auto` to execute."
+        )

package/integrations/hermes/open_gsd_hermes/config.py

@@ -0,0 +1,61 @@
+"""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
+    mcp_read_timeout_seconds: float = 60.0
+    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)),
+            mcp_read_timeout_seconds=float(gsd.get("mcp_read_timeout_seconds", 60.0)),
+            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 "—"