agent-peers 0.1.0

package/agent_peers/runtime.py

@@ -0,0 +1,293 @@
+"""Bounded subprocess transport and read-only runtime dependency checks."""
+
+from __future__ import annotations
+
+from concurrent.futures import Future, TimeoutError
+from contextvars import copy_context
+import json
+import logging
+import math
+import os
+from pathlib import Path
+from queue import Empty, Full, Queue
+import re
+import select
+import shlex
+import shutil
+import subprocess
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+MAX_LINE = 1_000_000
+QUEUE_MAX = 50
+PENDING_MAX = 64
+ROOT = Path(__file__).resolve().parent.parent
+_EXITED = "agent-peers bridge exited; delivery is unknown and was not retried"
+_TIMED_OUT = "agent-peers request timed out; delivery is unknown and was not retried"
+
+
+def context_thread(target, *, name, args=()):
+    """Carry public contextvars (including the host profile) into daemon workers."""
+    context = copy_context()
+    return threading.Thread(target=context.run, args=(target, *args), name=name, daemon=True)
+
+
+def bridge_environment():
+    # Discovery paths only; provider credentials and Node preload hooks stay out.
+    return {key: os.environ[key] for key in (
+        "PATH", "HOME", "XDG_RUNTIME_DIR", "CLAUDE_CONFIG_DIR", "CODEX_HOME",
+        "AGENT_PEERS_HOME", "AGENT_PEERS_CODEX_APP_SERVER",
+    ) if key in os.environ}
+
+
+def default_command(*, root=ROOT, hermes_home=None):
+    """Resolve a usable system or Hermes-managed Node without changing either."""
+    home = Path(hermes_home or os.environ.get("HERMES_HOME") or Path.home() / ".hermes")
+    homes = [home]
+    if home.parent.name == "profiles":
+        homes.append(home.parent.parent)
+    homes.append(Path.home() / ".hermes")
+    candidates = [str(path / suffix) for path in homes for suffix in ("node/bin/node", "node/node")]
+    if system := shutil.which("node"):
+        candidates.append(system)
+    env = bridge_environment()
+    deadline = time.monotonic() + 5
+    node = None
+    for candidate in dict.fromkeys(candidates):
+        if not os.access(candidate, os.X_OK) or not Path(candidate).is_file():
+            continue
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        try:
+            probe = subprocess.run([candidate, "--version"], stdout=subprocess.PIPE,
+                                   stderr=subprocess.DEVNULL, env=env, timeout=min(1, remaining), check=False)
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        match = re.fullmatch(rb"v(\d+)\.\d+\.\d+\s*", probe.stdout)
+        if probe.returncode == 0 and match and int(match[1]) >= 22:
+            node = str(Path(candidate).absolute())
+            break
+    if node is None:
+        raise RuntimeError("agent-peers requires Node.js 22 or newer on PATH or in the Hermes-managed node directory")
+    bridge = root / "bin" / "agent-peers.mjs"
+    if not bridge.is_file():
+        raise RuntimeError(f"agent-peers bridge is missing at {bridge}; install the whole repository as a Hermes plugin")
+    # Import the actual bridge module, without starting its stdin server. This
+    # catches missing and incompatible dependencies before the first request.
+    try:
+        probe = subprocess.run([node, "--input-type=module", "-e", "await import(process.argv[1])",
+                                (root / "src" / "hermes-bridge.mjs").as_uri()],
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                               env=env, timeout=5, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        raise RuntimeError("agent-peers bridge dependency check failed or timed out") from None
+    if probe.returncode:
+        command = shlex.join(["npm", "--prefix", str(root), "ci", "--omit=dev", "--ignore-scripts"])
+        raise RuntimeError(f"agent-peers bridge dependencies are unavailable; run: {command}")
+    return [node, str(bridge), "hermes-bridge"]
+
+
+class BridgeClient:
+    """One subprocess per plugin/profile; writes and responses share a deadline."""
+
+    def __init__(self, command: list[str], receive):
+        if not isinstance(command, list) or not command or not all(isinstance(x, str) and x for x in command):
+            raise ValueError("agent-peers bridge_command must be a nonempty executable/argument list")
+        self.command = list(command)
+        self.receive = receive
+        self._environment = bridge_environment()
+        self._lock = threading.RLock()
+        self._write_lock = threading.Lock()
+        self._process = None
+        self._reader = None
+        self._pending = {}
+        self._next = 0
+        self._stopped = False
+        self._messages = Queue(maxsize=QUEUE_MAX)
+        self._delivery = context_thread(self._deliver, name="agent-peers-delivery")
+        self._delivery.start()
+
+    def _start(self):
+        # Called under both locks. Only this path creates processes or reuses FDs.
+        if self._stopped:
+            raise RuntimeError("agent-peers plugin has been unloaded")
+        if self._process is not None:
+            if self._process.poll() is None:
+                return self._process
+            self._process.stdin.close()
+        process = subprocess.Popen(self.command, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                   stderr=subprocess.DEVNULL, env=self._environment)
+        os.set_blocking(process.stdin.fileno(), False)
+        self._process = process
+        self._reader = context_thread(self._read, name="agent-peers-reader", args=(process,))
+        self._reader.start()
+        return process
+
+    def _fail_pending(self, process, message):
+        with self._lock:
+            for owner, future in list(self._pending.values()):
+                if (process is None or owner is process) and not future.done():
+                    future.set_exception(RuntimeError(message))
+
+    def _write(self, process, data, deadline):
+        view = memoryview(data)
+        while view:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError()
+            if self._stopped or process.poll() is not None:
+                raise BrokenPipeError()
+            fd = process.stdin.fileno()
+            if not select.select([], [fd], [], min(remaining, 0.1))[1]:
+                continue
+            try:
+                written = os.write(fd, view)
+            except BlockingIOError:
+                continue
+            if written <= 0:
+                raise BrokenPipeError()
+            view = view[written:]
+
+    def call(self, method: str, params: dict | None = None, *, timeout: float = 25):
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("agent-peers timeout must be positive and finite")
+        deadline = time.monotonic() + timeout
+        request_id = None
+        if not self._write_lock.acquire(timeout=timeout):
+            raise RuntimeError("agent-peers bridge is busy; no message was sent")
+        try:
+            with self._lock:
+                if len(self._pending) >= PENDING_MAX:
+                    raise RuntimeError("agent-peers has too many pending requests; no message was sent")
+                self._next += 1
+                request_id = self._next
+                data = (json.dumps({"id": request_id, "method": method, "params": params or {}},
+                                   ensure_ascii=False) + "\n").encode("utf-8")
+                if len(data) > MAX_LINE:
+                    raise ValueError("agent-peers request exceeds the message size limit")
+                process = self._start()
+                future = Future()
+                self._pending[request_id] = (process, future)
+            try:
+                self._write(process, data, deadline)
+            except (TimeoutError, OSError, ValueError) as exc:
+                # A partially written frame cannot be reused safely.
+                try:
+                    process.terminate()
+                except OSError:
+                    pass
+                message = _TIMED_OUT if isinstance(exc, TimeoutError) else _EXITED
+                self._fail_pending(process, message)
+                raise RuntimeError(message) from None
+        except BaseException:
+            with self._lock:
+                self._pending.pop(request_id, None)
+            raise
+        finally:
+            self._write_lock.release()
+        try:
+            return future.result(timeout=max(0, deadline - time.monotonic()))
+        except TimeoutError:
+            raise RuntimeError(_TIMED_OUT) from None
+        finally:
+            with self._lock:
+                self._pending.pop(request_id, None)
+
+    def _read(self, process):
+        try:
+            while not self._stopped:
+                line = process.stdout.readline(MAX_LINE + 1)
+                if not line:
+                    break
+                if len(line) > MAX_LINE or not line.endswith(b"\n"):
+                    logger.warning("agent-peers bridge exceeded the protocol line limit")
+                    break
+                try:
+                    result = json.loads(line.decode("utf-8"))
+                except (ValueError, UnicodeError):
+                    logger.warning("agent-peers bridge returned invalid JSON")
+                    break
+                if not isinstance(result, dict):
+                    continue
+                if result.get("method") == "peer_message":
+                    try:
+                        self._messages.put_nowait(result.get("params", {}))
+                    except Full:
+                        logger.warning("agent-peers incoming queue is full; dropped peer message")
+                    continue
+                request_id = result.get("id")
+                if type(request_id) is not int:
+                    continue
+                with self._lock:
+                    pending = self._pending.get(request_id)
+                    if pending and pending[0] is process and not pending[1].done():
+                        error = result.get("error")
+                        if error:
+                            text = error.get("message", "bridge request failed") if isinstance(error, dict) else str(error)
+                            pending[1].set_exception(RuntimeError(text))
+                        else:
+                            pending[1].set_result(result.get("result"))
+        except (OSError, ValueError):
+            logger.warning("agent-peers bridge connection closed")
+        finally:
+            self._fail_pending(process, _EXITED)
+            # A broken stdout protocol must not leave an orphaned subprocess.
+            try:
+                if process.poll() is None:
+                    process.terminate()
+                process.wait(timeout=0.5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=0.5)
+            except OSError:
+                pass
+            process.stdout.close()
+
+    def _deliver(self):
+        while not self._stopped:
+            try:
+                message = self._messages.get(timeout=0.1)
+            except Empty:
+                continue
+            if self._stopped:
+                break
+            try:
+                self.receive(message)
+            except Exception:
+                # Never log peer bodies, which may contain task data.
+                logger.warning("agent-peers message could not be delivered", exc_info=False)
+
+    def close(self):
+        with self._lock:
+            self._stopped = True
+            process = self._process
+            reader = self._reader
+        self._fail_pending(None, "agent-peers plugin has been unloaded")
+        if process:
+            # Writers poll the stop flag every 100ms and release this lock.
+            if self._write_lock.acquire(timeout=0.5):
+                try:
+                    process.stdin.close()
+                finally:
+                    self._write_lock.release()
+            try:
+                process.wait(timeout=0.5)
+            except subprocess.TimeoutExpired:
+                process.terminate()
+                try:
+                    process.wait(timeout=0.5)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait(timeout=0.5)
+            except OSError:
+                pass
+        for worker in (reader, self._delivery):
+            if worker and worker is not threading.current_thread():
+                worker.join(timeout=0.5)
+        while True:
+            try:
+                self._messages.get_nowait()
+            except Empty:
+                break

package/bin/agent-peers.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { allPeers } from "../src/wire.mjs";
+import { formatSessionPeer } from "../src/discovery.mjs";
+import { VERSION } from "../src/version.mjs";
+
+const usage = `agent-peers ${VERSION} — local agent messaging
+
+Usage: agent-peers <command> [options]
+
+  list [--json]     Discover running Claude Code and Codex inboxes
+  doctor [--json]   Check local prerequisites without changing configuration
+  hermes-bridge    Start the plugin-managed JSON-lines subprocess
+  --version       Print the installed version
+  --help          Show this help
+
+Codex MCP server: codex-peer
+Documentation: https://github.com/ThomasMarcelis/agent-peers`;
+
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+  console.error(`agent-peers: ${error.message}`);
+  process.exit(1);
+});
+
+async function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+  if (!cmd || ["--help", "-h", "help"].includes(cmd)) {
+    if (args.length) throw new SyntaxError("unexpected arguments");
+    console.log(usage);
+    return;
+  }
+  if (["--version", "-v", "version"].includes(cmd) && !args.length) {
+    console.log(VERSION);
+    return;
+  }
+  if (!["list", "doctor", "hermes-bridge"].includes(cmd) || args.length > 1 ||
+      (args.length && (args[0] !== "--json" || cmd === "hermes-bridge"))) {
+    throw new SyntaxError("unknown command or option; run agent-peers --help");
+  }
+  if (cmd === "hermes-bridge") {
+    const { runHermesBridge } = await import("../src/hermes-bridge.mjs");
+    runHermesBridge();
+    return;
+  }
+  if (cmd === "doctor") {
+    const { diagnose } = await import("../src/diagnostics.mjs");
+    const result = diagnose();
+    if (args.includes("--json")) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`agent-peers ${VERSION}`);
+      for (const check of result.checks) console.log(`${check.status.toUpperCase()} ${check.name}: ${check.message}`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  const peers = allPeers();
+  if (args.includes("--json")) console.log(JSON.stringify({ peers }, null, 2));
+  else {
+    if (!peers.length) console.log("No agent sessions are running.");
+    for (const peer of peers) console.log(formatSessionPeer(peer));
+    if (peers.length) console.log("Codex native reachability depends on your session; call list_peers there for native targets.");
+  }
+}
+
+try { await main(); }
+catch (error) {
+  console.error(`agent-peers: ${error.message}`);
+  process.exitCode = error instanceof SyntaxError ? 2 : 1;
+}

