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
"""Bridge from the Python memory provider to the Open Second Brain TS core.
The provider never reimplements deterministic memory logic; it forwards work
to the existing ``o2b mcp`` stdio server over MCP JSON-RPC. ``BrainBridge`` is
the seam: ``McpBrainBridge`` is the production backend that owns a long-lived
``o2b mcp`` subprocess, and ``FakeBrainBridge`` lets tests exercise the
provider with no live Bun runtime.
Splitting ``JsonRpcStdioClient`` (pure framing) from ``McpBrainBridge`` (process
lifecycle) keeps each class single-responsibility and lets the framing be
unit-tested against in-memory streams.
"""
from __future__ import annotations
import json
import logging
import math
import os
import subprocess
import sys
import threading
import time
from collections import deque
from collections.abc import Mapping
from typing import Any, Protocol, runtime_checkable
from .config import REQUEST_TIMEOUT_ENV, env_setting
PROTOCOL_VERSION = "2025-06-18"
# The harness this bridge launches the server for. The server resolves its
# harness scope (which harness-scoped operator rules apply) from this launch
# argument alone, never from the name a client gives about itself.
HARNESS_ARGV: tuple[str, ...] = ("--harness", "hermes")
CLIENT_NAME = "open-second-brain-hermes-provider"
logger = logging.getLogger(__name__)
# Purpose recorded in Hermes' spawn ledger (``hermes_cli.process_identity``) for
# the long-lived ``o2b mcp`` child, so an operator reading the ledger can tell
# which plugin owns a process group.
SPAWN_PURPOSE = "open-second-brain-mcp-bridge"
def _hermes_spawn_owned() -> Any:
"""Hermes' owner-death spawner, when this host provides it.
Hermes 0.23 replaced the per-child ``tools.mcp_stdio_watchdog`` wrapper with
one owner-death supervisor per process (hermes-agent commit 2d783a15):
``spawn_owned`` puts the child in a new process group and hands that group to
the supervisor, so the child and every descendant that stays in the group die
when the host dies by any cause, SIGKILL included. Older Hermes has only the
wrapper (see ``McpBrainBridge._watchdog_argv``); a standalone checkout has
neither and degrades to a plain spawn.
Returning ``None`` means "this host has no such seam". Any import failure is
that answer, not an error: an older or non-Hermes host raises ImportError,
and a broken Hermes import raises something else - neither may take the
bridge down.
"""
try:
from hermes_cli.process_identity import spawn_owned
except Exception: # noqa: BLE001 - absence is the expected answer, never fatal
return None
return spawn_owned
def _release_owned_child(proc: Any) -> None:
"""Hand a ``spawn_owned`` child's process group back after it was stopped.
Hermes prunes dead groups on its own, but that prune runs on the next
registration; releasing here closes the window in which a recycled pgid
could still be registered to a stranger's group. Best-effort by contract:
losing the bookkeeping must never fail a shutdown.
"""
pid = getattr(proc, "pid", None)
if not isinstance(pid, int):
return
try:
from hermes_cli.process_identity import release_process_group_once_empty
except Exception: # noqa: BLE001 - older host: no ledger to hand back
return
try:
release_process_group_once_empty(pid, proc=proc)
except Exception: # noqa: BLE001 - shutdown is best-effort
return
# A shared bridge is one stdio stream, so its calls are serialised: a child
# that stops answering blocks every agent in the gateway rather than one
# session. Nothing in this transport bounded a read before - with a bridge per
# session that was survivable, and with a shared one it is not. The deadline is
# generous on purpose: a tool call can legitimately take tens of seconds when
# it opens the store for writing and the integrity scan runs.
DEFAULT_REQUEST_TIMEOUT_SECONDS = 120.0
# ``REQUEST_TIMEOUT_ENV`` lives in config.py with the other profile-scoped
# names and is re-exported from here; on a multiplexed Hermes gateway it is
# read from the profile scope, never from the gateway's process environment.
# The child's stderr is where the runtime says why it refused to start ("error:
# 'bun' is not on PATH."), and the JSON-RPC channel only ever reports the
# consequence ("unexpected EOF"). Keep the tail of it so the exception can
# carry the cause. Bounded twice over - by line count and by total bytes - so a
# child that floods stderr cannot grow the parent's memory.
STDERR_TAIL_LINES = 20
STDERR_TAIL_MAX_BYTES = 8 * 1024
# Stderr is read in fixed-size chunks rather than by line. `readline` returns
# only at a newline or at EOF, so a child emitting one enormous unterminated
# record would be held whole in the parent before any truncation could apply -
# which is the exact failure this buffer exists to rule out.
STDERR_CHUNK_BYTES = 4096
# Time allowed for the drain thread to finish after the child is torn down,
# so the excerpt includes the last thing the child managed to write.
_STDERR_DRAIN_JOIN_SECONDS = 1.0
def resolve_request_timeout() -> float | None:
"""Seconds a single JSON-RPC round trip may take, or None to wait forever.
A non-positive value disables the deadline, which is the escape hatch for
an operator whose vault legitimately outruns it; it is spelled explicitly
rather than reached by a malformed value, and a malformed value falls back
to the default rather than to no bound at all. ``nan`` is malformed (it
never compares equal, so it would also split every shared-bridge key);
``inf`` is an explicit "no bound", like a non-positive value. The WARNING
names the variable only: the value belongs to a profile and lands in the
shared gateway log.
:raises config.ProfileScopeError: on a multiplexed gateway with no profile
scope bound; the provider resolves it once where the scope is bound
and hands the bridge the result (see ``McpBrainBridge(timeout=...)``).
"""
raw = env_setting(REQUEST_TIMEOUT_ENV)
if raw is None or raw.strip() == "":
return DEFAULT_REQUEST_TIMEOUT_SECONDS
try:
seconds = float(raw)
except ValueError:
seconds = math.nan
if math.isnan(seconds):
logger.warning(
"%s is not a number; using the %.0fs default",
REQUEST_TIMEOUT_ENV,
DEFAULT_REQUEST_TIMEOUT_SECONDS,
)
return DEFAULT_REQUEST_TIMEOUT_SECONDS
return None if seconds <= 0 or math.isinf(seconds) else seconds
class BridgeError(RuntimeError):
"""Base error: a JSON-RPC error response or a transport failure.
``code`` is the stable string code of a JSON-RPC error response
(``error.data.code``, for example ``unknown_argument``), so a caller
branches on a token instead of parsing the rendered message. It is
``None`` for a transport failure and for a response that names none.
"""
def __init__(self, message: str, code: str | None = None) -> None:
super().__init__(message)
self.code = code
def _error_code(error: Any) -> str | None:
"""The string ``error.data.code`` of a JSON-RPC error, or ``None``."""
data = error.get("data") if isinstance(error, dict) else None
code = data.get("code") if isinstance(data, dict) else None
return code if isinstance(code, str) else None
class BridgeTransportError(BridgeError):
"""The channel itself failed (EOF, broken pipe). Worth one restart.
Distinct from a plain ``BridgeError``, which signals a JSON-RPC error
response (e.g. invalid tool arguments) - a server-level rejection that a
restart would only repeat, so it must propagate unchanged.
"""
class BridgeTimeoutError(BridgeTransportError):
"""The child is alive but did not answer inside the request deadline.
A subclass of the transport error on purpose: the restart-and-retry ladder
that already handles a dead child is the right response to an unresponsive
one too, and a bridge nobody can get an answer from is not usefully
different from a bridge that died.
"""
@runtime_checkable
class BrainBridge(Protocol):
"""Minimal contract the provider depends on (Dependency Inversion)."""
def start(self) -> None: ...
def list_tools(self) -> list[dict[str, Any]]: ...
def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]: ...
def stop(self) -> None: ...
class JsonRpcStdioClient:
"""Newline-delimited JSON-RPC 2.0 client over a writer/reader pair.
``writer`` needs ``write`` (and optionally ``flush``); ``reader`` needs
``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, timeout: float | None = None) -> None:
self._writer = writer
self._reader = reader
self._id = 0
self._timeout = timeout
def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
frame: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
if params is not None:
frame["params"] = params
self._write(frame)
def request(self, method: str, params: dict[str, Any] | None = None) -> Any:
self._id += 1
rid = self._id
frame: dict[str, Any] = {"jsonrpc": "2.0", "id": rid, "method": method}
if params is not None:
frame["params"] = params
self._write(frame)
return self._read_response(rid)
def _write(self, frame: dict[str, Any]) -> None:
try:
payload = (json.dumps(frame) + "\n").encode("utf-8")
self._writer.write(payload)
flush = getattr(self._writer, "flush", None)
if callable(flush):
flush()
except (BrokenPipeError, ValueError, OSError) as exc:
raise BridgeTransportError(f"write failed: {exc}") from exc
def _readline(self, deadline: float | None) -> Any:
"""One line, or a timeout. Blocks plainly when no deadline is set.
A blocking ``readline`` on a pipe cannot be interrupted, so the read
runs on a daemon thread whose result is collected with the remaining
budget. The thread is left behind on a timeout deliberately: the caller
tears the child down, which closes the pipe and releases it. Daemon,
because a thread stuck on a dead pipe must never hold up interpreter
exit - the failure this whole change is about is a process that would
not go away.
"""
if deadline is None:
return self._reader.readline()
remaining = deadline - time.monotonic()
if remaining <= 0:
raise BridgeTimeoutError("no response from MCP server within the deadline")
box: list[Any] = []
error: list[BaseException] = []
def pump() -> None:
try:
box.append(self._reader.readline())
except BaseException as exc: # noqa: BLE001 - reported to the caller
error.append(exc)
worker = threading.Thread(target=pump, daemon=True)
worker.start()
worker.join(remaining)
if worker.is_alive():
raise BridgeTimeoutError(
f"no response from MCP server within {self._timeout:.0f}s"
)
if error:
raise BridgeTransportError(f"read failed: {error[0]}") from error[0]
return box[0] if box else None
def _read_response(self, rid: int) -> Any:
deadline = None if self._timeout is None else time.monotonic() + self._timeout
while True:
line = self._readline(deadline)
# 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
try:
message = json.loads(line)
except json.JSONDecodeError:
# stdout carries only JSON-RPC frames; ignore stray noise.
continue
if not isinstance(message, dict) or message.get("id") != rid:
continue
if "error" in message:
error = message["error"]
raise BridgeError(str(error), code=_error_code(error))
return message.get("result")
class McpBrainBridge:
"""Owns one ``o2b mcp`` subprocess and speaks MCP JSON-RPC to it.
``spawn`` is injectable so tests substitute a fake process and never need a
live Bun runtime. A crashed channel is restarted once on the next call.
``env`` is the complete environment the child runs with; ``None`` means
inherit this process's. A Hermes gateway can start the provider with a
``PATH`` too small to contain Bun, and the ``o2b`` wrapper refuses to run
when its own ``command -v bun`` misses - so the caller that resolved an
absolute Bun passes an environment carrying that Bun's directory.
``timeout`` fixes the per-request deadline at construction; a non-positive
value disables it. ``None`` (the default) reads it at every ``start`` as
before. A multiplexed Hermes gateway passes it, because a restart can run
on the plugin's own capture thread, where no profile scope is bound and the
scoped setting cannot be read.
"""
def __init__(
self,
*,
vault: str | None,
repo_root: str | None = None,
command: tuple[str, ...] = ("o2b", "mcp"),
spawn: Any = None,
cwd: str | None = None,
env: Mapping[str, str] | None = None,
timeout: float | None = None,
) -> None:
self._vault = vault
self._timeout = timeout
self._repo_root = repo_root
self._command = command
self._spawn = spawn or self._default_spawn
self._cwd = cwd
self._env = dict(env) if env is not None else None
# deque append/clear are atomic under the GIL, so the drain thread
# writes it and start() reads it with no extra lock.
self._stderr_tail: deque[str] = deque(maxlen=STDERR_TAIL_LINES)
self._stderr_thread: threading.Thread | None = None
# A gateway may serve several AIAgents concurrently, but one shared
# bridge has one request/response stream. Serialise lifecycle and RPC
# operations so request ids and stdout frames cannot interleave.
self._lock = threading.RLock()
self._proc: Any = None
self._client: JsonRpcStdioClient | None = None
self._tools: list[dict[str, Any]] = []
self._started = False
# True when the child was spawned through Hermes' owner-death
# supervisor, so stop() hands its process group back.
self._spawned_owned = False
def _argv(self) -> list[str]:
argv = list(self._command)
if self._vault:
argv += ["--vault", self._vault]
# Without --repo the server's repoRoot is null, so skill discovery
# only searches <vault>/Brain/skills and never the in-repo skills/
# directory - which silently empties skill_auto_attach.
if self._repo_root:
argv += ["--repo", self._repo_root]
argv += HARNESS_ARGV
return argv
_watchdog_absent_warned = False
@classmethod
def _warn_watchdog_absent(cls) -> None:
if cls._watchdog_absent_warned:
return
cls._watchdog_absent_warned = True
logger.warning(
"parent-death watchdog module unavailable; open-second-brain MCP "
"children will not be reaped if this process exits abruptly"
)
@staticmethod
def _watchdog_argv(argv: list[str]) -> list[str]:
"""Wrap POSIX MCP children in Hermes' parent-death watchdog."""
if os.name != "posix":
return argv
try:
from tools import mcp_stdio_watchdog
except ImportError:
# The plugin can still operate from a standalone checkout; the
# host's normal runtime has this module and gets descendant
# cleanup. Say so rather than degrading in silence: if the module
# is ever renamed, the guarantee disappears and nothing else would
# report it. Once per process, because this is a property of the
# installation and not of the call.
McpBrainBridge._warn_watchdog_absent()
return argv
watchdog_path = getattr(mcp_stdio_watchdog, "__file__", None)
if not watchdog_path:
return argv
return [
sys.executable,
str(watchdog_path),
"--ppid",
str(os.getpid()),
"--",
*argv,
]
def _default_spawn(self, argv: list[str]) -> Any:
# 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.
#
# Parent-death protection has two shapes across Hermes versions, and
# whichever this host has is applied here rather than around the argv:
# `spawn_owned` (0.23+) owns the child's process group; the legacy
# `tools.mcp_stdio_watchdog` wrapped argv in a poller (see
# `_watchdog_argv`). A standalone checkout has neither.
popen_kwargs: dict[str, Any] = dict(
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
bufsize=0,
cwd=self._cwd,
env=self._env,
# The Hermes desktop app is a GUI process: without this, Windows
# opens a console window for the Bun child and keeps it on screen
# for the life of the bridge. No-op flag value on POSIX.
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
)
spawn_owned = _hermes_spawn_owned()
if spawn_owned is not None:
process = spawn_owned(argv, purpose=SPAWN_PURPOSE, **popen_kwargs)
self._spawned_owned = True
else:
self._spawned_owned = False
process = subprocess.Popen( # noqa: S603 - argv is a fixed command + config path
self._watchdog_argv(argv),
**popen_kwargs,
)
stderr_thread = threading.Thread(
target=self._drain_stderr,
args=(process,),
daemon=True,
name="o2b-mcp-stderr-drain",
)
self._stderr_thread = stderr_thread
stderr_thread.start()
return process
def _append_stderr_line(self, raw: bytes) -> None:
"""Record one child stderr line, decoded and clipped to the budget."""
line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
if line:
self._stderr_tail.append(line[:STDERR_TAIL_MAX_BYTES])
def _drain_stderr(self, process: Any) -> None:
"""Read stderr until the child exits, keeping a bounded tail of it.
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.
Chunked rather than line-oriented, and the in-progress line is clipped
as it grows, so nothing here is proportional to what the child writes:
at most :data:`STDERR_TAIL_LINES` lines are kept and each is capped at
the byte budget, including a record that never sends a newline at all.
`read1` is preferred where the stream offers it, because a buffered
`read` waits for the full chunk and would hold the excerpt back until
the child had said that much more.
"""
try:
stream = getattr(process, "stderr", None)
if stream is None:
return
read = getattr(stream, "read1", None) or getattr(stream, "read", None)
if not callable(read):
return
partial = b""
while True:
chunk = read(STDERR_CHUNK_BYTES)
if not chunk:
break
if isinstance(chunk, str):
chunk = chunk.encode("utf-8", errors="replace")
*complete, partial = (partial + chunk).split(b"\n")
for raw in complete:
self._append_stderr_line(raw)
# Keep the head of an over-long record: it is where a runtime
# puts the message, and clipping here is what keeps a child
# that never emits a newline from growing the parent.
if len(partial) > STDERR_TAIL_MAX_BYTES:
partial = partial[:STDERR_TAIL_MAX_BYTES]
self._append_stderr_line(partial)
except Exception: # noqa: BLE001 - drain must never raise
pass
def _stderr_excerpt(self) -> str:
"""Buffered child stderr, newest lines last, capped at the byte budget."""
lines = list(self._stderr_tail)
excerpt = "\n".join(lines)
if len(excerpt) > STDERR_TAIL_MAX_BYTES:
excerpt = excerpt[-STDERR_TAIL_MAX_BYTES:]
return excerpt.strip()
def _with_stderr_excerpt(self, exc: BaseException) -> BaseException:
"""The handshake failure, re-stated with what the child said on stderr.
``stop()`` has already torn the child down, so the drain thread is
about to see EOF; give it a bounded moment to land its last lines
rather than reporting a truncated cause. Only transport failures are
rewritten - a JSON-RPC rejection came from a server that is talking,
and its stderr is noise - and the original exception is returned
untouched when the child said nothing.
"""
if not isinstance(exc, BridgeTransportError):
return exc
thread = self._stderr_thread
if thread is not None and thread.is_alive():
thread.join(_STDERR_DRAIN_JOIN_SECONDS)
excerpt = self._stderr_excerpt()
if not excerpt:
return exc
return type(exc)(f"{exc}\n--- child stderr (last lines) ---\n{excerpt}")
def _request_timeout(self) -> float | None:
if self._timeout is None:
return resolve_request_timeout()
return None if self._timeout <= 0 else self._timeout
def start(self) -> None:
with self._lock:
if self._started:
return
self._stderr_tail.clear()
self._stderr_thread = None
self._proc = self._spawn(self._argv())
self._client = JsonRpcStdioClient(
self._proc.stdin, self._proc.stdout, timeout=self._request_timeout()
)
pid = getattr(self._proc, "pid", "unknown")
logger.debug("open-second-brain MCP child spawned pid=%s", pid)
try:
self._client.request(
"initialize",
{
"protocolVersion": PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": CLIENT_NAME, "version": "1"},
},
)
self._client.notify("notifications/initialized")
result = self._client.request("tools/list", {})
except BaseException as exc:
# A failed handshake must not leak the spawned process.
logger.warning("open-second-brain MCP handshake failed pid=%s", pid)
self.stop()
explained = self._with_stderr_excerpt(exc)
if explained is exc:
raise
raise explained from exc
self._tools = list((result or {}).get("tools", []))
self._started = True
logger.debug("open-second-brain MCP child ready pid=%s", pid)
def list_tools(self) -> list[dict[str, Any]]:
with self._lock:
self._ensure_started()
return list(self._tools)
def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
with self._lock:
return self._call_tool(name, args)
def _call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
# 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:
with self._lock:
proc = self._proc
self._started = False
self._client = None
self._proc = None
if proc is None:
return
pid = getattr(proc, "pid", "unknown")
try:
poll = getattr(proc, "poll", None)
if not callable(poll) or poll() is None:
proc.terminate()
except Exception: # noqa: BLE001 - shutdown is best-effort
pass
try:
proc.wait(timeout=8)
except Exception: # noqa: BLE001 - escalate once, then still reap
kill = getattr(proc, "kill", None)
if callable(kill):
try:
kill()
except Exception: # noqa: BLE001
pass
try:
proc.wait(timeout=5)
except Exception: # noqa: BLE001
pass
finally:
# Release the parent's pipe descriptors as well as reaping the
# child. The old implementation only waited for the process.
for stream_name in ("stdin", "stdout", "stderr"):
stream = getattr(proc, stream_name, None)
close = getattr(stream, "close", None)
if callable(close):
try:
close()
except Exception: # noqa: BLE001
pass
if self._spawned_owned:
_release_owned_child(proc)
self._spawned_owned = False
logger.debug("open-second-brain MCP child stopped pid=%s", pid)
def _ensure_started(self) -> None:
if not self._started:
self.start()
def _restart(self) -> None:
self.stop()
self.start()
class FakeBrainBridge:
"""In-memory ``BrainBridge`` for tests: records calls, returns canned data."""
def __init__(
self,
tools: list[dict[str, Any]] | None = None,
results: dict[str, Any] | None = None,
) -> None:
self._tools = tools or []
self._results = results or {}
self.calls: list[tuple[str, dict[str, Any]]] = []
self.started = False
self.stopped = False
def start(self) -> None:
self.started = True
def list_tools(self) -> list[dict[str, Any]]:
return list(self._tools)
def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
self.calls.append((name, args))
result = self._results.get(name)
if callable(result):
return result(args)
return result if result is not None else {}
def stop(self) -> None:
self.stopped = True
__all__ = [
"BridgeError",
"BridgeTransportError",
"BrainBridge",
"JsonRpcStdioClient",
"McpBrainBridge",
"FakeBrainBridge",
"PROTOCOL_VERSION",
]