@securecoms/agent-bridge 0.16.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,7 @@ 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/dist/bin.js

@@ -11125,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`;
@@ -11141,7 +11156,7 @@ 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
       };
@@ -11182,7 +11197,7 @@ 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
       };
@@ -11226,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 };
 }
 
@@ -11797,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);
   }

package/package.json

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