package/docs/compatibility.md

@@ -0,0 +1,38 @@
+# Compatibility
+
+agent-peers 0.1.0 is an initial release. Its CLI and MCP tools are small, but the agent runtimes it connects expose version-sensitive interfaces. A newer agent release is not automatically compatible.
+
+## Runtime requirements
+
+| Component | Requirement |
+| --- | --- |
+| Node.js | 22 or later; CI covers 22, 24, and 26 |
+| Operating system | Linux and macOS; local Unix sockets are required |
+| Python (Hermes only) | 3.11–3.13, as supported by the tested Hermes host |
+| Claude Code | Cross-session inbox and `SendMessage` support |
+| Codex | Shared app-server daemon, thread identity in MCP call metadata, and live `turn/start` delivery |
+| Hermes | Native plugin loader plus `session_message_route`, `inject_session_message`, and route-retirement hook |
+
+Windows is not supported. WSL must run all participating agents inside the same Linux environment. CI on macOS verifies the transport and package; live agent interoperability was exercised on Linux.
+
+## Tested agent builds
+
+- Codex CLI **0.160.0**.
+- Claude Code **2.1.288**.
+- Hermes fork [ThomasMarcelis/hermes-agent](https://github.com/ThomasMarcelis/hermes-agent) at [`1afb5d16d2d25e1d8e13703c1ce946e3ca0adc0d`](https://github.com/ThomasMarcelis/hermes-agent/commit/1afb5d16d2d25e1d8e13703c1ce946e3ca0adc0d).
+
+The pinned Hermes host is reproducible in CI. It is a fork dependency, not a claim that any upstream version with the same version number includes these APIs.
+
+Upstream Hermes was inspected at [`5d3c05977bb3c8b7cfd6b3e39d96f6e35a9e0662`](https://github.com/NousResearch/hermes-agent/commit/5d3c05977bb3c8b7cfd6b3e39d96f6e35a9e0662). Its public `inject_message` API cannot atomically pin a late reply to the original conversation across reset and compression. Gateway and TUI injection queue busy-session input rather than steering it. The plugin therefore rejects sends on that host instead of weakening its routing contract.
+
+## What to expect
+
+A Codex inbox binds on the session's first `list_peers` or `send_peer` call. Threads hosted in embedded servers, including sessions started with `-c` or `--no-daemon`, are not reachable through the shared daemon. A subagent sends under its root's address; replies return to the root. Native targets only refer to agents in the caller's own tree.
+
+Claude's inbox protocol is undocumented. Inbound messages may be held for approval or rejected according to Claude settings. In particular, `bypassPermissions` does not imply accepting external messages. The package does not change that policy.
+
+Hermes support is experimental. Tests verify plugin loading, profile isolation, and busy/idle replies to the originating Discord thread on the pinned fork. CLI and Desktop/TUI reset/compression behavior is not covered by this release's compatibility guarantee: the current fork has a Desktop idle-dispatch/reset race that requires a separate host fix. No upstream submission or host upgrade is part of installing this package.
+
+Claude sessions may use different private socket directories on the same machine. Codex maintains a reply inbox in each verified directory; Hermes selects a private reply inbox in the destination's directory. Existing owned inboxes survive discovery changes, and a missing Codex inbox can be repaired on the next tool call without resetting the conversation.
+
+Run the opt-in live checks after upgrading an agent. See [contribution guidance](../CONTRIBUTING.md) and [release verification](release-verification.md).

package/docs/hermes.md

@@ -0,0 +1,55 @@
+# Hermes plugin (experimental)
+
+The repository is a native Hermes plugin and an npm package. Both use the same Node transport. Hermes starts its own bridge subprocess lazily; a separate standalone daemon is unnecessary.
+
+## Prerequisites
+
+Use the [verified Hermes fork](compatibility.md#tested-agent-builds), Python 3.11–3.13, and Node.js 22+. Stock Hermes currently lacks the exact-conversation route APIs. Discovery remains available there, but sending returns an unsupported-host error.
+
+## Install
+
+```sh
+hermes plugins install ThomasMarcelis/agent-peers --enable
+```
+
+For a reproducible release install, add `--ref` followed by the full 40-character commit from the [GitHub release](https://github.com/ThomasMarcelis/agent-peers/releases/tag/v0.1.0). Hermes does not accept tag names for this flag. Use `hermes --profile NAME plugins install ...` for a named profile. Current Hermes installers can offer to install the plugin's Node dependencies; accept that step. Older fork installers need a separate install in the plugin directory printed by Hermes:
+
+```sh
+npm --prefix /absolute/plugin/directory ci --omit=dev --ignore-scripts
+```
+
+Replace `/absolute/plugin/directory` with the actual installed directory. The plugin reports the exact recovery command if Node or dependencies are unavailable. There are no install-time scripts in agent-peers.
+
+Grant injection explicitly for each selected profile using Hermes configuration:
+
+```sh
+hermes config set plugins.entries.agent-peers.allow_gateway_injection true
+```
+
+This allows automatic peer messages to start or steer the original conversation. For messaging gateways, an agent response may be posted to its existing chat/thread. The plugin does not grant this permission itself. New hosts/conversations may be needed to load changed plugin tools; follow your host's normal restart workflow.
+
+If saved platform tool selections exclude new plugins, enable the `agent-peers` toolset for the intended platform using `hermes tools`. Preserve other platform selections.
+
+## Behavior
+
+`list_peers()` returns Claude Code and Codex inboxes without publishing Hermes. The first `send_peer(to, message)` creates a private inbox for that conversation. Peers reply to its received address through their normal messaging tools.
+
+- Every conversation and profile has an independent reply route.
+- Busy conversations receive input through the host's steering boundary; idle conversations start a turn.
+- Routes belong to the originating host conversation. Unload or host shutdown closes their inboxes; Hermes must send again to establish fresh return addresses.
+- Discord replies return to the original thread. Switching chats does not change the return destination.
+- There is no transcript scraping, history polling, offline mailbox, or automatic retry of an ambiguous send.
+
+Discord gateway routing is the verified surface. CLI and Desktop/TUI lifecycle behavior remains experimental on the current fork; see the [host limitation](compatibility.md#what-to-expect).
+
+## Configuration
+
+An optional `bridge_command` list under `plugins.entries.agent-peers.settings` overrides the executable and arguments. Use absolute paths. Normal installs resolve Node and the bridge within the installed plugin; no checkout path is required.
+
+The bridge inherits only environment needed for discovery and execution. Provider credentials are not passed to it. It reads Claude session registry metadata and agent-peers registry entries, communicates over local sockets, and keeps no transcript archive. Agent replies may themselves invoke the model providers configured in those agents.
+
+## Update and remove
+
+Use Hermes's native plugin manager to update or remove the plugin. For an explicitly pinned release, reinstall with the new release ref after reviewing its compatibility notes. The legacy Python installer is a compatibility helper; native installation is the supported path.
+
+The optional generic Hermes host extension is separate from this package. It adds conversation-route capabilities for any plugin; peer discovery and messaging remain entirely here.

package/docs/reference.md

@@ -0,0 +1,66 @@
+# Reference
+
+## CLI
+
+| Command | Output |
+| --- | --- |
+| `agent-peers list` | Sessions with exact Claude `SendMessage` and Codex `send_peer` targets |
+| `agent-peers list --json` | `{ "peers": [...] }`; no status text mixed into stdout |
+| `agent-peers doctor [--json]` | Runtime, dependency, and local path checks; does not modify configuration or send messages |
+| `agent-peers --version` | Package version |
+| `agent-peers --help` | Usage |
+| `codex-peer` | Codex MCP server over stdio |
+| `agent-peers hermes-bridge` | Plugin-managed JSON-lines subprocess |
+
+Exit codes: `0` success, `1` runtime/diagnostic failure, `2` invalid CLI usage. Missing agent state is a diagnostic warning because running only one integration is valid. A present socket does not prove compatibility or model readiness.
+
+## Tools
+
+`list_peers()` takes no arguments. Codex's structured result contains `peers`, each with its name, kind, working directory, available activity status, and native/bridge route. Native reachability is caller-relative: another root is bridge-only even on the same daemon. Discovery does not load historical Codex threads.
+
+`send_peer({to, message})` accepts an exact peer name, unambiguous abbreviated name, or a valid inbox address. Prefer returned exact targets. Empty messages, ambiguous targets, self-sends, and invalid addresses fail clearly. Hermes host handlers return JSON text as required by its dispatcher; Codex uses MCP text content and error results.
+
+A successful socket write confirms only inbox acceptance. Claude delivery receipts can report held/rejected input; not every recipient sends a receipt. No receipt is not proof of model consumption. Timed-out delivery is not automatically retried because it may already have arrived.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `CLAUDE_CONFIG_DIR` | Claude configuration directory used to locate session registry metadata |
+| `CODEX_HOME` | Codex home used to locate its shared daemon |
+| `AGENT_PEERS_HOME` | agent-peers registry directory |
+| `AGENT_PEERS_CODEX_APP_SERVER` | Explicit absolute path to an app-server Unix socket |
+| `AGENT_PEERS_LOG` | Optional absolute log file for `codex-peer` |
+
+Defaults use the current OS user's standard agent directories. Every override should be absolute. Package-owned socket and registry state must have private ownership/permissions. The transport is local and same-user; it is not a network service.
+
+## Hermes subprocess protocol
+
+Requests are newline-delimited JSON objects `{id, method, params}`. Responses are `{id, result}` or `{id, error}`. Methods:
+
+- `list_peers`: no parameters.
+- `send_peer`: `session`, `name` (a `hermes:` identity), `to`, `message`.
+- `close_session`: `session`.
+- `shutdown`: close owned state and exit.
+
+`peer_message` notifications identify the private session, message ID, sender, reply address, and body. Hermes creates no public registry entry. EOF and termination remove owned sockets. Standard output carries protocol data only; diagnostics go to standard error.
+
+Messages use Claude's `<cross-session-message>` envelope. Incoming agent input is reframed with sender identity, a reply address, and a reminder that it carries no user approval. Closing tags in message bodies are escaped. A frame is bounded to 1,000,000 bytes. Resource bounds, token buckets, and duplicate suppression limit accidental floods; see the source constants for precise limits.
+
+## Troubleshooting
+
+- **No Codex inbox:** call `list_peers` in that session; check that it uses the shared daemon.
+- **Wrong native target:** rediscover from the sending Codex session. A thread UUID alone does not establish native reachability.
+- **Held Claude delivery:** review its inbound-message policy; agent-peers does not bypass it.
+- **Hermes unsupported route:** use the documented host revision. Upstream `inject_message` is not an equivalent fallback.
+- **Missing plugin dependencies:** run the exact install command in the plugin error, then reload through the host's supported lifecycle.
+- **Permission failure:** inspect directory ownership and modes. Do not make the socket directory globally writable.
+- **Old reply address:** ask the peer to discover or send again after the original conversation closes; addresses are not durable mailboxes.
+
+## Updating active integrations
+
+Keep production launchers pointed at a tested installed snapshot, separate from development checkouts. Running Node processes cache their modules: changing a file does not update an existing sidecar.
+
+Use the agent host's supported MCP refresh with the new snapshot's launcher. Codex can preserve conversations and active work while replacing an MCP connection; an already captured tool step may still use the previous connection. A live legacy inbox owner blocks unsafe takeover. Verify the new registry owner, all inbox paths, and a real reply before considering an update complete.
+
+Missing Codex inboxes repair on the next tool call only while the sidecar still owns its registry token. An inbox owned by a replacement is never reclaimed. A Hermes bridge restart retires its private reply addresses, so the Hermes conversation must send again to establish a fresh return route.

package/docs/release-verification.md

@@ -0,0 +1,31 @@
+# Release verification
+
+Verified on 2026-10-03 for 0.1.0. Raw live transcripts are excluded from the repository and package.
+
+## Automated checks
+
+| Check | Result |
+| --- | --- |
+| JavaScript transport, MCP, discovery and CLI | 62 tests |
+| Portable Python plugin and subprocess | 25 tests |
+| Pinned Hermes loader and Discord routing | 5 tests |
+| Packed npm artifact | 29 files; installed CLI and MCP handshake passed |
+| Production dependency audit | 0 known vulnerabilities |
+
+Regressions cover concurrent socket directories, destination-specific reply addresses, legacy sidecar takeover, missing-inbox repair, and an injected replacement race between validation and socket publication. An independent Opus 5.5 review identified lifecycle issues addressed by these changes.
+
+All ten jobs in the [transport validation run](https://github.com/ThomasMarcelis/agent-peers/actions/runs/37149288716) passed: Linux/macOS on Node 22, 24 and 26, Python 3.11–3.13, and the pinned-Hermes integration. See [CI](https://github.com/ThomasMarcelis/agent-peers/actions/workflows/ci.yml) for the release commit. A credential-pattern scan of reachable Git history found no potential credentials.
+
+## Agent compatibility
+
+Live verification used Node 22.23.1, Codex CLI 0.160.0, and Claude Code 2.1.288 on Linux, with disposable sessions and isolated peer registries:
+
+- All 12 directed request/reply routes among two Claude and two Codex sessions passed.
+- All four sessions discovered their expected peers.
+- Native Codex subagent discovery and messaging passed.
+- All four Hermes bridge round trips passed: idle and busy Codex, and idle and busy Claude, with private-inbox lifecycle and discovery checks.
+- A shared design task negotiated ownership, completed independent drafts, and coordinated a changed requirement. No peer messages were sent during the independent phase; this is an observation, not a quota.
+
+Deterministic Discord tests exercise the real adapter path with fake model and network calls. They do not claim a production Discord API test. Host requirements and experimental Hermes surfaces are listed in [compatibility](compatibility.md).
+
+The generic Hermes host extension remains separate and unsubmitted. Its local preparation does not make stock upstream Hermes supported.

package/hermes-plugin/__init__.py

@@ -0,0 +1,15 @@
+"""Compatibility entrypoint for existing checkout symlinks; install the repo root."""
+
+import importlib.util
+from pathlib import Path
+import sys
+
+_package = Path(__file__).resolve().parent.parent / "agent_peers"
+_name = __name__ + "._implementation"
+_spec = importlib.util.spec_from_file_location(_name, _package / "__init__.py",
+                                             submodule_search_locations=[str(_package)])
+_module = importlib.util.module_from_spec(_spec)
+sys.modules[_name] = _module
+_spec.loader.exec_module(_module)
+BridgeClient, PeerTools, register = _module.BridgeClient, _module.PeerTools, _module.register
+__all__ = ["BridgeClient", "PeerTools", "register"]

package/hermes-plugin/plugin.yaml

@@ -0,0 +1,13 @@
+name: agent-peers
+version: "0.1.0"
+description: "Discover and message local Claude Code and Codex sessions from an unlisted Hermes inbox."
+manifest_version: 1
+provides_tools:
+  - list_peers
+  - send_peer
+provides_hooks:
+  - on_session_message_route_closed
+config_schema:
+  bridge_command:
+    type: list
+    description: "Executable and arguments for the agent-peers hermes-bridge subprocess."

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "agent-peers",
+  "version": "0.1.0",
+  "description": "Local peer messaging for Claude Code, Codex, and Hermes agents",
+  "license": "MIT",
+  "author": "Thomas Marcelis",
+  "homepage": "https://github.com/ThomasMarcelis/agent-peers#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThomasMarcelis/agent-peers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ThomasMarcelis/agent-peers/issues"
+  },
+  "keywords": [
+    "hermes",
+    "codex",
+    "claude-code",
+    "mcp",
+    "agents",
+    "ipc"
+  ],
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "agent_peers/",
+    "__init__.py",
+    "plugin.yaml",
+    "hermes-plugin/",
+    "scripts/install-hermes-plugin.py",
+    "docs/",
+    "CLAUDE-snippet.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "after-install.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "bin": {
+    "agent-peers": "bin/agent-peers.mjs",
+    "codex-peer": "src/codex-peer.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "test": "node --test test/discovery.mjs test/hermes-bridge.mjs test/wire.mjs test/app-server.mjs test/codex-peer.mjs test/cli.mjs",
+    "test:python": "python3 -m pytest -q",
+    "test:package": "node scripts/test-package.mjs",
+    "test:live": "node test/live-matrix.mjs",
+    "test:live:hermes": "node test/hermes-live.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1",
+    "ws": "^8",
+    "zod": "^4"
+  }
+}