@opengsd/gsd-pi 1.3.0 → 1.4.0

package/integrations/hermes/open_gsd_hermes/types.py

@@ -0,0 +1,100 @@
+"""Shared types for the open-gsd-hermes plugin."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Protocol
+
+
+class PluginContext(Protocol):
+    """Minimal Hermes plugin context surface used by this integration."""
+
+    def register_command(self, name: str, handler: Callable[..., Any]) -> None: ...
+    def register_hook(self, name: str, handler: Callable[..., Any]) -> None: ...
+    def register_memory_provider(self, provider: Any) -> None: ...
+    def dispatch_tool(self, name: str, arguments: dict[str, Any]) -> Any: ...
+
+
+@dataclass
+class DeliveryTarget:
+    """Gateway delivery target for send_message notifications."""
+
+    platform: str
+    chat_type: str
+    chat_id: str
+    session_key: str = ""
+
+    @classmethod
+    def from_session_key(cls, session_key: str) -> DeliveryTarget | None:
+        # agent:main:{platform}:{chat_type}:{chat_id}
+        parts = session_key.split(":")
+        if len(parts) < 5 or parts[0] != "agent" or parts[1] != "main":
+            return None
+        return cls(
+            platform=parts[2],
+            chat_type=parts[3],
+            chat_id=":".join(parts[4:]),
+            session_key=session_key,
+        )
+
+
+@dataclass
+class ProgressSnapshot:
+    """Structured progress compatible with GSD ProgressResult."""
+
+    active_milestone: dict[str, str] | None = None
+    active_slice: dict[str, str] | None = None
+    active_task: dict[str, str] | None = None
+    phase: str = "unknown"
+    milestones: dict[str, int] = field(default_factory=dict)
+    slices: dict[str, int] = field(default_factory=dict)
+    tasks: dict[str, int] = field(default_factory=dict)
+    requirements: dict[str, int] | None = None
+    blockers: list[str] = field(default_factory=list)
+    next_action: str = ""
+
+    @classmethod
+    def from_mcp(cls, data: dict[str, Any]) -> ProgressSnapshot:
+        return cls(
+            active_milestone=data.get("activeMilestone"),
+            active_slice=data.get("activeSlice"),
+            active_task=data.get("activeTask"),
+            phase=data.get("phase", "unknown"),
+            milestones=data.get("milestones") or {},
+            slices=data.get("slices") or {},
+            tasks=data.get("tasks") or {},
+            requirements=data.get("requirements"),
+            blockers=list(data.get("blockers") or []),
+            next_action=data.get("nextAction", ""),
+        )
+
+
+@dataclass
+class SessionStatus:
+    """Subset of gsd_status response."""
+
+    status: str
+    pending_blocker: dict[str, Any] | None = None
+    session_id: str | None = None
+    error: str | None = None
+
+    @classmethod
+    def from_mcp(cls, data: dict[str, Any]) -> SessionStatus:
+        return cls(
+            status=data.get("status", "unknown"),
+            pending_blocker=data.get("pendingBlocker"),
+            session_id=data.get("sessionId"),
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class BindingContext:
+    """Inputs for tiered project binding resolution."""
+
+    slash_path: str | None = None
+    session_bind: str | None = None
+    platform: str | None = None
+    channel_id: str | None = None
+    cron_project: str | None = None
+    cwd: str | None = None

package/integrations/hermes/plugin.yaml

@@ -0,0 +1,38 @@
+name: open-gsd-hermes
+version: 1.2.0
+description: GSD structured delivery — gateway supervision, cron headless, memory provider
+entry_point: open_gsd_hermes:register
+config_schema:
+  type: object
+  properties:
+    gsd:
+      type: object
+      properties:
+        cli_path:
+          type: string
+          description: Path to gsd CLI binary
+        mcp_server_path:
+          type: string
+          description: Path to gsd-mcp-server binary
+        credential_source:
+          type: string
+          enum: [gsd, hermes]
+          default: gsd
+        default_project:
+          type: string
+        bindings:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties:
+              type: string
+        poll_interval_seconds:
+          type: integer
+          default: 12
+        cache_ttl_seconds:
+          type: integer
+          default: 45
+        notification_level:
+          type: string
+          enum: [quiet, normal, verbose]
+          default: normal

package/integrations/hermes/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "open-gsd-hermes"
+version = "1.2.0"
+description = "Hermes Agent plugin — GSD structured delivery engine integration"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+  "PyYAML>=6.0",
+  "packaging>=23.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.entry-points."hermes_agent.plugins"]
+open_gsd_hermes = "open_gsd_hermes:register"
+
+[project.scripts]
+hermes-gsd-cron = "open_gsd_hermes.cron:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["open_gsd_hermes*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

package/integrations/hermes/scripts/preflight.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Local preflight before Slack/Telegram gateway checklist (no Hermes required).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+FIXTURE="$ROOT/integrations/hermes/tests/fixtures/minimal-project"
+GSD="${GSD_CLI_PATH:-gsd}"
+LOADER="${GSD_LOADER_PATH:-$ROOT/dist/loader.js}"
+
+pass=0
+fail=0
+
+ok() { echo "  ✓ $1"; pass=$((pass + 1)); }
+bad() { echo "  ✗ $1"; fail=$((fail + 1)); }
+
+echo "=== GSD Hermes integration preflight ==="
+echo
+
+echo "1. gsd version"
+if ver="$($GSD --version 2>/dev/null | tail -1)"; then
+  ok "gsd --version → $ver"
+else
+  bad "gsd not found (set GSD_CLI_PATH or install gsd)"
+fi
+
+echo
+echo "2. gsd-mcp-server"
+MCP="${GSD_MCP_SERVER_PATH:-gsd-mcp-server}"
+if command -v "$MCP" >/dev/null 2>&1; then
+  ok "$MCP on PATH"
+else
+  bad "$MCP not on PATH (configure mcp_server_path in ~/.hermes/gsd.yaml)"
+fi
+
+echo
+echo "3. gsd read progress (fixture)"
+if [[ -f "$LOADER" ]]; then
+  READ_CMD=(node "$LOADER" read progress --json --project "$FIXTURE")
+elif command -v "$GSD" >/dev/null 2>&1; then
+  READ_CMD=("$GSD" read progress --json --project "$FIXTURE")
+else
+  READ_CMD=()
+fi
+
+if [[ ${#READ_CMD[@]} -gt 0 ]]; then
+  if out="$("${READ_CMD[@]}" 2>/dev/null)"; then
+    if echo "$out" | grep -q '"integration_version": 1'; then
+      ok "read CLI returns integration_version 1"
+    else
+      bad "read CLI missing integration_version envelope"
+    fi
+    if echo "$out" | grep -q '"id": "M001"'; then
+      ok "fixture milestone M001 parsed"
+    else
+      bad "fixture milestone M001 not found in read output"
+    fi
+  else
+    bad "gsd read progress failed (run npm run build:core if using dist/loader.js)"
+  fi
+else
+  bad "no gsd binary available for read CLI check"
+fi
+
+echo
+echo "4. Python contract tests"
+if command -v python3 >/dev/null 2>&1; then
+  export GSD_LOADER_PATH="$LOADER"
+  if (cd "$ROOT/integrations/hermes" && python3 -m pytest tests/ -q); then
+    ok "pytest contract suite passed"
+  else
+    bad "pytest failed (pip install -e integrations/hermes[dev])"
+  fi
+else
+  bad "python3 not found"
+fi
+
+echo
+echo "5. Plugin package"
+if [[ -f "$ROOT/integrations/hermes/pyproject.toml" ]]; then
+  ok "integrations/hermes present"
+else
+  bad "integrations/hermes missing"
+fi
+
+echo
+echo "=== Summary: $pass passed, $fail failed ==="
+if [[ "$fail" -gt 0 ]]; then
+  echo "Fix failures above before running the Slack/Telegram gateway checklist."
+  exit 1
+fi
+echo "Preflight OK — proceed to gateway setup in docs/setup.md"
+exit 0

package/integrations/hermes/tests/fixtures/minimal-project/.gsd/STATE.md

@@ -0,0 +1,17 @@
+# GSD State
+
+**Active Milestone:** M001: Hermes Integration
+**Active Slice:** S01: Gateway MVP
+**Active Task:** T01: Plugin scaffold
+**Phase:** execution
+**Requirements Status:** 2 active · 0 validated · 0 deferred · 0 out of scope
+
+## Milestone Registry
+
+- 🔄 **M001:** Hermes Integration
+
+## Blockers
+
+## Next Action
+
+Run contract tests for binding and snapshot golden.

package/integrations/hermes/tests/golden/memory_prefetch.txt

@@ -0,0 +1,5 @@
+## GSD memories
+- Auth uses JWT with refresh rotation
+
+## Hermes MEMORY.md (read-only)
+User prefers concise Slack updates.

package/integrations/hermes/tests/golden/snapshot.txt

@@ -0,0 +1,8 @@
+## GSD Project Snapshot
+Phase: execute
+Active milestone: M001: Hermes Integration
+Active slice: S01: Gateway MVP
+Active task: T01: Plugin scaffold
+Milestones: 0/1 done (1 active)
+Requirements: 2 active, 0 validated
+Next: Run contract tests for binding and snapshot golden.

package/integrations/hermes/tests/test_binding.py

@@ -0,0 +1,103 @@
+"""Tests for tiered binding resolver."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+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.types import BindingContext
+
+FIXTURE = Path(__file__).parent / "fixtures" / "minimal-project"
+
+
+@pytest.fixture
+def config() -> GsdConfig:
+    return GsdConfig(
+        default_project=None,
+        bindings={"slack": {"#eng-bot": str(FIXTURE)}},
+    )
+
+
+def test_slash_path_wins_over_channel_binding(
+    config: GsdConfig, tmp_path: Path
+) -> None:
+    other = tmp_path / "other"
+    other.mkdir()
+    (other / ".gsd").mkdir()
+    ctx = BindingContext(
+        slash_path=str(other),
+        platform="slack",
+        channel_id="#eng-bot",
+    )
+    assert resolve_project_dir(config, ctx) == str(other.resolve())
+
+
+def test_explicit_project_dir_rejects_invalid_project(tmp_path: Path) -> None:
+    with pytest.raises(BindingError):
+        resolve_explicit_project_dir(str(tmp_path / "missing"))
+
+
+def test_session_bind_wins_over_channel_binding(
+    config: GsdConfig, tmp_path: Path
+) -> None:
+    other = tmp_path / "other"
+    other.mkdir()
+    (other / ".gsd").mkdir()
+    store = SessionBindStore()
+    store.set("sess-1", str(other))
+    ctx = BindingContext(
+        session_bind=store.get("sess-1"),
+        platform="slack",
+        channel_id="#eng-bot",
+    )
+    assert resolve_project_dir(config, ctx) == str(other.resolve())
+
+
+def test_session_bind_wins_over_default(config: GsdConfig, tmp_path: Path) -> None:
+    other = tmp_path / "other"
+    other.mkdir()
+    (other / ".gsd").mkdir()
+    config.default_project = str(other)
+    store = SessionBindStore()
+    store.set("sess-1", str(FIXTURE))
+    ctx = BindingContext(session_bind=store.get("sess-1"))
+    assert resolve_project_dir(config, ctx) == str(FIXTURE.resolve())
+
+
+def test_channel_binding(config: GsdConfig) -> None:
+    ctx = BindingContext(platform="slack", channel_id="#eng-bot")
+    assert resolve_project_dir(config, ctx) == str(FIXTURE.resolve())
+
+
+def test_cron_explicit_over_channel(config: GsdConfig, tmp_path: Path) -> None:
+    cron_proj = tmp_path / "cron"
+    cron_proj.mkdir()
+    (cron_proj / ".gsd").mkdir()
+    ctx = BindingContext(
+        cron_project=str(cron_proj),
+        platform="slack",
+        channel_id="#eng-bot",
+    )
+    assert resolve_project_dir(config, ctx) == str(cron_proj.resolve())
+
+
+def test_fail_closed(config: GsdConfig) -> None:
+    with pytest.raises(BindingError):
+        resolve_project_dir(config, BindingContext())
+
+
+def test_fail_open_returns_none(config: GsdConfig) -> None:
+    assert resolve_project_dir(config, BindingContext(), fail_closed=False) is None
+
+
+def test_cwd_heuristic(config: GsdConfig) -> None:
+    ctx = BindingContext(cwd=str(FIXTURE))
+    assert resolve_project_dir(config, ctx) == str(FIXTURE.resolve())

