@creatornader/agent-bridge 0.7.2 → 0.7.4

package/docs/troubleshooting.md

@@ -48,6 +48,24 @@ another client's identity or backend file into the entry.
 
 ## Move a managed client to a local MCP HTTP host
 
+The public package owns the long-lived host. Do not depend on a wrapper from another
+repository for normal MCP availability. On macOS, install the host for one exact client
+identity and prove the listening socket before changing that client's registration:
+
+```bash
+agent-bridge-loopback-host --install-launchd \
+  --service-name codex \
+  --config ~/.agent-bridge/clients/<codex-backend>.config \
+  --agent codex --instance <stable-key> --port 8794
+curl --fail http://127.0.0.1:8794/mcp/health
+```
+
+The install returns success only after it receives a healthy HTTP response from the
+new listener. Each host receives one private backend file, identity, and stable
+instance. Do not point several identities at one host process.
+The generated plist omits `ProcessType` and `LowPriorityIO`; these macOS hints have
+previously left a Node process running without a bound socket.
+
 Preview the update first. Add `--apply` only after the plan names the expected
 registration and metadata steps:
 
@@ -64,8 +82,8 @@ Claude Desktop needs a stdio proxy because its managed entry remains a process l
 agent-bridge clients update claude-desktop \
   --identity claude-desktop --instance <stable-key> \
   --mcp-url http://127.0.0.1:8791/mcp \
-  --proxy-command /absolute/path/to/node \
-  --proxy-args-json '["/absolute/path/to/stdio-http-proxy.js","--transport","stdio-http-proxy","--endpoint","http://127.0.0.1:8791/mcp"]'
+  --proxy-command "$(command -v agent-bridge-stdio-http-proxy)" \
+  --proxy-args-json '["--endpoint","http://127.0.0.1:8791/mcp"]'
 ```
 
 The endpoint must use plain HTTP on `127.0.0.1`, `localhost`, or `::1`, include an
@@ -74,6 +92,10 @@ rejected. The update does not delete or rewrite the private backend file. A fail
 update can resume from its operation UUID, and a committed update can be reversed with
 `clients rollback`.
 
+An optional observer installed outside Agent Bridge must not be the only route to a
+public host. If it becomes unhealthy, keep clients on the public host and inspect the
+observer separately.
+
 ## The executable is missing
 
 Install the published package globally, then repeat the normal client installation:

package/llms.txt

@@ -49,6 +49,9 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 - agent-bridge clients adopt <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path> [--apply]
 - agent-bridge clients repair <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
 - agent-bridge clients update <runtime> --identity <principal> --instance <stable-key> [--command <command> | --mcp-url <loopback-url>] [--proxy-command <command> --proxy-args-json <json-array>] [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge-loopback-host [--host 127.0.0.1] [--port <port>] [--path /mcp]: public long-lived MCP host for one client identity.
+- agent-bridge-loopback-host --install-launchd --service-name <name> --config <private-backend> --agent <identity> --instance <stable-key> --port <port>: macOS lifecycle install. Prove /mcp/health before routing a client to it.
+- agent-bridge-stdio-http-proxy --endpoint http://127.0.0.1:<port>/mcp: public stdio bridge for a Claude Desktop loopback target.
 - agent-bridge clients uninstall <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
 - agent-bridge clients rollback <update-operation-id> --identity <principal> [--apply] [--recover-lock]
 - agent-bridge clients migrate stage <runtime> --identity <principal> --instance <stable-key> --enrollment-file <private-path> [--apply] [--recover-lock]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creatornader/agent-bridge",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Let AI agents message each other and hand off work across tools, sessions, and machines.",
   "type": "module",
   "license": "Apache-2.0",
@@ -20,6 +20,8 @@
   "bin": {
     "agent-bridge": "bin/agent-bridge",
     "agent-bridge-mcp": "dist/index.js",
+    "agent-bridge-loopback-host": "dist/loopback-host.js",
+    "agent-bridge-stdio-http-proxy": "dist/stdio-http-proxy.js",
     "agent-bridge-gateway": "dist/gateway-main.js"
   },
   "files": [