Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

fix(hermes): bridge EOF - byte streams, stderr drain, retry loop (#92)

3c0m3x56dd3dd27d47
diff --git a/plugins/hermes/bridge.py b/plugins/hermes/bridge.py
index 7a52509f..dd444085 100644
--- a/plugins/hermes/bridge.py
+++ b/plugins/hermes/bridge.py
@@ -15,6 +15,8 @@ from __future__ import annotations
import json
import subprocess
+import threading
+import time
from typing import Any, Protocol, runtime_checkable
PROTOCOL_VERSION = "2025-06-18"
@@ -51,8 +53,14 @@ class JsonRpcStdioClient:
"""Newline-delimited JSON-RPC 2.0 client over a writer/reader pair.
``writer`` needs ``write`` (and optionally ``flush``); ``reader`` needs
- ``readline`` returning ``str`` (``""`` at EOF). Responses are correlated by
- id; notifications and stale ids are skipped.
+ ``readline`` returning ``bytes`` (``b""`` at EOF). Responses are correlated
+ by id; notifications and stale ids are skipped.
+
+ Popen with ``bufsize=0`` (no ``text=True``) gives raw byte streams; the
+ client decodes UTF-8 itself. This avoids the line-buffering deadlock that
+ ``text=True, bufsize=1`` classically triggers with Popen pipes: a fast
+ child writer + a slow parent reader fills the kernel buffer and both
+ block, surfacing as a silent EOF on the JSON-RPC channel.
"""
def __init__(self, writer: Any, reader: Any) -> None:
@@ -77,7 +85,8 @@ class JsonRpcStdioClient:
def _write(self, frame: dict[str, Any]) -> None:
try:
- self._writer.write(json.dumps(frame) + "\n")
+ payload = (json.dumps(frame) + "\n").encode("utf-8")
+ self._writer.write(payload)
flush = getattr(self._writer, "flush", None)
if callable(flush):
flush()
@@ -87,8 +96,13 @@ class JsonRpcStdioClient:
def _read_response(self, rid: int) -> Any:
while True:
line = self._reader.readline()
- if line == "":
+ # EOF arrives as b"" from a bytes reader, as "" from a str reader
+ # (e.g. the StringIO-based _ScriptedReader in test_memory_provider),
+ # and as None from a closed pipe. All three terminate the read.
+ if line is None or line == b"" or line == "":
raise BridgeTransportError("unexpected EOF from MCP server")
+ if isinstance(line, bytes):
+ line = line.decode("utf-8", errors="replace")
line = line.strip()
if not line:
continue
@@ -135,15 +149,50 @@ class McpBrainBridge:
return argv
def _default_spawn(self, argv: list[str]) -> Any:
- return subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
+ # Use a small thread to drain stderr continuously; otherwise the child
+ # can block on a full stderr pipe after logging init warnings and
+ # silently die before its first stdout write - surfacing as
+ # "unexpected EOF" on the JSON-RPC read. `bufsize=0` on the pipes
+ # avoids the line-buffering deadlock that `text=True, bufsize=1`
+ # classically triggers with Popen pipes: a fast child writer +
+ # a slow parent reader fills the kernel buffer and both block.
+ process = subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
argv,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
- stderr=subprocess.DEVNULL,
- text=True,
- bufsize=1,
+ stderr=subprocess.PIPE,
+ bufsize=0,
cwd=self._cwd,
)
+ stderr_thread = threading.Thread(
+ target=self._drain_stderr,
+ args=(process,),
+ daemon=True,
+ name="o2b-mcp-stderr-drain",
+ )
+ stderr_thread.start()
+ return process
+
+ @staticmethod
+ def _drain_stderr(process: Any) -> None:
+ """Read stderr line-by-line until the child exits; discard contents.
+
+ Runs in a daemon thread so a misbehaving child (one that floods
+ stderr) cannot wedge the parent. Without this, a `stderr=PIPE` child
+ that writes more than the kernel pipe buffer (~64 KiB on Linux) will
+ block on its next stderr write, which surfaces in the parent as a
+ silent death of the JSON-RPC channel.
+ """
+ try:
+ stream = getattr(process, "stderr", None)
+ if stream is None:
+ return
+ for _line in iter(stream.readline, b""):
+ # Drain and discard; we do not currently surface stderr to
+ # the agent, but a future diagnostic flag could log it.
+ pass
+ except Exception: # noqa: BLE001 - drain must never raise
+ pass
def start(self) -> None:
if self._started:
@@ -173,18 +222,65 @@ class McpBrainBridge:
return self._tools
def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
- self._ensure_started()
- assert self._client is not None
- try:
- result = self._client.request("tools/call", {"name": name, "arguments": args})
- except BridgeTransportError:
- # The channel died: restart once and retry. A JSON-RPC error
- # (plain BridgeError, e.g. invalid arguments) is a server-level
- # rejection and propagates unchanged - restarting would only repeat it.
- self._restart()
- assert self._client is not None
- result = self._client.request("tools/call", {"name": name, "arguments": args})
- return result or {}
+ # Hard cap on restarts: o2b mcp can flake under load (e.g. bun runtime
+ # SIGPIPE on a parent process briefly holding the pipe). One restart is
+ # not enough; a bounded retry with backoff turns a transient subproc
+ # death into a successful call instead of an EOF error to the agent.
+ # A plain BridgeError (JSON-RPC rejection) is server-level and never
+ # triggers a restart - it would only repeat.
+ max_attempts = 3
+ backoff_seconds = 0.1
+ last_transport_error: BridgeTransportError | None = None
+ for attempt in range(max_attempts):
+ try:
+ # Spawn / handshake / restart all live inside the try: a
+ # transport failure while bringing a replacement child up is
+ # just as retryable as one on the request itself. Otherwise a
+ # dead -> dead -> good sequence would abort on the second dead
+ # child and collapse back to single-restart behaviour.
+ self._ensure_started()
+ assert self._client is not None
+ if self._is_proc_dead():
+ # Subprocess died between the last call and now: restart, then try.
+ self._restart()
+ assert self._client is not None
+ result = self._client.request(
+ "tools/call", {"name": name, "arguments": args}
+ )
+ return result or {}
+ except BridgeTransportError as exc:
+ last_transport_error = exc
+ if attempt + 1 >= max_attempts:
+ break
+ # Restart and back off briefly before the next attempt. A
+ # restart that itself fails to hand-shake is captured, not
+ # raised, so the remaining attempts still run.
+ try:
+ self._restart()
+ except BridgeTransportError as restart_exc:
+ last_transport_error = restart_exc
+ if backoff_seconds > 0:
+ time.sleep(backoff_seconds)
+ backoff_seconds *= 2
+ assert last_transport_error is not None # for type-checkers
+ raise last_transport_error
+
+ def _is_proc_dead(self) -> bool:
+ """poll() the owned subprocess; return True if it has exited.
+
+ Cheap health check that catches the case where the child died between
+ the last successful call and this one (e.g. parent process briefly held
+ the stdin pipe, child got SIGPIPE). Without this guard, the next write
+ surfaces as a BrokenPipe that the EOF handler would otherwise see as a
+ one-off flake and restart from - slow and noisy.
+ """
+ proc = self._proc
+ if proc is None:
+ return True
+ poll = getattr(proc, "poll", None)
+ if not callable(poll):
+ return False
+ return poll() is not None
def stop(self) -> None:
proc = self._proc
diff --git a/tests/python/test_memory_provider.py b/tests/python/test_memory_provider.py
index 3adabb19..aeea3460 100644
--- a/tests/python/test_memory_provider.py
+++ b/tests/python/test_memory_provider.py
@@ -516,12 +516,12 @@ class _ScriptedReader:
"""Readline source that yields pre-built JSON-RPC frames in order."""
def __init__(self, frames):
- self._lines = [json.dumps(f) + "\n" for f in frames]
+ self._lines = [(json.dumps(f) + "\n").encode("utf-8") for f in frames]
self._i = 0
def readline(self):
if self._i >= len(self._lines):
- return ""
+ return b""
line = self._lines[self._i]
self._i += 1
return line
@@ -531,7 +531,7 @@ class _FakeProcess:
"""Minimal Popen stand-in: captures stdin writes, scripts stdout reads."""
def __init__(self, responses):
- self.stdin = io.StringIO()
+ self.stdin = io.BytesIO()
self.stdout = _ScriptedReader(responses)
self.terminated = False
self._returncode = None
@@ -553,7 +553,7 @@ class _FakeProcess:
class JsonRpcStdioClientTests(unittest.TestCase):
def test_request_correlates_by_id_and_skips_noise(self):
- writer = io.StringIO()
+ writer = io.BytesIO()
# A notification (no id) and a mismatched id must be skipped before
# the matching response is returned.
reader = _ScriptedReader(
@@ -574,12 +574,12 @@ class JsonRpcStdioClientTests(unittest.TestCase):
reader = _ScriptedReader(
[{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "nope"}}]
)
- client = JsonRpcStdioClient(io.StringIO(), reader)
+ client = JsonRpcStdioClient(io.BytesIO(), reader)
with self.assertRaises(BridgeError):
client.request("missing", {})
def test_eof_raises(self):
- client = JsonRpcStdioClient(io.StringIO(), _ScriptedReader([]))
+ client = JsonRpcStdioClient(io.BytesIO(), _ScriptedReader([]))
with self.assertRaises(BridgeError):
client.request("ping", {})
@@ -676,6 +676,23 @@ class McpBrainBridgeTests(unittest.TestCase):
self.assertEqual(result, {"ok": True})
self.assertEqual(spawn.state["n"], 2)
+ def test_transport_error_retries_through_failed_restart(self):
+ # Regression: a restart whose OWN handshake dies must not abort the
+ # retry loop. dead-on-call -> dead-on-handshake -> good. The middle
+ # child EOFs during initialize, so _restart() raises; the loop must
+ # capture that and still reach the third, healthy child.
+ first = _FakeProcess(self._handshake_frames()) # no id-3 -> EOF on the call
+ broken = _FakeProcess([]) # EOF during handshake -> _restart() raises
+ good = _FakeProcess(
+ self._handshake_frames([{"jsonrpc": "2.0", "id": 3, "result": {"ok": True}}])
+ )
+ spawn = self._counting_spawn(first, broken, good)
+ bridge = McpBrainBridge(vault="/v", spawn=spawn)
+ bridge.start()
+ result = bridge.call_tool("brain_query", {"topic": "x"})
+ self.assertEqual(result, {"ok": True})
+ self.assertEqual(spawn.state["n"], 3)
+
class FakeBrainBridgeTests(unittest.TestCase):
def test_records_calls_and_returns_canned_results(self):