package/integrations/hermes/tests/test_config.py

@@ -0,0 +1,36 @@
+"""Tests for Hermes plugin configuration defaults."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from open_gsd_hermes.config import GsdConfig, config_path
+
+
+def test_default_gsd_version_range_matches_plugin_release_train() -> None:
+    config = GsdConfig()
+
+    assert config.gsd_version_min == "2.53"
+    assert config.gsd_version_max == "3.0"
+
+
+def test_dict_fallback_gsd_version_range_matches_plugin_release_train() -> None:
+    config = GsdConfig.from_dict({"gsd": {}})
+
+    assert config.gsd_version_min == "2.53"
+    assert config.gsd_version_max == "3.0"
+
+
+def test_config_path_respects_hermes_home(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.delenv("HERMES_GSD_CONFIG", raising=False)
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes-home"))
+
+    assert config_path() == tmp_path / "hermes-home" / "gsd.yaml"
+
+
+def test_config_path_explicit_env_wins(tmp_path: Path, monkeypatch) -> None:
+    explicit = tmp_path / "custom-gsd.yaml"
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "hermes-home"))
+    monkeypatch.setenv("HERMES_GSD_CONFIG", str(explicit))
+
+    assert config_path() == explicit

package/integrations/hermes/tests/test_cron.py

@@ -0,0 +1,34 @@
+"""Cron CLI tests."""
+
+from __future__ import annotations
+
+from open_gsd_hermes import cron
+from open_gsd_hermes.config import GsdConfig
+
+
+def test_main_prefers_cli_project_over_gsd_cron_project(monkeypatch, tmp_path) -> None:
+    cli_project = tmp_path / "cli-project"
+    env_project = tmp_path / "env-project"
+    captured: dict[str, object] = {}
+
+    monkeypatch.setenv("GSD_CRON_PROJECT", str(env_project))
+    monkeypatch.setattr(cron, "load_config", lambda: GsdConfig())
+
+    def fake_run_headless_auto(
+        project_dir: str,
+        config: GsdConfig,
+        *,
+        timeout_seconds: int,
+    ) -> cron.CronResult:
+        captured["project_dir"] = project_dir
+        captured["config"] = config
+        captured["timeout_seconds"] = timeout_seconds
+        return cron.CronResult(0, {"ok": True}, project_dir)
+
+    monkeypatch.setattr(cron, "run_headless_auto", fake_run_headless_auto)
+
+    result = cron.main([str(cli_project), "--timeout", "7"])
+
+    assert result == 0
+    assert captured["project_dir"] == str(cli_project)
+    assert captured["timeout_seconds"] == 7

package/integrations/hermes/tests/test_gsd_client_cache.py

@@ -0,0 +1,120 @@
+"""Unit tests for MCP client TTL cache (no subprocess)."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from unittest.mock import patch
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.gsd_client import GsdMcpClient, GsdVersionError
+from open_gsd_hermes.types import ProgressSnapshot
+
+
+def test_progress_cache_ttl() -> None:
+    config = GsdConfig(cache_ttl_seconds=1)
+    client = GsdMcpClient(config)
+    calls = {"n": 0}
+
+    def fake_read(project_dir: str) -> ProgressSnapshot:
+        calls["n"] += 1
+        return ProgressSnapshot(phase="execute", blockers=[], next_action="")
+
+    with patch.object(client, "_read_progress_cli", side_effect=fake_read):
+        with patch.object(client, "ensure_version"):
+            client.progress("/tmp/p")
+            client.progress("/tmp/p")
+            assert calls["n"] == 1
+            time.sleep(1.1)
+            client.progress("/tmp/p")
+            assert calls["n"] == 2
+
+
+def test_invalidate_cache_only_removes_exact_project() -> None:
+    client = GsdMcpClient(GsdConfig(cache_ttl_seconds=60))
+    calls: dict[str, int] = {}
+
+    def fake_read(project_dir: str) -> ProgressSnapshot:
+        calls[project_dir] = calls.get(project_dir, 0) + 1
+        return ProgressSnapshot(phase="execute", blockers=[], next_action=project_dir)
+
+    with patch.object(client, "_read_progress_cli", side_effect=fake_read):
+        with patch.object(client, "ensure_version"):
+            client.progress("/tmp/app")
+            client.progress("/tmp/app-v2")
+
+            client.invalidate_cache("/tmp/app")
+
+            client.progress("/tmp/app-v2")
+            client.progress("/tmp/app")
+
+    assert calls["/tmp/app-v2"] == 1
+    assert calls["/tmp/app"] == 2
+
+
+def test_progress_falls_back_to_mcp_when_cli_binary_is_missing() -> None:
+    client = GsdMcpClient(GsdConfig())
+
+    with patch.object(client, "ensure_version", side_effect=FileNotFoundError("gsd")):
+        with patch.object(
+            client,
+            "_call_tool",
+            return_value={"phase": "execute", "nextAction": "from mcp"},
+        ) as call_tool:
+            progress = client.progress("/tmp/p")
+
+    assert progress.phase == "execute"
+    assert progress.next_action == "from mcp"
+    call_tool.assert_called_once_with(
+        "gsd_progress",
+        {"projectDir": "/tmp/p"},
+        check_version=False,
+    )
+
+
+def test_progress_falls_back_to_mcp_when_cli_version_is_unsupported() -> None:
+    client = GsdMcpClient(GsdConfig())
+
+    with patch.object(client, "ensure_version", side_effect=GsdVersionError("old gsd")):
+        with patch.object(
+            client,
+            "_call_tool",
+            return_value={"phase": "execute", "nextAction": "from mcp"},
+        ) as call_tool:
+            progress = client.progress("/tmp/p")
+
+    assert progress.phase == "execute"
+    assert progress.next_action == "from mcp"
+    call_tool.assert_called_once_with(
+        "gsd_progress",
+        {"projectDir": "/tmp/p"},
+        check_version=False,
+    )
+
+
+def test_progress_falls_back_to_mcp_when_cli_json_has_unexpected_shape() -> None:
+    client = GsdMcpClient(GsdConfig())
+    cli_result = subprocess.CompletedProcess(
+        args=["gsd", "read", "progress"],
+        returncode=0,
+        stdout=json.dumps(["unexpected"]),
+        stderr="",
+    )
+
+    with patch.object(client, "ensure_version"):
+        with patch("subprocess.run", return_value=cli_result):
+            with patch.object(
+                client,
+                "_call_tool",
+                return_value={"phase": "execute", "nextAction": "from mcp"},
+            ) as call_tool:
+                progress = client.progress("/tmp/p")
+
+    assert progress.phase == "execute"
+    assert progress.next_action == "from mcp"
+    call_tool.assert_called_once_with(
+        "gsd_progress",
+        {"projectDir": "/tmp/p"},
+        check_version=False,
+    )

