opencode-hermes-mcp 0.4.1__py3-none-any.whl

opencode_hermes_mcp/models.py

@@ -0,0 +1,234 @@
+"""Data helpers: message parsing, agent validation, durable turn state.
+
+The durable state file (one per session, under OPENCODE_MCP_STATE_DIR) is what
+makes `opencode_answer` / `opencode_permission` survive a controller restart:
+everything the wait loop needs to resume the SAME OpenCode turn is either
+server-side (status/messages/pending q/p) or persisted here (submission time,
+answered request ids).
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+STATE_DIR = os.environ.get(
+    "OPENCODE_MCP_STATE_DIR",
+    os.path.join(os.path.expanduser("~"), ".local", "state", "opencode-hermes-mcp"),
+)
+
+# A root agent must have mode "primary" (observed on 1.18.21). "all" is
+# treated as usable-as-root too, in case a future version exposes it.
+ROOT_AGENT_MODES = {"primary", "all"}
+
+
+# --------------------------------------------------------------------------- #
+# Message helpers
+# --------------------------------------------------------------------------- #
+
+
+def assistant_text(message: dict[str, Any] | None) -> str:
+    if not message:
+        return ""
+    parts = message.get("parts") or []
+    texts = [
+        p.get("text", "")
+        for p in parts
+        if isinstance(p, dict) and p.get("type") == "text" and isinstance(p.get("text"), str)
+    ]
+    return "\n".join(x for x in texts if x)
+
+
+def last_assistant(messages: list[dict[str, Any]]) -> dict[str, Any] | None:
+    for msg in reversed(messages):
+        if (msg.get("info") or {}).get("role") == "assistant":
+            return msg
+    return None
+
+
+def last_user_message(messages: list[dict[str, Any]]) -> dict[str, Any] | None:
+    for msg in reversed(messages):
+        if (msg.get("info") or {}).get("role") == "user":
+            return msg
+    return None
+
+
+def msg_created_ms(message: dict[str, Any] | None) -> int:
+    info = (message or {}).get("info") or {}
+    return int((info.get("time") or {}).get("created", 0) or 0)
+
+
+def parse_model(value: str) -> dict[str, str]:
+    if "/" not in value:
+        raise ValueError(f"model must be provider/model, got {value!r}")
+    provider, model = value.split("/", 1)
+    if not provider or not model:
+        raise ValueError(f"model must be provider/model, got {value!r}")
+    return {"providerID": provider, "modelID": model}
+
+
+def diff_summary(diffs: list[dict[str, Any]]) -> dict[str, Any]:
+    files = [d.get("file") for d in diffs if d.get("file")]
+    return {
+        "files": len(files),
+        "additions": sum(int(d.get("additions", 0) or 0) for d in diffs),
+        "deletions": sum(int(d.get("deletions", 0) or 0) for d in diffs),
+        "changed_files": files[:50],
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Agent validation (dynamic — no hardcoded whitelist)
+# --------------------------------------------------------------------------- #
+
+
+def validate_agent(
+    agents: list[dict[str, Any]], agent: str
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Check `agent` against the live /agent list.
+
+    Returns (agent_info, None) when usable as a root agent, or
+    (None, error_result) otherwise. Error results carry the code
+    agent_not_found / invalid_primary_agent plus the available primaries.
+    """
+    primaries = [a for a in agents if a.get("mode") in ROOT_AGENT_MODES]
+    primaries = [a for a in primaries if not a.get("hidden")]
+    primary_names = [a.get("name") for a in primaries if a.get("name")]
+    for a in agents:
+        if a.get("name") == agent:
+            if a.get("mode") in ROOT_AGENT_MODES:
+                return a, None
+            return None, {
+                "ok": False,
+                "state": "error",
+                "code": "invalid_primary_agent",
+                "agent": agent,
+                "mode": a.get("mode"),
+                "error": f"agent '{agent}' is a {a.get('mode')} and cannot be a root agent",
+                "primary_agents": primary_names,
+            }
+    return None, {
+        "ok": False,
+        "state": "error",
+        "code": "agent_not_found",
+        "agent": agent,
+        "error": f"agent '{agent}' does not exist in this directory",
+        "primary_agents": primary_names,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Answer / permission validation (against the ORIGINAL request data)
+# --------------------------------------------------------------------------- #
+
+
+def validate_question_answers(
+    question: dict[str, Any], answers: list[Any]
+) -> tuple[bool, str]:
+    """Validate `answers` (one entry per sub-question, each a str or list[str])
+    against the question's options.
+
+    OpenCode 1.18.21 rejects (400) any answer that is not an exact option
+    label when the sub-question has options and custom=false.
+    """
+    subqs = question.get("questions") or []
+    if len(answers) != len(subqs):
+        return False, f"expected {len(subqs)} answer(s) (one per sub-question), got {len(answers)}"
+    for i, (q, ans) in enumerate(zip(subqs, answers)):
+        if isinstance(ans, str):
+            ans = [ans]
+        valid = isinstance(ans, list) and ans and all(
+            isinstance(x, str) and x.strip() for x in ans
+        )
+        if not valid:
+            return False, f"answer {i + 1} must be a non-empty string or list of strings"
+        labels = [o.get("label") for o in (q.get("options") or []) if o.get("label")]
+        custom = bool(q.get("custom"))
+        if labels and not custom:
+            for x in ans:
+                if x not in labels:
+                    return False, (
+                        f"answer {i + 1}: {x!r} is not a valid option label; "
+                        f"valid labels: {labels}"
+                    )
+        if not q.get("multiple") and len(ans) > 1:
+            return False, f"answer {i + 1}: question is single-choice, got {len(ans)} answers"
+    return True, ""
+
+
+PERMISSION_REPLIES = ("once", "always", "reject")
+
+
+def validate_permission_reply(reply: str) -> tuple[bool, str]:
+    if reply in PERMISSION_REPLIES:
+        return True, ""
+    return False, f"reply must be one of {list(PERMISSION_REPLIES)}, got {reply!r}"
+
+
+# --------------------------------------------------------------------------- #
+# Durable turn state (survives controller restarts)
+# --------------------------------------------------------------------------- #
+
+
+def state_path(session_id: str) -> str:
+    safe = session_id.replace("/", "_")
+    return os.path.join(STATE_DIR, f"turn_{safe}.json")
+
+
+def _turn_to_jsonable(turn: dict[str, Any]) -> dict[str, Any]:
+    """Project a turn dict to a JSON-safe form (sets -> sorted lists)."""
+    out = dict(turn)
+    for key in ("ignore_ids", "tree"):
+        if isinstance(out.get(key), (set, frozenset)):
+            out[key] = sorted(out[key])
+    return out
+
+
+def save_turn_state(turn: dict[str, Any]) -> None:
+    try:
+        os.makedirs(STATE_DIR, exist_ok=True)
+        path = state_path(turn["session_id"])
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(_turn_to_jsonable(turn), f)
+        os.replace(tmp, path)
+    except OSError:
+        pass  # state persistence is best-effort; the wait loop still works in-RAM
+
+
+def load_turn_state(session_id: str) -> dict[str, Any] | None:
+    try:
+        with open(state_path(session_id), encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict) or not data.get("session_id"):
+            return None
+        data["ignore_ids"] = set(data.get("ignore_ids") or [])
+        if isinstance(data.get("tree"), list):
+            data["tree"] = set(data["tree"])
+        return data
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def clear_turn_state(session_id: str) -> None:
+    try:
+        os.remove(state_path(session_id))
+    except OSError:
+        pass
+
+
+def new_turn(
+    session_id: str,
+    directory: str,
+    submitted_at_ms: int | None = None,
+    agent: str | None = None,
+    ignore_ids: set[str] | None = None,
+) -> dict[str, Any]:
+    return {
+        "session_id": session_id,
+        "directory": directory,
+        "agent": agent,
+        "submitted_at_ms": submitted_at_ms or int(time.time() * 1000),
+        "ignore_ids": set(ignore_ids or set()),
+    }

opencode_hermes_mcp/pin.txt

@@ -0,0 +1 @@
+1.18.21

opencode_hermes_mcp/server.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+opencode-hermes-mcp — deterministic controller between Hermes (MCP client) and
+the permanent OpenCode server.
+
+    Hermes  --MCP stdio-->  this server  --HTTP + SSE-->  OpenCode :4096
+
+This process is NO LLM: a state machine + HTTP/SSE client (see controller.py,
+client.py, models.py). The Hermes LLM is the supervisor: it delegates a task
+with opencode_run, and when OpenCode needs input (question / permission) the
+controller returns `needs_agent_input` to the Hermes LLM, which decides and
+calls opencode_answer / opencode_permission. Those tools post the decision and
+re-enter the SAME blocking wait — the same OpenCode turn, never a resubmitted
+prompt.
+
+Tools (final surface):
+  opencode_run        submit a task, block until completed/error/needs input
+  opencode_answer     answer a pending OpenCode question, keep waiting
+  opencode_permission decide a pending OpenCode permission, keep waiting
+  opencode_abort      abort the active (or given) session
+  opencode_inspect    DIAGNOSTIC ONLY — never poll a running task
+  opencode_sessions   list sessions for a directory
+
+Credentials come from the environment (injected by the launcher):
+  OPENCODE_SERVER_URL / OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD
+
+Target: OpenCode 1.18.21. Endpoint contract = the live server's /doc,
+verified against the installed binary — not the web docs.
+"""
+
+# NOTE: no `from __future__ import annotations` here — FastMCP inspects
+# parameter annotations at runtime to detect the Context injection point, and
+# stringified annotations break that detection.
+
+import os
+from contextlib import asynccontextmanager
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import OpenCode
+from .controller import DEFAULT_RUN_TIMEOUT, Controller
+
+OC = OpenCode()
+CTRL = Controller(OC)
+
+# PID file (used by tests to kill the controller process mid-turn to simulate
+# an MCP restart). Best-effort; ignored if the env var is not set.
+_PID_FILE = os.environ.get("OPENCODE_MCP_PID_FILE")
+
+
+def _write_pid() -> None:
+    if not _PID_FILE:
+        return
+    try:
+        with open(_PID_FILE, "w", encoding="utf-8") as f:
+            f.write(str(os.getpid()))
+    except OSError:
+        pass
+
+
+def _remove_pid() -> None:
+    if not _PID_FILE:
+        return
+    try:
+        os.remove(_PID_FILE)
+    except OSError:
+        pass
+
+
+@asynccontextmanager
+async def _lifespan(_: FastMCP):
+    # SSE subscriptions are per-wait (scoped by directory); nothing global to
+    # start here. The httpx client is created lazily and closed on shutdown.
+    _write_pid()
+    try:
+        yield
+    finally:
+        _remove_pid()
+        await OC.aclose()
+
+
+server = FastMCP(
+    name="opencode",
+    debug=False,
+    instructions=(
+        "Supervise the permanent OpenCode server. Delegate coding tasks with "
+        "opencode_run — it blocks until the turn completes, errors, or needs "
+        "input. NEVER poll with opencode_inspect while waiting: opencode_run, "
+        "opencode_answer and opencode_permission wait for you. When a tool "
+        "returns state=needs_agent_input, YOU decide (question: pick the exact "
+        "option labels; permission: once/always/reject) and call "
+        "opencode_answer or opencode_permission to resume the same turn. "
+        "opencode_inspect is for exceptional diagnostics only."
+    ),
+    lifespan=_lifespan,
+)
+
+
+def _busy_error() -> dict[str, Any]:
+    active_sid = (CTRL._active or {}).get("session_id")
+    return {
+        "ok": False,
+        "error": (
+            "another OpenCode operation is already in progress (strictly "
+            "sequential). Use opencode_abort to stop it, or wait."
+        ),
+        "active_session": active_sid,
+    }
+
+
+@server.tool()
+async def opencode_run(
+    directory: str,
+    task: str,
+    agent: str | None = None,
+    model: str | None = None,
+    session_id: str | None = None,
+    timeout: float = DEFAULT_RUN_TIMEOUT,
+) -> dict[str, Any]:
+    """Delegate a coding task to OpenCode and block until it completes, errors,
+    or needs input (a question or a permission).
+
+    - New task: pass `directory` + `task` + `agent` (a new session is created).
+      `agent` is REQUIRED for a new session.
+    - Continuation / resume: pass `session_id` (+ `task` for a NEW turn on that
+      session, or `task` is ignored when the turn is still in flight). `agent`
+      is not needed to resume an in-flight turn (it is taken from the turn's
+      durable state); pass it only when starting a fresh turn on an existing
+      session.
+    - `agent`: the OpenCode agent to run as root. Free string, validated
+      dynamically against the project's live agent list (GET /agent). It MUST
+      be a primary agent of that directory (project-specific primary agents
+      are preferred when they fit the task; `build` is the generic
+      implementation agent; `plan` is read-only). Subagents are rejected as
+      root. Do not rely on the server's default_agent: always choose
+      explicitly for a new session.
+    - `model`: optional 'provider/model' override.
+
+    RESUME: if `session_id` is given and that session still has a turn in
+    flight (busy/retry) — e.g. the controller restarted mid-turn — the prompt
+    is NOT resubmitted: the wait loop simply resumes on the SAME turn
+    (`task` and `agent` are ignored in that case).
+
+    The call blocks until the turn ends. While OpenCode works, NOTHING is
+    polled — the controller watches SSE + REST internally. If OpenCode asks a
+    question or requests a permission, the call returns
+    state='needs_agent_input' (kind='question' or 'permission') with everything
+    needed to decide; answer with opencode_answer / opencode_permission, which
+    resume the SAME turn. Returns the final assistant text + diff on completion.
+    """
+    if CTRL._lock.locked():
+        return _busy_error()
+    async with CTRL._lock:
+        return await CTRL.run(
+            directory=directory,
+            task=task,
+            agent=agent,
+            model=model,
+            session_id=session_id,
+            timeout=timeout,
+        )
+
+
+@server.tool()
+async def opencode_answer(
+    directory: str,
+    session_id: str,
+    question_id: str,
+    answers: list[Any],
+    timeout: float = DEFAULT_RUN_TIMEOUT,
+) -> dict[str, Any]:
+    """Answer a pending OpenCode question (state=needs_agent_input,
+    kind=question) and keep blocking until the turn completes, errors, or
+    needs input again.
+
+    - `answers`: ONE entry per sub-question, in order. Each entry is a string
+      or a list of strings. When a sub-question offers options and does not
+      allow custom answers, each value MUST be an exact option label (the
+      server rejects anything else — this tool validates before posting).
+    - The answer is posted to OpenCode and the SAME turn resumes (the prompt
+      is never resubmitted).
+    - If the question is no longer pending (already answered/consumed), an
+      error is returned; the turn may have moved on.
+    """
+    if CTRL._lock.locked():
+        return _busy_error()
+    async with CTRL._lock:
+        return await CTRL.answer(
+            directory=directory,
+            session_id=session_id,
+            question_id=question_id,
+            answers=answers,
+            timeout=timeout,
+        )
+
+
+@server.tool()
+async def opencode_permission(
+    directory: str,
+    session_id: str,
+    permission_id: str,
+    reply: str,
+    timeout: float = DEFAULT_RUN_TIMEOUT,
+) -> dict[str, Any]:
+    """Decide a pending OpenCode permission (state=needs_agent_input,
+    kind=permission) and keep blocking until the turn completes, errors, or
+    needs input again.
+
+    - `reply`: exactly one of 'once' (allow this call), 'always' (allow this
+      pattern for the session), 'reject'. Decide as supervisor: allow normal
+      actions necessary for the delegated task; reject destructive or
+      out-of-scope requests.
+    - The decision is posted to OpenCode and the SAME turn resumes (the prompt
+      is never resubmitted).
+    - If the permission is no longer pending, an error is returned.
+    """
+    if CTRL._lock.locked():
+        return _busy_error()
+    async with CTRL._lock:
+        return await CTRL.permission(
+            directory=directory,
+            session_id=session_id,
+            permission_id=permission_id,
+            reply=reply,
+            timeout=timeout,
+        )
+
+
+@server.tool()
+async def opencode_abort(session_id: str | None = None) -> dict[str, Any]:
+    """Abort the active OpenCode session (or a specific one). Does not require
+    the run lock, so it can stop a stuck run."""
+    return await CTRL.abort(session_id)
+
+
+@server.tool()
+async def opencode_inspect(session_id: str | None = None) -> dict[str, Any]:
+    """DIAGNOSTIC ONLY: one-shot snapshot of a session (status, tree, pending
+    permissions/questions, last assistant text). NEVER use this to poll or
+    monitor a running task — opencode_run / opencode_answer /
+    opencode_permission block until the turn ends; polling wastes tokens and
+    is forbidden. Use only for exceptional diagnostics (after a timeout, or to
+    inspect a session you did not start)."""
+    return await CTRL.inspect(session_id)
+
+
+@server.tool()
+async def opencode_sessions(directory: str) -> dict[str, Any]:
+    """List OpenCode sessions for a directory (to pick a session_id to reuse)."""
+    return await CTRL.sessions(directory)
+
+
+def main() -> None:
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

opencode_hermes_mcp/smoke_client.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Smoke test: drive the opencode-hermes-mcp controller over stdio as a client.
+
+No LLM is called: it checks the MCP tool surface, the agent-required
+validation, and the session listing against a live OpenCode server.
+
+Credentials: OPENCODE_SERVER_URL / OPENCODE_SERVER_USERNAME /
+OPENCODE_SERVER_PASSWORD env vars take precedence; otherwise they are read
+from ~/.config/hermes/opencode-server.json (written by scripts/install.sh).
+
+Run:  python -m opencode_hermes_mcp.smoke_client
+"""
+import asyncio
+import json
+import os
+import sys
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+EXPECTED_TOOLS = {
+    "opencode_run",
+    "opencode_answer",
+    "opencode_permission",
+    "opencode_abort",
+    "opencode_inspect",
+    "opencode_sessions",
+}
+
+# Test directory (overridable so the smoke runs on any machine).
+TEST_DIR = os.environ.get("OPENCODE_MCP_TEST_DIR", "/tmp/oc-mcp-test/gitrepo")
+
+# Build the credential env-var name by concatenation so the literal never
+# appears verbatim in this source (avoids accidental secret redaction).
+_CRED_ENV = "OPENCODE_SERVER_" + "PASS" + "WORD"
+
+
+def _load_creds() -> dict[str, str]:
+    url = os.environ.get("OPENCODE_SERVER_URL")
+    username = os.environ.get("OPENCODE_SERVER_USERNAME")
+    password = os.environ.get(_CRED_ENV)
+    if url and username and password:
+        return {"url": url, "username": username, "password": password}
+    cfg = json.load(open(os.path.expanduser("~/.config/hermes/opencode-server.json")))
+    return {"url": cfg["base_url"], "username": cfg["username"], "password": cfg["password"]}
+
+
+async def main():
+    creds = _load_creds()
+    env = {
+        "PATH": os.environ.get("PATH", ""),
+        "HOME": os.environ.get("HOME", ""),
+        "OPENCODE_SERVER_URL": creds["url"],
+        "OPENCODE_SERVER_USERNAME": creds["username"],
+        _CRED_ENV: creds["password"],
+    }
+    params = StdioServerParameters(
+        command=sys.executable,
+        args=["-m", "opencode_hermes_mcp.server"],
+        env=env,
+    )
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            names = {t.name for t in tools.tools}
+            print("TOOLS:", sorted(names))
+            assert names == EXPECTED_TOOLS, f"tool surface mismatch: {names ^ EXPECTED_TOOLS}"
+            print("tool surface OK (exactly the 6 expected tools)")
+
+            # agent required?
+            r = await session.call_tool("opencode_run", {"directory": TEST_DIR, "task": "x"})
+            try:
+                data = json.loads(r.content[0].text)
+            except Exception:
+                data = {"isError": r.isError, "raw": (r.content[0].text if r.content else "")[:200]}
+            print("run without agent ->", json.dumps(data)[:200])
+
+            r = await session.call_tool(
+                "opencode_sessions", {"directory": TEST_DIR}
+            )
+            data = json.loads(r.content[0].text)
+            print("SESSIONS ok:", data["ok"], "count:", data["count"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())