@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

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)

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.