@securecoms/agent-bridge 0.15.0 → 0.17.0

package/README.md

@@ -305,6 +305,65 @@ Pick one receive mode — WebSocket, SSE, or long-poll — and stick with it. Th
 
 ---
 
+## Bring your own agent
+
+The daemon has no approved-framework list. It checks a bearer token and nothing else, so there is exactly one requirement:
+
+> **You must be able to add code to a process that stays running.**
+
+That is the whole test. If your agent is a program you control, it can hold a SecureComs channel in about fifty lines — see [`examples/ws-agent-client.mjs`](./examples/ws-agent-client.mjs) and [`ws-agent-client.py`](./examples/ws-agent-client.py), which are runnable as-is.
+
+To check your own connector against every rule in this section, run [`examples/byo-conformance.mjs`](./examples/byo-conformance.mjs) — a zero-dependency agent that follows the section literally and prints a pass/fail line per rule:
+
+```sh
+node examples/byo-conformance.mjs <your agent's identity_id>
+```
+
+**This fits.** Anything you build yourself, in any language: LangChain, LangGraph, CrewAI, AutoGen, Pydantic AI, the OpenAI or Anthropic agent SDKs, LlamaIndex — or a plain script calling an LLM API with no framework at all. You already own the process; you add a socket to it.
+
+**This does not fit.** Consumer chat products (claude.ai, ChatGPT, the Gemini app) have no extension point. Session-based coding CLIs have no always-on loop to attach to. A fully hosted agent you cannot run code beside cannot reach the daemon.
+
+**A platform you run but did not write** (Dify, Flowise, n8n, and the like) fits only if it lets you run persistent custom code. If it does, what you are writing is a plugin for that platform — the same job the bundled `openclaw` and `hermes` connectors do.
+
+Install with `--harness universal` to skip connector wiring and print the details your agent needs. (`--harness custom` is the old name for the same thing and still works.) Running `install` with no `--harness` at all does the same thing when neither OpenClaw nor Hermes is present.
+
+### Where your agent runs
+
+Same machine by default — the daemon binds `127.0.0.1`. Another machine works too, over TLS (see **Cross-host use** under Security). One caveat: a delivered attachment gives you a **local file path** on the daemon's machine, so an off-host agent can receive text, status, vault and A2A traffic but cannot read attachment bytes.
+
+### The five rules
+
+1. **Ack everything.** Delivery is at-least-once. Send `{type:"ack", message_id}` once you have durably handled a message, and dedup by `message_id`.
+2. **One consumer per daemon.** A second `/v1/ws` closes the first. Two clients will evict each other in a loop.
+3. **Answer the pings.** The daemon pings every 30s and reaps a socket that misses a pong. Standard WebSocket clients do this for you.
+4. **Read the token from its file, never from an environment value.** An env *value* is inherited by child processes and visible in `ps eww` and crash dumps. A path is not.
+5. **Check the identity gate before you attach.** Details below.
+
+### The identity gate
+
+Skip this and a single-agent host still works. The failure appears later, when a second agent is installed on the same machine, and it is silent.
+
+The daemon rewrites `~/.securecoms/connections/<identity_id>.json` on every start, giving you its current port and token-file path — so a moved port is picked up automatically. But if your connector reads the *wrong* agent's file, everything looks consistent: it authenticates successfully to that agent's daemon, drives that agent's identity, and evicts that agent's real connector.
+
+The bearer token does not catch this. It rejects a caller with *no* valid token; it does nothing against a caller holding a *valid but wrong* pair.
+
+So, before opening the WebSocket:
+
+1. Know which agent you are meant to serve — a fixed `identity_id`, from your own config. **Never** infer it by scanning the connections directory: on a multi-agent host a slow-starting daemon can leave exactly one file present at the moment you look, and you will bind to the wrong agent.
+2. Read that agent's connection file for `bridge_url` and `token_file`.
+3. `GET /healthz` (no token needed) and require **both**: the file's `identity_id` and your own fixed `identity_id` each equal `healthz.identity_id`.
+4. Any mismatch: do not open the socket. Back off with jitter and retry from step 2 — the port may have moved.
+
+On reconnect, re-read the connection file and the token, but **not** your identity. Re-deriving it on every reconnect lets a file appearing or disappearing silently re-bind a running connector to a different agent.
+
+The bundled `openclaw` and `hermes` connectors implement all of this; read either one as a worked example.
+
+### Separate compartments need separate OS uids
+
+The gate prevents honest mistakes. It is not a tenant boundary. The hop from daemon to agent carries plaintext, and the token and sealed store are readable by anyone sharing the uid — so any agent under the same uid can already drive another's daemon directly. **Agents in different orgs or enclaves that must not cross MUST run under different OS uids, or on different hosts.**
+
+---
+
 ## Run as a service
 
 For an autonomous agent running on a server, keep the daemon up with systemd so it restarts on failure and starts on boot. A sleeping or crashed daemon means its WebSocket/SSE connections drop and messages queue on the server until the daemon reconnects; they replay losslessly on wake. The daemon can't wake a sleeping machine.