package/integrations/hermes/tests/test_memory.py

@@ -0,0 +1,59 @@
+"""Golden test for federated memory prefetch (6c)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from open_gsd_hermes.config import GsdConfig
+from open_gsd_hermes.gsd_client import GsdMcpClient
+from open_gsd_hermes.memory import GsdMemoryProvider
+
+GOLDEN = Path(__file__).parent / "golden" / "memory_prefetch.txt"
+
+
+def test_memory_prefetch_golden(tmp_path: Path) -> None:
+    memory_file = tmp_path / "MEMORY.md"
+    memory_file.write_text("User prefers concise Slack updates.\n", encoding="utf-8")
+
+    config = GsdConfig(hermes_memory_path=str(memory_file))
+    client = MagicMock(spec=GsdMcpClient)
+    client.memory_query.return_value = {
+        "memories": [{"content": "Auth uses JWT with refresh rotation"}],
+    }
+
+    provider = GsdMemoryProvider(config, client)
+    rendered = provider.prefetch("/tmp/project", query="auth")
+    expected = GOLDEN.read_text(encoding="utf-8").strip()
+    assert rendered.strip() == expected
+
+
+def test_memory_prefetch_ignores_empty_memory_results() -> None:
+    config = GsdConfig()
+    client = MagicMock(spec=GsdMcpClient)
+    client.memory_query.return_value = {"memories": []}
+
+    provider = GsdMemoryProvider(config, client)
+    rendered = provider.prefetch("/tmp/project", query="auth")
+
+    assert rendered == ""
+
+
+def test_memory_prefetch_keeps_multiple_gsd_memories_in_one_list() -> None:
+    config = GsdConfig()
+    client = MagicMock(spec=GsdMcpClient)
+    client.memory_query.return_value = {
+        "memories": [
+            {"content": "Auth uses JWT with refresh rotation"},
+            {"content": "Billing runs through Stripe"},
+        ],
+    }
+
+    provider = GsdMemoryProvider(config, client)
+    rendered = provider.prefetch("/tmp/project", query="auth")
+
+    assert rendered == (
+        "## GSD memories\n"
+        "- Auth uses JWT with refresh rotation\n"
+        "- Billing runs through Stripe"
+    )