opencode-hermes-mcp 0.4.1__tar.gz → 0.4.2__tar.gz

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-hermes-mcp
-Version: 0.4.1
+Version: 0.4.2
 Summary: Deterministic MCP controller between Hermes (supervisor LLM) and the permanent OpenCode server. OpenCode pin defined in opencode_hermes_mcp/pin.txt (currently 1.18.21).
 Author-email: Arthur Hottier <arthur.ho2tier@gmail.com>
 License: MIT
@@ -195,6 +195,25 @@ The launcher reads the OpenCode server credentials from
 `python -m opencode_hermes_mcp.server` in the repo venv — `config.yaml` stays
 secret-free.
 
+## Delegation journal
+
+Every `opencode_run` is recorded in a durable, append-only JSONL journal so
+the delegation history survives sessions (the per-turn state file
+`turn_<sid>.json` is cleared on completion). One line per record:
+
+```json
+{"ts": 1787750000123, "kind": "start", "session_id": "ses_...", "directory": "/abs/repo", "agent": "build", "task": "...(truncated to 500 chars)"}
+{"ts": 1787750100456, "kind": "end", "session_id": "ses_...", "directory": "/abs/repo", "state": "completed|error|aborted|timeout", "elapsed_ms": 100333, "files": 12, "additions": 1209, "deletions": 18, "changed_files": ["a.py", "..."]}
+```
+
+- Path: `~/.local/state/opencode-hermes-mcp/delegations.jsonl` by default,
+  overridable with the `OPENCODE_HERMES_MCP_JOURNAL` env var.
+- `ts` is epoch milliseconds; `state` is the run's terminal state;
+  `changed_files` is truncated to 50 entries.
+- The journal is best-effort: a write failure (disk full, permissions) is
+  logged and swallowed — it never fails a run.
+- Read-only access for consumers: `opencode_hermes_mcp.journal.read_journal()`.
+
 ## TUI attach helpers (watch OpenCode live)
 
 `install.sh` also drops two helpers into `~/.local/bin/` (sources:
@@ -277,8 +296,10 @@ smoke test and the integration suite, and the contribution conventions.
 | `opencode_hermes_mcp/controller.py` | state machine: submit / wait / resume / classify |
 | `opencode_hermes_mcp/client.py` | HTTP + SSE client for the OpenCode server |
 | `opencode_hermes_mcp/models.py` | data helpers for turns / interactions |
+| `opencode_hermes_mcp/journal.py` | durable delegation journal (append-only JSONL) |
 | `opencode_hermes_mcp/smoke_client.py` | no-LLM smoke test (tool surface + basic calls) |
 | `tests/run_tests.py` | full integration suite (live LLM turns) |
+| `tests/test_journal.py` | journal unit tests (pytest) |
 | `opencode_hermes_mcp/installer.py` | setup wizard (Python + rich; self-bootstrapping venv) |
 | `opencode_hermes_mcp/pin.txt` | the OpenCode version pin (single source of truth, one line) |
 | `scripts/install.sh` / `uninstall.sh` / `upgrade.sh` | lifecycle (`install.sh` is a thin wrapper around the wizard) |

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/README.md

@@ -167,6 +167,25 @@ The launcher reads the OpenCode server credentials from
 `python -m opencode_hermes_mcp.server` in the repo venv — `config.yaml` stays
 secret-free.
 
+## Delegation journal
+
+Every `opencode_run` is recorded in a durable, append-only JSONL journal so
+the delegation history survives sessions (the per-turn state file
+`turn_<sid>.json` is cleared on completion). One line per record:
+
+```json
+{"ts": 1787750000123, "kind": "start", "session_id": "ses_...", "directory": "/abs/repo", "agent": "build", "task": "...(truncated to 500 chars)"}
+{"ts": 1787750100456, "kind": "end", "session_id": "ses_...", "directory": "/abs/repo", "state": "completed|error|aborted|timeout", "elapsed_ms": 100333, "files": 12, "additions": 1209, "deletions": 18, "changed_files": ["a.py", "..."]}
+```
+
+- Path: `~/.local/state/opencode-hermes-mcp/delegations.jsonl` by default,
+  overridable with the `OPENCODE_HERMES_MCP_JOURNAL` env var.
+- `ts` is epoch milliseconds; `state` is the run's terminal state;
+  `changed_files` is truncated to 50 entries.
+- The journal is best-effort: a write failure (disk full, permissions) is
+  logged and swallowed — it never fails a run.
+- Read-only access for consumers: `opencode_hermes_mcp.journal.read_journal()`.
+
 ## TUI attach helpers (watch OpenCode live)
 
 `install.sh` also drops two helpers into `~/.local/bin/` (sources:
@@ -249,8 +268,10 @@ smoke test and the integration suite, and the contribution conventions.
 | `opencode_hermes_mcp/controller.py` | state machine: submit / wait / resume / classify |
 | `opencode_hermes_mcp/client.py` | HTTP + SSE client for the OpenCode server |
 | `opencode_hermes_mcp/models.py` | data helpers for turns / interactions |
+| `opencode_hermes_mcp/journal.py` | durable delegation journal (append-only JSONL) |
 | `opencode_hermes_mcp/smoke_client.py` | no-LLM smoke test (tool surface + basic calls) |
 | `tests/run_tests.py` | full integration suite (live LLM turns) |
+| `tests/test_journal.py` | journal unit tests (pytest) |
 | `opencode_hermes_mcp/installer.py` | setup wizard (Python + rich; self-bootstrapping venv) |
 | `opencode_hermes_mcp/pin.txt` | the OpenCode version pin (single source of truth, one line) |
 | `scripts/install.sh` / `uninstall.sh` / `upgrade.sh` | lifecycle (`install.sh` is a thin wrapper around the wizard) |

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/opencode_hermes_mcp/__init__.py

@@ -3,4 +3,4 @@ LLM) and the permanent OpenCode server. No LLM: a state machine + HTTP/SSE
 client, pinned to the OpenCode version in opencode_hermes_mcp/pin.txt
 (currently 1.18.21)."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/opencode_hermes_mcp/controller.py

@@ -22,6 +22,7 @@ import os
 import time
 from typing import Any
 
+from . import journal
 from .client import OpenCode, OpenCodeError, event_stream
 from .models import (
     assistant_text,
@@ -621,7 +622,17 @@ class Controller:
                     turn["assistant_count_before"] = sum(
                         1 for m in pre if (m.get("info") or {}).get("role") == "assistant"
                     )
-                return await self._wait(turn, timeout)
+                journal.append_start(sid, directory, turn.get("agent"), task)
+                result = await self._wait(turn, timeout)
+                if result.get("state") in ("completed", "error", "aborted", "timeout"):
+                    diff = result.get("diff") or {}
+                    journal.append_end(
+                        sid, directory, result["state"],
+                        (result.get("timing") or {}).get("elapsed_ms"),
+                        diff.get("files"), diff.get("additions"), diff.get("deletions"),
+                        diff.get("changed_files"),
+                    )
+                return result
         else:
             try:
                 sess = await self.oc.create_session(
@@ -665,7 +676,17 @@ class Controller:
                 "error": f"failed to submit prompt: {exc}",
                 "session_id": sid,
             }
-        return await self._wait(turn, timeout)
+        journal.append_start(sid, directory, turn.get("agent"), task)
+        result = await self._wait(turn, timeout)
+        if result.get("state") in ("completed", "error", "aborted", "timeout"):
+            diff = result.get("diff") or {}
+            journal.append_end(
+                sid, directory, result["state"],
+                (result.get("timing") or {}).get("elapsed_ms"),
+                diff.get("files"), diff.get("additions"), diff.get("deletions"),
+                diff.get("changed_files"),
+            )
+        return result
 
     # ------------------------------------------------------------------ #
     # Resume primitives (answer / permission) — same turn, no resubmit

opencode_hermes_mcp-0.4.2/opencode_hermes_mcp/journal.py

@@ -0,0 +1,121 @@
+"""Durable delegation journal (append-only JSONL).
+
+Records the start and terminal state of every controller run so the
+delegation history survives sessions (the per-turn state file
+turn_<sid>.json is cleared on completion). The journal is best-effort:
+any write failure is logged and swallowed — it must never fail a run.
+
+Path: ~/.local/state/opencode-hermes-mcp/delegations.jsonl by default,
+overridable via the OPENCODE_HERMES_MCP_JOURNAL env var.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+ENV_JOURNAL = "OPENCODE_HERMES_MCP_JOURNAL"
+DEFAULT_JOURNAL = Path(
+    os.path.join(
+        os.path.expanduser("~"), ".local", "state", "opencode-hermes-mcp", "delegations.jsonl"
+    )
+)
+TASK_MAX_CHARS = 500
+CHANGED_FILES_MAX = 50
+
+
+def journal_path() -> Path:
+    """Journal path: env override (OPENCODE_HERMES_MCP_JOURNAL) or default."""
+    return Path(os.environ.get(ENV_JOURNAL) or DEFAULT_JOURNAL)
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _append(record: dict[str, Any]) -> None:
+    """Append one JSON line (open 'a', one full write, flush + fsync).
+
+    Never raises: a journal failure is logged and swallowed.
+    """
+    try:
+        path = journal_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(record, ensure_ascii=False) + "\n"
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(line)
+            f.flush()
+            os.fsync(f.fileno())
+    except Exception as exc:  # noqa: BLE001 — the journal must never fail a run
+        log.warning("journal: append %s failed: %s", record.get("kind"), exc)
+
+
+def append_start(session_id: str, directory: str, agent: str | None, task: str) -> None:
+    """Record a run start (session resolved, before the wait)."""
+    _append(
+        {
+            "ts": _now_ms(),
+            "kind": "start",
+            "session_id": session_id,
+            "directory": directory,
+            "agent": agent,
+            "task": (task or "")[:TASK_MAX_CHARS],
+        }
+    )
+
+
+def append_end(
+    session_id: str,
+    directory: str,
+    state: str,
+    elapsed_ms: int | None = None,
+    files: int | None = None,
+    additions: int | None = None,
+    deletions: int | None = None,
+    changed_files: list[str] | None = None,
+) -> None:
+    """Record a run's terminal state (completed / error / aborted / timeout)."""
+    _append(
+        {
+            "ts": _now_ms(),
+            "kind": "end",
+            "session_id": session_id,
+            "directory": directory,
+            "state": state,
+            "elapsed_ms": elapsed_ms,
+            "files": files,
+            "additions": additions,
+            "deletions": deletions,
+            "changed_files": (changed_files or [])[:CHANGED_FILES_MAX],
+        }
+    )
+
+
+def read_journal(path: str | Path | None = None) -> list[dict[str, Any]]:
+    """Read the journal (read-only, for tests and consumers).
+
+    Missing file -> []. Malformed lines are skipped.
+    """
+    p = Path(path) if path is not None else journal_path()
+    try:
+        with open(p, encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return []
+    records: list[dict[str, Any]] = []
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(rec, dict):
+            records.append(rec)
+    return records

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/opencode_hermes_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-hermes-mcp
-Version: 0.4.1
+Version: 0.4.2
 Summary: Deterministic MCP controller between Hermes (supervisor LLM) and the permanent OpenCode server. OpenCode pin defined in opencode_hermes_mcp/pin.txt (currently 1.18.21).
 Author-email: Arthur Hottier <arthur.ho2tier@gmail.com>
 License: MIT
@@ -195,6 +195,25 @@ The launcher reads the OpenCode server credentials from
 `python -m opencode_hermes_mcp.server` in the repo venv — `config.yaml` stays
 secret-free.
 
+## Delegation journal
+
+Every `opencode_run` is recorded in a durable, append-only JSONL journal so
+the delegation history survives sessions (the per-turn state file
+`turn_<sid>.json` is cleared on completion). One line per record:
+
+```json
+{"ts": 1787750000123, "kind": "start", "session_id": "ses_...", "directory": "/abs/repo", "agent": "build", "task": "...(truncated to 500 chars)"}
+{"ts": 1787750100456, "kind": "end", "session_id": "ses_...", "directory": "/abs/repo", "state": "completed|error|aborted|timeout", "elapsed_ms": 100333, "files": 12, "additions": 1209, "deletions": 18, "changed_files": ["a.py", "..."]}
+```
+
+- Path: `~/.local/state/opencode-hermes-mcp/delegations.jsonl` by default,
+  overridable with the `OPENCODE_HERMES_MCP_JOURNAL` env var.
+- `ts` is epoch milliseconds; `state` is the run's terminal state;
+  `changed_files` is truncated to 50 entries.
+- The journal is best-effort: a write failure (disk full, permissions) is
+  logged and swallowed — it never fails a run.
+- Read-only access for consumers: `opencode_hermes_mcp.journal.read_journal()`.
+
 ## TUI attach helpers (watch OpenCode live)
 
 `install.sh` also drops two helpers into `~/.local/bin/` (sources:
@@ -277,8 +296,10 @@ smoke test and the integration suite, and the contribution conventions.
 | `opencode_hermes_mcp/controller.py` | state machine: submit / wait / resume / classify |
 | `opencode_hermes_mcp/client.py` | HTTP + SSE client for the OpenCode server |
 | `opencode_hermes_mcp/models.py` | data helpers for turns / interactions |
+| `opencode_hermes_mcp/journal.py` | durable delegation journal (append-only JSONL) |
 | `opencode_hermes_mcp/smoke_client.py` | no-LLM smoke test (tool surface + basic calls) |
 | `tests/run_tests.py` | full integration suite (live LLM turns) |
+| `tests/test_journal.py` | journal unit tests (pytest) |
 | `opencode_hermes_mcp/installer.py` | setup wizard (Python + rich; self-bootstrapping venv) |
 | `opencode_hermes_mcp/pin.txt` | the OpenCode version pin (single source of truth, one line) |
 | `scripts/install.sh` / `uninstall.sh` / `upgrade.sh` | lifecycle (`install.sh` is a thin wrapper around the wizard) |

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/opencode_hermes_mcp.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ opencode_hermes_mcp/__init__.py
 opencode_hermes_mcp/client.py
 opencode_hermes_mcp/controller.py
 opencode_hermes_mcp/installer.py
+opencode_hermes_mcp/journal.py
 opencode_hermes_mcp/models.py
 opencode_hermes_mcp/pin.txt
 opencode_hermes_mcp/server.py
@@ -14,4 +15,5 @@ opencode_hermes_mcp.egg-info/SOURCES.txt
 opencode_hermes_mcp.egg-info/dependency_links.txt
 opencode_hermes_mcp.egg-info/entry_points.txt
 opencode_hermes_mcp.egg-info/requires.txt
-opencode_hermes_mcp.egg-info/top_level.txt
+opencode_hermes_mcp.egg-info/top_level.txt
+tests/test_journal.py

{opencode_hermes_mcp-0.4.1 → opencode_hermes_mcp-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opencode-hermes-mcp"
-version = "0.4.1"
+version = "0.4.2"
 description = "Deterministic MCP controller between Hermes (supervisor LLM) and the permanent OpenCode server. OpenCode pin defined in opencode_hermes_mcp/pin.txt (currently 1.18.21)."
 readme = "README.md"
 license = {text = "MIT"}

opencode_hermes_mcp-0.4.2/tests/test_journal.py

@@ -0,0 +1,83 @@
+"""Unit tests for the durable delegation journal (opencode_hermes_mcp.journal).
+
+Pure unit tests: no LLM, no server. Run with:
+  .venv/bin/python -m pytest tests/test_journal.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from opencode_hermes_mcp import journal  # noqa: E402
+
+
+def test_journal_path_default(monkeypatch):
+    monkeypatch.delenv(journal.ENV_JOURNAL, raising=False)
+    p = journal.journal_path()
+    assert p.name == "delegations.jsonl"
+    assert p.parent.name == "opencode-hermes-mcp"
+    assert ".local" in p.parts and "state" in p.parts
+
+
+def test_journal_path_env_override(tmp_path, monkeypatch):
+    custom = tmp_path / "custom" / "delegations.jsonl"
+    monkeypatch.setenv(journal.ENV_JOURNAL, str(custom))
+    assert journal.journal_path() == custom
+
+
+def test_append_start_end_jsonl_format(tmp_path, monkeypatch):
+    custom = tmp_path / "sub" / "delegations.jsonl"
+    monkeypatch.setenv(journal.ENV_JOURNAL, str(custom))
+    journal.append_start("ses_1", "/repo", "build", "t" * 600)
+    journal.append_end(
+        "ses_1", "/repo", "completed",
+        elapsed_ms=1234, files=2, additions=10, deletions=1,
+        changed_files=[f"f{i}.py" for i in range(60)],
+    )
+    lines = custom.read_text(encoding="utf-8").splitlines()
+    assert len(lines) == 2
+    start, end = (json.loads(line) for line in lines)
+    assert start["kind"] == "start"
+    assert start["session_id"] == "ses_1"
+    assert start["directory"] == "/repo"
+    assert start["agent"] == "build"
+    assert start["task"] == "t" * 500
+    assert isinstance(start["ts"], int) and start["ts"] > 0
+    assert end["kind"] == "end"
+    assert end["session_id"] == "ses_1"
+    assert end["state"] == "completed"
+    assert end["elapsed_ms"] == 1234
+    assert end["files"] == 2
+    assert end["additions"] == 10
+    assert end["deletions"] == 1
+    assert len(end["changed_files"]) == 50
+    assert end["ts"] >= start["ts"]
+
+
+def test_read_journal(tmp_path, monkeypatch):
+    custom = tmp_path / "d.jsonl"
+    monkeypatch.setenv(journal.ENV_JOURNAL, str(custom))
+    assert journal.read_journal() == []
+    journal.append_start("ses_2", "/r", "plan", "hello")
+    journal.append_end("ses_2", "/r", "error")
+    recs = journal.read_journal()
+    assert [r["kind"] for r in recs] == ["start", "end"]
+    assert recs[1]["state"] == "error"
+    assert journal.read_journal(custom) == recs
+
+
+def test_read_journal_skips_bad_lines(tmp_path):
+    p = tmp_path / "bad.jsonl"
+    p.write_text('{"kind": "start", "session_id": "s"}\nnot-json\n\n', encoding="utf-8")
+    recs = journal.read_journal(p)
+    assert len(recs) == 1
+    assert recs[0]["kind"] == "start"
+
+
+def test_append_never_raises_on_unwritable_path(tmp_path, monkeypatch):
+    monkeypatch.setenv(journal.ENV_JOURNAL, "/proc/no-such-dir-ocmcp/delegations.jsonl")
+    journal.append_start("ses_x", "/r", "build", "task")
+    journal.append_end("ses_x", "/r", "completed", elapsed_ms=1)