@@ -358,7 +417,8 @@ pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
 - A **free port is auto-selected** from `7077-7276` (lowest free wins; sibling service definitions and live binds both count as taken). Pass `--port N` to override; the explicit port is honored as-is.
 - Install **verifies the daemon actually came up** and fails loudly with the log path if it didn't — no silent crash-loops.
 - Install echoes the credential's `device_id`, `issued_at`, and a redacted api-key fingerprint so you can confirm you installed the newest download. **Re-running install is the only way to update a live (e.g. rotated) credential** — replacing the downloaded file alone does nothing.
-- Optional `--harness openclaw|hermes|custom` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output).
+- Optional `--harness openclaw|hermes|universal` prints a paste-ready config snippet with the chosen port and the token-file path (the token itself never appears in output). (`--harness custom` is an accepted alias for `universal`.)
+- **One harness gateway serves one agent.** The connector registers a single platform and resolves a single bound identity for the life of the gateway process, so a connector directory (`~/.hermes/plugins/securecoms`, `~/.openclaw/local-plugins/securecoms`) holds exactly one agent. Install and `wire` therefore **refuse** to overwrite a binding that names a different agent — doing so would take the harness away from that agent, not add one alongside it. To run two agents on one host, give each its own harness profile with its own connector directory and binding. To deliberately move a harness to a different agent, pass `--rebind`.
 
 ---
 

package/connectors/hermes/adapter.py

@@ -132,7 +132,17 @@ class SecureComsAdapter(BasePlatformAdapter):
 
     # ── Connection lifecycle ──────────────────────────────────────────────
 
-    async def connect(self) -> bool:
+    async def connect(self, *, is_reconnect: bool = False) -> bool:
+        """Connect to the local daemon.
+
+        ``is_reconnect`` mirrors BasePlatformAdapter.connect's signature —
+        gateway/run.py passes it as a keyword on EVERY call, cold boot
+        included, so an adapter that omits it raises TypeError and the
+        platform never attaches. SecureComs holds no server-side update
+        queue to preserve across an outage (the daemon is a local WS the
+        supervisor re-opens), so the flag carries no behaviour here.
+        """
+        del is_reconnect  # accepted for contract parity; nothing to preserve
         self._stopped = False
 
         # BINDING-STABILITY fold: resolve bound_identity here, ONCE, for the

package/connectors/hermes/tests/test_adapter_wiring.py

@@ -539,3 +539,36 @@ class TestCheckRequirementsWiring:
         monkeypatch.setenv("SECURECOMS_CONNECTION_FILE", str(tmp_path / "does-not-exist.json"))
 
         assert adapter.check_requirements() is False
+
+
+# ---------------------------------------------------------------------------
+# (6) connect() signature contract with BasePlatformAdapter
+# ---------------------------------------------------------------------------
+
+
+class TestConnectSignatureContract:
+    """gateway/run.py ALWAYS calls `adapter.connect(is_reconnect=...)` — on the
+    cold first boot as well as on every reconnect. An adapter whose connect()
+    does not accept that keyword raises TypeError inside the gateway's
+    connect helper, which the reconnect watcher reports as a platform error
+    and retries forever: the daemon looks connected to the SecureComs server
+    while the harness side never attaches and the agent never answers.
+    """
+
+    def test_connect_accepts_is_reconnect_keyword(self):
+        import inspect
+
+        sig = inspect.signature(adapter.SecureComsAdapter.connect)
+        param = sig.parameters.get("is_reconnect")
+        assert param is not None, "connect() must accept the is_reconnect keyword"
+        assert param.kind is inspect.Parameter.KEYWORD_ONLY
+        assert param.default is False
+
+    @pytest.mark.asyncio
+    async def test_connect_is_reconnect_true_reaches_the_unwired_path(self, monkeypatch):
+        a, _ = make_adapter(monkeypatch, files={})  # no binding file -> unwired
+        ok = await a.connect(is_reconnect=True)
+        assert ok is False
+        code, _message, retryable = a.fatal_errors[-1]
+        assert code == "unwired"
+        assert retryable is False

