@opengsd/gsd-pi 1.3.0 → 1.4.0

package/integrations/hermes/open_gsd_hermes/__init__.py

@@ -0,0 +1,105 @@
+"""open-gsd-hermes — Hermes Agent plugin for GSD Pi integration."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from open_gsd_hermes.binding import SessionBindStore
+from open_gsd_hermes.commands import GsdCommandRouter
+from open_gsd_hermes.config import GsdConfig, load_config
+from open_gsd_hermes.credentials import CredentialPassthrough
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.inject import make_pre_llm_call_handler
+from open_gsd_hermes.memory import GsdMemoryProvider
+from open_gsd_hermes.notifications import NotificationService
+from open_gsd_hermes.supervisor import SupervisorContext, SupervisorFsm
+from open_gsd_hermes.types import BindingContext, DeliveryTarget, PluginContext
+
+
+def register(ctx: PluginContext) -> None:
+    """Hermes plugin entry point."""
+    config = load_config()
+    client = GsdMcpClient(config)
+    bind_store = SessionBindStore()
+
+    session_key = os.environ.get(
+        "HERMES_SESSION_KEY", "agent:main:cli:direct:local"
+    )
+    binding_ctx = BindingContext(cwd=os.getcwd())
+    supervisor_ctx = SupervisorContext()
+
+    def get_session_key() -> str:
+        return session_key
+
+    def get_binding_ctx() -> BindingContext:
+        return binding_ctx
+
+    def get_supervisor_ctx() -> SupervisorContext:
+        return supervisor_ctx
+
+    def set_supervisor_ctx(sctx: SupervisorContext) -> None:
+        nonlocal supervisor_ctx
+        supervisor_ctx = sctx
+
+    delivery_target: DeliveryTarget | None = DeliveryTarget.from_session_key(
+        session_key
+    )
+
+    def get_target() -> DeliveryTarget | None:
+        return delivery_target
+
+    def get_platform_channel() -> tuple[str | None, str | None]:
+        t = get_target()
+        if t:
+            return t.platform, t.chat_id
+        return None, None
+
+    notifications = NotificationService(ctx, config, get_target)
+    supervisor = SupervisorFsm(
+        config,
+        client,
+        notifications,
+        get_supervisor_ctx,
+        set_supervisor_ctx,
+    )
+
+    router = GsdCommandRouter(
+        config,
+        client,
+        bind_store,
+        supervisor,
+        get_session_key,
+        get_binding_ctx,
+        get_supervisor_ctx,
+        set_supervisor_ctx,
+        get_platform_channel,
+        notifications,
+    )
+
+    ctx.register_hook(
+        "pre_llm_call",
+        make_pre_llm_call_handler(config, client, router._binding_ctx),
+    )
+    ctx.register_command("gsd", router.handle)
+
+    memory_provider = GsdMemoryProvider(config, client)
+    if hasattr(ctx, "register_memory_provider"):
+        ctx.register_memory_provider(memory_provider)
+
+    # Validate credential config at startup
+    creds = CredentialPassthrough(config.credential_source)
+    for warning in creds.validate():
+        if hasattr(ctx, "log_warning"):
+            ctx.log_warning(warning)  # type: ignore[attr-defined]
+
+    # Expose for tests
+    register._state = {  # type: ignore[attr-defined]
+        "config": config,
+        "client": client,
+        "router": router,
+        "supervisor": supervisor,
+    }
+
+
+__all__ = ["register", "GsdConfig", "load_config"]

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,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 "—"