package/dist/bin.js

@@ -1409,9 +1409,7 @@ var SUITE2 = "xchacha20poly1305";
 var AAD = new TextEncoder().encode("kekset");
 var enc = new TextEncoder();
 var dec = new TextDecoder();
-function unb64(s) {
-  return new Uint8Array(Buffer.from(s, "base64"));
-}
+var unb64 = base64ToBytes;
 function headerObject(h) {
   return {
     enclaveId: h.enclaveId,
@@ -11000,6 +10998,16 @@ function connectorTargetDir(home, harness) {
   if (harness === "openclaw") return `${home}/.openclaw/local-plugins/securecoms`;
   return `${home}/.hermes/plugins/securecoms`;
 }
+function checkBindingConflict(prev, next, allowRebind) {
+  if (!prev || prev === next) return { ok: true, rebindFrom: null };
+  if (allowRebind) return { ok: true, rebindFrom: prev };
+  return {
+    ok: false,
+    message: `refusing to rebind: this harness connector is already bound to ${prev}, not ${next}. A harness gateway serves ONE agent, so this would take the harness away from ${prev} rather than add ${next} alongside it.
+  To run both agents, give each one its own harness profile (its own connector dir + binding).
+  To deliberately move THIS harness to ${next}, re-run with --rebind.`
+  };
+}
 function connectorsSrcDir(importMetaUrl, harness) {
   const pkgRoot = dirname5(dirname5(fileURLToPath(importMetaUrl)));
   return join9(pkgRoot, "connectors", harness);
@@ -11061,8 +11069,18 @@ function runWire(deps) {
   if (!resolved) return 1;
   const { entry, harness } = resolved;
   const targetDir = connectorTargetDir(deps.home, harness);
+  const guard = checkBindingConflict(
+    deps.readBinding(targetDir),
+    entry.identityId,
+    deps.argv.includes("--rebind")
+  );
+  if (!guard.ok) {
+    deps.log(`wire: ${guard.message}`);
+    return 1;
+  }
   deps.copyConnector(deps.connectorsSrcDir(harness), targetDir, harness);
   deps.writeBinding(targetDir, entry.identityId);
+  if (guard.rebindFrom) deps.log(`wire: rebind: ${guard.rebindFrom} -> ${entry.identityId}`);
   if (harness === "hermes") {
     const enabled = enableHermesConfig(deps.home, deps);
     deps.log(`[securecoms] ${enabled.message}`);
@@ -11107,15 +11125,30 @@ function runUnwire(deps) {
 function customFacts(input) {
   const ws = `ws://127.0.0.1:${input.port ?? "<PORT>"}/v1/ws`;
   return [
-    `  bridge WS:   ${ws}`,
-    `  token file:  ${input.tokenFilePath}`,
+    `  bridge WS:     ${ws}`,
+    `  token file:    ${input.tokenFilePath}`,
+    `  agent id:      ${input.identityId}`,
+    `  discovery:     ~/.securecoms/connections/${input.identityId}.json (rewritten on every daemon start)`,
     `  Bring your own connector: open the WS with the bearer token read from that file.`,
+    `  Ack every message you receive; delivery is at-least-once, so dedup by message_id.`,
+    `  Before you attach, check the identity gate: the daemon's /healthz identity_id MUST equal`,
+    `    the agent id above. Skipping it means a second agent on this host can silently`,
+    `    drive the wrong daemon. See "Bring your own agent" in the agent-bridge README.`,
     `  Protocol reference: the "WebSocket" section of the agent-bridge README.`
   ].join("\n");
 }
 function autoWireHarness(input, deps) {
   const h = input.harness;
-  if (!h || h === "none") return { echo: "", wired: false, error: false };
+  if (h === "none") return { echo: "", wired: false, error: false };
+  if (!h) {
+    return {
+      echo: `[securecoms] No agent harness detected (no ~/.openclaw, no ~/.hermes) \u2014 the bridge service is installed and running, but nothing is attached to it yet.
+  Bring your own agent:
+${customFacts(input)}`,
+      wired: false,
+      error: false
+    };
+  }
   if (h === "openclaw") {
     const retry = `agent-bridge wire --harness openclaw --identity ${input.slug}`;
     const parent2 = `${input.home}/.openclaw`;
@@ -11123,18 +11156,25 @@ function autoWireHarness(input, deps) {
       return {
         echo: `[securecoms] OpenClaw not found at ~/.openclaw \u2014 the bridge service is installed, but the harness was NOT wired.
   Install OpenClaw, then re-run install, or run: ${retry}
-  (or re-run install with --harness custom).`,
+  (or re-run install with --harness universal).`,
         wired: false,
         error: true
       };
     }
     const targetDir = connectorTargetDir(input.home, "openclaw");
+    const guard = checkBindingConflict(deps.readBinding(targetDir), input.identityId, input.allowRebind ?? false);
+    if (!guard.ok) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but the OpenClaw connector was NOT wired: ${guard.message}`,
+        wired: false,
+        error: true
+      };
+    }
     try {
-      const prev = deps.readBinding(targetDir);
       deps.copyConnector(input.connectorsSrcDir, targetDir, "openclaw");
       deps.writeBinding(targetDir, input.identityId);
-      const rebind = prev && prev !== input.identityId ? `
-  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      const rebind = guard.rebindFrom ? `
+  rebind: ${guard.rebindFrom} \u2192 ${input.identityId}` : "";
       return {
         echo: `[securecoms] OpenClaw connector installed and bound to identity ${input.identityId}.${rebind}
   Now restart OpenClaw to pick up the connector.`,
@@ -11157,14 +11197,21 @@ function autoWireHarness(input, deps) {
       return {
         echo: `[securecoms] Hermes not found at ~/.hermes \u2014 the bridge service is installed, but the harness was NOT wired.
   Install Hermes, then re-run install, or run: ${retry}
-  (or re-run install with --harness custom).`,
+  (or re-run install with --harness universal).`,
         wired: false,
         error: true
       };
     }
     const targetDir = connectorTargetDir(input.home, "hermes");
+    const guard = checkBindingConflict(deps.readBinding(targetDir), input.identityId, input.allowRebind ?? false);
+    if (!guard.ok) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but the Hermes connector was NOT wired: ${guard.message}`,
+        wired: false,
+        error: true
+      };
+    }
     try {
-      const prev = deps.readBinding(targetDir);
       deps.copyConnector(input.connectorsSrcDir, targetDir, "hermes");
       deps.writeBinding(targetDir, input.identityId);
       const enabled = enableHermesConfig(input.home, deps);
@@ -11176,8 +11223,8 @@ function autoWireHarness(input, deps) {
           error: true
         };
       }
-      const rebind = prev && prev !== input.identityId ? `
-  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      const rebind = guard.rebindFrom ? `
+  rebind: ${guard.rebindFrom} \u2192 ${input.identityId}` : "";
       return {
         echo: `[securecoms] Hermes connector installed and bound to identity ${input.identityId}.${rebind}
   ${enabled.message}
@@ -11194,7 +11241,7 @@ function autoWireHarness(input, deps) {
       };
     }
   }
-  return { echo: `[securecoms] Custom harness \u2014 bring your own connector:
+  return { echo: `[securecoms] Universal \u2014 bring your own agent:
 ${customFacts(input)}`, wired: false, error: false };
 }
 
@@ -11342,6 +11389,7 @@ async function orchestrateInstall(ctx) {
       identityId: parsed.identityId,
       slug,
       port,
+      allowRebind: ctx.allowRebind,
       home: ctx.home,
       tokenFilePath: result.tokenHint,
       connectorsSrcDir: ctx.connectorsSrcDir
@@ -11741,6 +11789,8 @@ function realWireDeps() {
     argv: realWireArgv(),
     readFleet: realReadFleet,
     copyConnector: realCopyConnector,
+    readBinding: realReadBinding,
+    // bin.ts:252 — feeds checkBindingConflict
     writeBinding: realWriteBinding,
     removeBinding: realRemoveBinding,
     getHealth: realGetHealth,
@@ -11762,7 +11812,7 @@ async function runServiceVerb(verb) {
   const label = argOrEnv("--label", "SECURECOMS_LABEL");
   if (verb === "install" ? !credentialPath : !credentialPath && !label) {
     const execPathUsage = verb === "install" ? " [--exec-path <path>]" : "";
-    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|custom]${execPathUsage}
+    process.stderr.write(`usage: agent-bridge ${verb} --credential <path> [--label <name>] [--store <path>] [--port N] [--harness openclaw|hermes|universal]${execPathUsage}
 `);
     process.exit(2);
   }
@@ -11786,6 +11836,7 @@ async function runServiceVerb(verb) {
         label,
         explicitPort: portStr ? Number(portStr) : void 0,
         harness: installHarness,
+        allowRebind: process.argv.includes("--rebind"),
         home: homedir2(),
         connectorsSrcDir: connectorsSrcDir(import.meta.url, installHarness === "hermes" ? "hermes" : "openclaw"),
         autoWireDeps: {

package/dist/index.js

@@ -1121,9 +1121,7 @@ var SUITE2 = "xchacha20poly1305";
 var AAD = new TextEncoder().encode("kekset");
 var enc = new TextEncoder();
 var dec = new TextDecoder();
-function unb64(s) {
-  return new Uint8Array(Buffer.from(s, "base64"));
-}
+var unb64 = base64ToBytes;
 function headerObject(h) {
   return {
     enclaveId: h.enclaveId,

package/dist/service/harness-wire.d.ts

@@ -7,6 +7,10 @@ export interface AutoWireInput {
     home: string;
     tokenFilePath: string;
     connectorsSrcDir: string;
+    /** Deliberate consent to move an already-bound harness to this identity
+     *  (`install --rebind`). Absent/false, a conflicting binding REFUSES —
+     *  see checkBindingConflict in wire.ts for why. */
+    allowRebind?: boolean;
 }
 export interface AutoWireDeps extends HermesConfigIoDeps {
     statDir: (p: string) => boolean;

package/dist/service/install-prep.d.ts

@@ -43,6 +43,7 @@ export interface OrchestrateInstallCtx {
     label?: string;
     explicitPort?: number;
     harness?: string;
+    allowRebind?: boolean;
     home: string;
     launchAgentsDir?: string;
     systemdDir?: string;

package/dist/service/wire.d.ts

@@ -38,6 +38,10 @@ export interface WireDeps extends HermesConfigIoDeps {
     argv: string[];
     readFleet: () => AgentFleetEntry[];
     copyConnector: (srcDir: string, dstDir: string, harness: Harness) => void;
+    /** The identity the target dir is ALREADY bound to, or null when nothing
+     *  is bound / the file is missing or malformed. Read BEFORE any write so
+     *  `checkBindingConflict` can refuse without having touched disk. */
+    readBinding: (dstDir: string) => string | null;
     writeBinding: (dstDir: string, identityId: string) => void;
     removeBinding: (dstDir: string) => void;
     getHealth: (port: number) => {
@@ -72,6 +76,32 @@ export declare function detectHarness(home: string, statDir: (p: string) => bool
  * placeholder value, never the real one).
  */
 export declare function connectorTargetDir(home: string, harness: Harness): string;
+/**
+ * The binding guard, shared by `wire` and by `install`'s auto-wire.
+ *
+ * A harness connector registers ONE platform and resolves ONE bound identity
+ * for the life of the gateway process (connectors/hermes/adapter.py's
+ * `register` + `_bound_identity`), so a connector directory holds exactly one
+ * agent. Writing a different identity over an existing binding therefore does
+ * not ADD an agent — it silently takes the harness away from whichever agent
+ * was already using it, leaving that agent dark while two gateways race for
+ * one daemon socket. Observed in the field 2026-09-08: installing a second
+ * Hermes agent rebound `~/.hermes/plugins/securecoms` away from the agent the
+ * default-profile gateway was serving.
+ *
+ * So an overwrite must be a deliberate act (`--rebind`), exactly like the
+ * binding itself is a deliberate act (audit C1). A first wire and an
+ * idempotent same-identity re-wire are always allowed.
+ *
+ * Pure: callers do the reading and the refusing.
+ */
+export declare function checkBindingConflict(prev: string | null, next: string, allowRebind: boolean): {
+    ok: true;
+    rebindFrom: string | null;
+} | {
+    ok: false;
+    message: string;
+};
 /**
  * Resolves a connector's SOURCE dir at runtime, keyed by harness (`connectors/
  * <harness>`) — `connectors/` is shipped SOURCE (not compiled — H2), so this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",