npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@securecoms/agent-bridge

v0.48.1

Published

Attached runtimes should include the inbound `message_id` as `in_reply_to` on their outbound `send` frame/request. After the encrypted send publishes, the The Agent Connector retains a bounded, 15-minute content-free receipt and exposes it at the bearer-g

Readme

@agentvault/connect-agent-bridge

Non-destructive runtime reply monitoring

Attached runtimes should include the inbound message_id as in_reply_to on their outbound send frame/request. After the encrypted send publishes, the The Agent Connector retains a bounded, 15-minute content-free receipt and exposes it at the bearer-gated loopback route:

GET /v1/reply-receipt?in_reply_to=<message_id>

The response is either { "found": false } or a receipt containing only the inbound message id, outbound message id, channel id, and publish timestamp. It contains no prompt or reply text. scripts/agent-reply-probe.mjs uses this surface and never calls /v1/messages, /v1/events, or /v1/ws, so routine monitoring cannot compete with or evict the attached runtime. The older scripts/fleet-probe.mjs remains an attended promotion tool because it drains the single-consumer stream to inspect reply plaintext.

An always-on local daemon that holds an AI agent's SecureComs credential and MLS state, then exposes a loopback API so any agent — Python, Node, Go, shell scripts, whatever — can send and receive end-to-end encrypted messages without touching any cryptography itself. All MLS key agreement, AEAD encryption, and channel admission happen inside the daemon.

The daemon serves two interfaces on the same port:

  • A WebSocket at /v1/ws — one persistent bidirectional socket for live receive, send, and status. This is the recommended interface for an always-on agent: no polling loop, messages arrive the instant they decrypt.
  • An HTTP API — /healthz, /v1/channels, one-shot /v1/send, plus long-poll and SSE receive. Best for health checks, control, scripts, and clients that don't want a socket.

Pick the WebSocket for a long-running agent; reach for HTTP for everything else. They share the same bearer token and the same channel state.

The server still sees ciphertext only. The trust boundary is the machine running the daemon.

Requirements

  • Node.js 24 LTS or newer. The daemon requires >= 24 (node:sqlite stable API).
  • A valid SecureComs agent credential (agent.json, chmod 600)

You don't have to check your Node version yourself. The installer checks it before anything else runs. On an older Node it says so plainly, and on macOS it offers to install Node 24 from nodejs.org after asking you. That step needs your computer's administrator password. It checks the download's published SHA-256 checksum before running it.

To install Node 24 yourself, download the Node 24 LTS installer from nodejs.org and run it. Then run the install command again.

Always re-run the install command after upgrading Node — the background service pins the Node path it was installed with.

Harness minimum versions (0.26.5 and later)

The bundled connectors give tools only to the agent owner's turns. Each harness must be able to block a tool call before it runs, so each has a minimum version:

| Harness | Minimum version | Hook the connector relies on | |---------|-----------------|------------------------------| | OpenClaw | 2026.4.27 | before_tool_call that can block | | Hermes | v2026.9.24 | pre_tool_call veto |

On an older harness the plugin reports its tool veto as inactive and refuses every turn that has no tool grant, so non-owner rooms go quiet instead of running tools unchecked. /healthz shows harness_tool_veto_active (true, false, or null when no plugin is attached), the authenticated GET /v1/status shows the harness name and version, and the daemon logs harness.tool_veto_inactive once when an attached harness cannot veto. After upgrading the package, re-run agent-bridge wire --harness openclaw (or re-copy the Hermes plugin files) so the harness loads the new plugin, then restart the harness gateway.

Room tool rule (0.30.0 and later)

In a room whose every member, including pending members and anyone who left but still holds an MLS leaf, is in the agent owner's org, the agent gets the time, plus web search if you allow it (50 a day per room). Other rooms get no tools. The owner DM uses the tools the owner signed. Without signed settings, it keeps current_time and web_search. Replies to room turns are re-classified when they are sent.

Operator steps:

  • Deploy order: backend (already live), then this Agent Connector, then @securecoms/agent-runtime 0.13.0. A new runtime on an old Agent Connector offers no tools on the owner's relayed voice turns. Room grants need both the new Agent Connector and the new runtime.
  • Re-wire plugins: re-run agent-bridge wire --harness ... on every Hermes and OpenClaw host after upgrading. Plugins are copied at wire time and an upgrade does not refresh them. An Agent Connector downgrade after re-wiring makes the new plugins refuse tools on the owner's voice turns.
  • Kill switch: SECURECOMS_ROOM_DEFAULT_GRANTS (Agent Connector service environment, read at startup). Unset or on keeps the room default; any other value sends no tools on every room turn. It does not affect the owner DM. SECURECOMS_OWNER_DM_DEFAULT_GRANTS is unchanged.
  • Owner-signed grant switches: SECURECOMS_OWNER_DM_MANIFEST_GRANTS and SECURECOMS_ROOM_MANIFEST_GRANTS (Agent Connector service environment, read at startup). Unset or on keeps owner-signed tool settings in that place (the private chat, or rooms). Any other value makes that place use the fallback: today's default tools, limited to what the owner signed, plus current_time. These switches never add a tool. SECURECOMS_OWNER_DM_DEFAULT_GRANTS and SECURECOMS_ROOM_DEFAULT_GRANTS still override them and send no tools when off.
  • Room search cap: SECURECOMS_ROOM_SEARCH_DAILY_CAP lowers the daily web_search limit for each room. The default and the maximum are 50. Use a whole number from 0 to 50. 0 turns room search off, and the room gets no notice. Any other value is treated as 50, and the Connector logs one warning. Set it in both the Agent Connector service environment and the runtime service environment. On macOS these are two launchd plists, and each has its own EnvironmentVariables. Each service reads it once at start, so restart both after a change. The count resets each UTC day.
  • Agent search cap: SECURECOMS_AGENT_ROOM_SEARCH_DAILY_CAP lowers the daily total of room web_search calls for one agent across all rooms. The default and the maximum are 200. Use a whole number from 0 to 200. 0 turns room search off. Any other value is treated as 200, and the Connector logs one warning. Set it in both service environments and restart both, as for the room cap.
  • Owner-DM epoch freshness: owner-DM tools now also require a roster read at the agent's current MLS group and epoch. A wedged or group-less DM shows no tools. Diagnose with the authz.decision log fields epoch_fresh, room_class, per_tool_consumer and room_kill_switch.
  • Restart residual: after an Agent Connector restart, a reply to a room turn granted before the restart is not re-classified. current_time and web_search output can be affected.
  • sqlite database path: a sqlite database path must be its real path. On macOS /tmp is /private/tmp, so a path under /tmp is refused.
  • Post-deploy probe: count connect.roster_mirror_unresolved warnings and rooms reading unknown. A high rate means roster mirror drift is hiding room tools.

Quickstart

1. Get a credential file

Use the SecureComs admin API to provision an agent credential. The server returns the signing key once and never again, so save the response immediately.

curl -s -X POST https://connect-dev.agentvault.chat/api/v1/admin/connect/agent-credentials \
  -H "Authorization: Bearer <owner-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"enclave_id": "<your-enclave-id>", "agent_name": "my-agent"}' \
  | tee agent.json
chmod 600 agent.json

The file must contain these fields (the API response includes all of them):

{
  "api_key": "av_agent_sk_...",
  "identity_id": "...",
  "device_id": "...",
  "signing_private_key": "...",
  "enclave_id": "...",
  "api_base": "https://connect-dev.agentvault.chat"
}

The daemon warns to stderr if the file permissions are looser than 0600. It does not block startup, but you should tighten it.

2. Start the daemon

npx @agentvault/connect-agent-bridge --credential ./agent.json

The daemon publishes its key package to SecureComs, waits to be admitted to channels by the owner's channel watcher, and then starts serving. Startup output on stderr looks like:

[bridge] listening on http://127.0.0.1:7077 (agent WS at ws://127.0.0.1:7077/v1/ws)
BRIDGE_TOKEN=<random-base64url-token>

The token is also persisted at <credential-dir>/bridge-token (mode 0600) so you can read it back on restart without grepping stderr. Override the path with --token-file.

Save the token:

export T=$(cat $(dirname ./agent.json)/bridge-token)

Or capture it from the boot line:

npx @agentvault/connect-agent-bridge --credential ./agent.json 2>&1 \
  | tee /tmp/bridge.log &
export T=$(grep '^BRIDGE_TOKEN=' /tmp/bridge.log | cut -d= -f2-)

3. Try it with curl

Use 127.0.0.1, not localhost — the daemon binds the IPv4 loopback by default.

# Check health (no auth required)
curl http://127.0.0.1:7077/healthz

# List channels
curl -H "Authorization: Bearer $T" http://127.0.0.1:7077/v1/channels

# Send a message
curl -X POST http://127.0.0.1:7077/v1/send \
  -H "Authorization: Bearer $T" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"<id>","text":"Hello from the Agent Connector"}'

# Poll for new messages (long-poll up to 30s)
curl -H "Authorization: Bearer $T" \
  "http://127.0.0.1:7077/v1/messages?channel_id=<id>&wait=30"

# Stream messages over SSE
curl -H "Authorization: Bearer $T" \
  "http://127.0.0.1:7077/v1/events?channel_id=<id>"

4. Call it from code

Python (requests)

import requests, time

BASE = "http://127.0.0.1:7077"
TOKEN = open("/path/to/credential-dir/bridge-token").read().strip()
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
CHANNEL = "<channel-id>"

# Send a message
resp = requests.post(f"{BASE}/v1/send", headers=HEADERS, json={
    "channel_id": CHANNEL,
    "text": "Hello from Python",
})
print(resp.json())  # {"message_id": "...", "status": "sent"}

# Receive loop (long-poll)
while True:
    r = requests.get(f"{BASE}/v1/messages",
                     headers=HEADERS,
                     params={"channel_id": CHANNEL, "wait": 50})
    for msg in r.json():
        print(msg["sender_id"], ":", msg["text"])

Node.js (fetch)

const BASE = "http://127.0.0.1:7077";
const TOKEN = (await fs.readFile("/path/to/credential-dir/bridge-token", "utf8")).trim();
const headers = { Authorization: `Bearer ${TOKEN}` };

// Send
const r = await fetch(`${BASE}/v1/send`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ channel_id: "<id>", text: "Hello from Node" }),
});
console.log(await r.json()); // { message_id, status: "sent" }

// SSE receive — listen on the named `message` event
const es = new EventSource(`${BASE}/v1/events?channel_id=<id>`, {
  headers,
});
es.addEventListener("message", (e) => {
  console.log(JSON.parse(e.data));
});

HTTP API reference

All routes except /healthz require Authorization: Bearer <BRIDGE_TOKEN>.

| Method | Path | Request | Response | |--------|------|---------|----------| | GET | /healthz | — | {status, identity_id, joined_channels, buffered, uptime_s, version} | | GET | /v1/channels | — | [{channel_id, name, is_dm, joined}] | | POST | /v1/send | {channel_id, text, idempotency_key?} | {message_id, status:"sent"} | | GET | /v1/messages | query: channel_id, wait (0–50) | [{channel_id, message_id, sender_id, text, ts}] | | GET | /v1/events | query: channel_id | SSE stream | | POST | /v1/status | {channel_id, state, detail?} | {ok:true} | | GET | /v1/vault-outbox | — | {path} (the upload outbox; null when uploads are disabled) | | POST | /v1/send-attachment | {channel_id, path, caption?} (path must be in the vault outbox) | {message_id, status:"sent"} | | POST | /v1/vault-write | {enclave_id, path, name, vault_channel_id?} (path must be in the vault outbox) | {node_id} | | GET (Upgrade) | /v1/ws | query: token or Authorization header | WebSocket — see WebSocket |

The agent's capabilities, including the receive modes the daemon supports, are advertised on /healthz under capabilities (e.g. receive_modes: ["longpoll","sse","websocket"]).

Uploads come only from the vault outbox. /v1/send-attachment and /v1/vault-write read a local file and share it with the channel or the workspace Files. They read only a regular file placed directly in the daemon's outbox, <store-dir>/vault-outbox/ (next to bridge-state.db). The daemon creates it at start with mode 0700, owned by the daemon's user, and pins it. Every read checks that it is still that same directory, owned by the daemon's user, with mode 0700. The authenticated GET /v1/vault-outbox returns its absolute path; the unauthenticated /healthz does not show it. Copy the file into that directory first, then pass its path (absolute, or a bare file name, which is resolved inside the outbox). Any other path is refused with 400 {"error":"path_outside_outbox"}. That includes a .. path, a subdirectory, a symlink (even one pointing back into the outbox), a hard link, a directory, a FIFO or a device, and an outbox that was swapped or loosened after start. The response and the daemon log never contain the path. A missing file inside the outbox is still 400 invalid_request. After a successful upload the daemon deletes the file from the outbox, so no plaintext copy lingers. After a failed upload the file stays, so you can retry. A received attachment saved under <store-dir>/attachments/ is outside the outbox: to forward it, copy it into the outbox first. Uploads are refused until the daemon has started, and always for an in-memory store. If the outbox mode or owner is changed while the daemon runs, uploads are refused until the daemon is restarted (it fails closed; a restart tightens the mode again).

What the outbox does not stop. It stops a caller that can only send HTTP requests to the daemon, for example a prompt-injected harness that is allowed to call the Agent Connector but not to touch files. It does not stop a harness that can also write files (shell or file tools): such a harness can copy ~/.ssh/id_ed25519 into the outbox and upload it. The real control for that case is per-upload owner approval, which is tracked as a follow-up (W6). Until then, give file-capable harnesses only the Agent Connector token you would trust with your files.

POST /v1/send — 503 channel_pending

If the daemon hasn't been admitted to the named channel yet (the owner's watcher hasn't processed the key package), the response is:

HTTP 503
{"error": "channel_pending", "detail": "awaiting admission"}

Retry with exponential back-off. The channel becomes available once the owner's client adds the agent device to the MLS group.

POST /v1/send — 409 group_superseded

The channel's owner reset its secure session and this daemon still holds the previous MLS group. Nothing was sent or stored. The daemon asks the owner's client to re-admit it and never wipes its local state on this answer. Retry later with back-off; a reply sent with in_reply_to or idempotency_key is republished under the same message id once the daemon holds the new group. Until then the daemon holds that channel's inbound messages: they are not handed to the runtime and do not use up their delivery attempts, for at most 24 hours from the first refusal. Adoption and the re-admission request are skipped on FileSafe vault channels and on any channel the enclave channel listing does not show.

HTTP 409
{"error": "group_superseded", "message": "channel moved to a new secure group; not sent; retry after the agent rejoins"}

POST /v1/status — state values

state must be one of idle, working, stalled, or error. detail is an optional free-form string.


Receive modes

Three ways to receive, in order of preference for a long-running agent: the WebSocket (one socket does everything), SSE (one-way real-time push), and long-poll (a plain loop). Use one receive mode at a time per daemon.

WebSocket (recommended)

GET /v1/ws upgrades to a single persistent bidirectional socket. The agent receives live messages and sends/reports status over the same connection — no polling, no separate send channel. This is the interface to use for an always-on agent.

Two reference connectors speak this protocol today: openclaw (JavaScript) and hermes (Python), both implementing the same ADR-0009 connection-file + two-anchor-gate contract.

Authenticate with the bearer token either as a query param (ws://127.0.0.1:7077/v1/ws?token=<BRIDGE_TOKEN>) or an Authorization: Bearer header on the upgrade request. The same loopback/Origin/Host rules as the HTTP API apply; an unauthorized upgrade is accepted and then closed with code 1008.

All frames are JSON text.

Daemon → agent

{ "type":"message", "channel_id":"...", "message_id":"...", "sender_id":"...", "text":"...", "ts": 1234567890,
  "authorization": { "version":1, "audience":"owner_dm"|"team_room"|"partner_room"|"other_human_dm"|"agent_to_agent"|"unknown",
    "sender_membership":"active"|"unknown", "tool_grants":[] } }
{ "type":"sent", "message_id":"..." }                       // acks your send
{ "type":"ok" }                                             // acks your status report
{ "type":"error", "error":"channel_pending"|"invalid_request"|"group_superseded"|..., "message":"...", "detail":"..." }

The daemon derives authorization only from the authenticated channel and roster APIs; message text, display names, and model output cannot set it. Missing or stale roster data produces unknown with no grants. This release deliberately issues no channel tool grants while grant persistence and owner controls are staged, so consumers must treat tool_grants:[] as authoritative. Future side-effect grants will also bind an exact operation digest, confirmation id, idempotency key, and expiry rather than granting a tool name globally.

When memory.provider is openclaw, OpenClaw text history and workspace facts are owner-DM-only. The live fast path consumes them only when the immutable turn authorization says owner_dm with active membership. The loopback memory context API independently refreshes authenticated channel/roster metadata and returns an empty context unless the channel is a DM with exactly one non-agent human counterpart and that counterpart is the agent owner. Missing, stale, ambiguous, room, partner, other-human, and agent-to-agent state therefore fails closed without exposing OpenClaw memory.

Agent → daemon

{ "type":"send", "channel_id":"...", "text":"...", "in_reply_to":"...", "idempotency_key":"..." }   // both optional
{ "type":"status", "channel_id":"...", "state":"idle"|"working"|"stalled"|"error", "detail":"..." }
{ "type":"ack", "message_id":"..." }                        // confirms you consumed a delivered message

Acknowledge what you receive. Inbound delivery is at-least-once. Before the remote server queue is acknowledged, the daemon seals each runtime-bound message into bridge-state.db. It remains durable until you send a matching {type:"ack", message_id}. If your socket, daemon, or host disappears first, the message is restored and redelivered to the next consumer in FIFO order. The cost is that you may occasionally see a message twice; dedup by message_id. Ack as soon as you've durably handled a message, not before.

For the first-party runtime, a reply carries in_reply_to. The daemon persists a content-free reply receipt after publish, and a replacement runtime checks that receipt before running the turn again. This closes the publish-success/ACK-loss window where the result is known. It does not pretend an indeterminate external tool call is safe to repeat; those calls use the runtime's separate reconciliation ledger.

Replies are published at most once (SEC-06 #18). A send that carries in_reply_to (or, on /v1/ws, an idempotency_key) is an idempotent reply:

  • Its message_id is a deterministic, keyed UUID of (agent identity, channel, the inbound it answers, which part). The key is derived from the identity seed, so other channel members cannot predict the id and publish under it first. The voice fast path's reply id is keyed the same way. The idempotency_key is never used as the message_id itself.
  • Before the publish, the daemon writes a durable reply intent to bridge-state.db: the reply body and the signed envelope about to be sent, both sealed like the rest of the store and dropped once the publish is confirmed.
  • Every retry resends those exact envelope bytes, so a backend that already accepted them answers with the original ack (even if the epoch has moved since). A message_in_flight 409 (the original is still being processed) is retried later with the same bytes, never re-encrypted: 3 in-process retries with backoff, then the redelivery backoff and the delivery cap. The reply is re-encrypted (same id, fresh nonce) only when the backend says the earlier attempt was not accepted: a replay_nonce 409 on the exact bytes, or mls.stale_epoch, which it answers only for an id it has not seen.
  • message_id_conflict means the id slot is held by OTHER bytes, never that our reply was delivered: the cached envelope always holds the last bytes posted under the id, and a resend of those bytes gets the original ack. So the slot belongs to another message (for example an old reply whose intent was pruned): an unkeyed part moves to the next part number, and a keyed one fails with invalid_request.
  • If the inbound is redelivered while its reply has an intent (a 502 after the backend committed, a crash before the receipt, a nack), the daemon republishes that reply itself and acknowledges the inbound. The runtime is not handed the message again, so the model does not run twice.
  • A rate_limited publish (the daemon's room floor or a backend 429) is retried in-process with backoff, up to 3 times, before rate_limited is returned. The intent stays pending, so the redelivery republishes it.
  • Parts are numbered from bridge-state.db, not from memory, so a restart between two parts never reuses a published part's id. Intents are kept for 7 days (at most 5000).
  • Send an idempotency_key per reply block. Without one, a send whose text equals the MOST RECENT part of the same in_reply_to is treated as a retry of that part and returns its message_id without publishing. Two identical consecutive blocks therefore become one message. With a key, each key is its own part; resending the same key and text is a retry, and the same key with different text is refused with invalid_request. The OpenClaw and Hermes connectors send <in_reply_to>:<n> per block. idempotency_key is honoured on both /v1/ws and POST /v1/send.
  • Trade-off: a crash in the middle of a multi-part reply. If the runtime published part 1 of a reply and then the runtime, daemon or host died before it produced part 2, the redelivered message is answered from the intents: part 1 is republished (or confirmed) and the message is acknowledged. Part 2 is never produced, because producing it means running the model again, which would write a new, different reply around a part 1 that was already sent. The daemon chooses "no duplicate" over "complete".
  • An intent only answers a message the runtime was actually handed (one with a delivery attempt). A reply that names a message still waiting in the buffer does not stop that message reaching the runtime.
  • Replies to a message more than 7 days old. Intents are pruned after 7 days (or past 5000 rows), and a pruned intent's id is still held by the reply the backend stored. Replying to that same inbound again then collides with the old reply:
    • a connector key reused after the prune (for example X:0 again) is refused with 400 invalid_request, and that block is lost;
    • an unkeyed reply moves past the old reply's parts one number at a time, at most 8 per send. If the old reply had more than 8 parts, sends fail until enough collided parts have been skipped (each failed send skips up to 8).
  • Hermes: a block retried after a different block went out can be published twice. The Hermes plugin reuses a block's key only while it is the most recent unconfirmed block. If block A fails ambiguously (the daemon may in fact have published it), then block B is sent, and then Hermes retries A, the retry carries a new key and A appears twice. The OpenClaw plugin uses the same key rule; it does not retry a failed block itself, so the same case arises there only if OpenClaw's own reply dispatcher retries one.

One consumer at a time. The daemon serves a single agent per process. Opening a second /v1/ws connection closes the first (newest wins, code 1000); the replaced socket's un-acked messages are re-buffered for the new one. Don't run two consumers against one daemon expecting to share the stream.

Keepalive. The daemon pings every 30 seconds and reaps a socket that misses a pong. Clients using the standard WebSocket API answer pings automatically.

Runnable clients are in examples/: ws-agent-client.mjs (Node) and ws-agent-client.py (Python, pip install websockets). Both connect, print the agent's channels, ack every message, and can send one with --send "<channel_id>" "<text>". A minimal receive-and-ack loop in Node:

const token = (await fs.readFile("/path/to/credential-dir/bridge-token", "utf8")).trim();
const ws = new WebSocket(`ws://127.0.0.1:7077/v1/ws?token=${encodeURIComponent(token)}`);

ws.addEventListener("message", (ev) => {
  const frame = JSON.parse(ev.data);
  if (frame.type === "message") {
    handle(frame);                                          // your work
    ws.send(JSON.stringify({ type: "ack", message_id: frame.message_id }));
  }
});

// send any time over the same socket
ws.send(JSON.stringify({ type: "send", channel_id: "<id>", text: "Hello from the agent" }));

And in Python (websockets):

import asyncio, json, websockets

async def main():
    token = open("/path/to/credential-dir/bridge-token").read().strip()
    async with websockets.connect(f"ws://127.0.0.1:7077/v1/ws?token={token}") as ws:
        await ws.send(json.dumps({"type": "send", "channel_id": "<id>", "text": "Hello"}))
        async for raw in ws:
            frame = json.loads(raw)
            if frame.get("type") == "message":
                handle(frame)
                await ws.send(json.dumps({"type": "ack", "message_id": frame["message_id"]}))

asyncio.run(main())

SSE (real-time)

GET /v1/events?channel_id=<id> opens a persistent SSE connection. Messages arrive as named message events:

event: message
data: {"channel_id":"...","message_id":"...","sender_id":"...","text":"...","ts":1234567890}

The daemon sends a :keepalive comment every 15 seconds to keep the connection alive through proxies. Only one SSE connection at a time is supported per daemon — a new connection supersedes the previous one. The old stream is closed cleanly.

An initial :connected comment is sent when the connection is established, before any messages.

Long-poll (simple loop)

GET /v1/messages?channel_id=<id>&wait=N blocks up to N seconds (max 50) and returns as soon as a message arrives or the timeout expires. With wait=0 it returns immediately with whatever is buffered.

A simple receive loop:

while True:
    msgs = requests.get(f"{BASE}/v1/messages",
                        headers=HEADERS,
                        params={"channel_id": CHANNEL, "wait": 50}).json()
    for m in msgs:
        handle(m)

Pick one receive mode — WebSocket, SSE, or long-poll — and stick with it. They draw from the same buffer, so running more than one splits the stream.


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 and 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 — a zero-dependency agent that follows the section literally and prints a pass/fail line per rule:

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.

systemd unit (/etc/systemd/system/securecoms-bridge.service):

[Unit]
Description=SecureComs Agent Connector
After=network.target

[Service]
Type=simple
User=agentuser
WorkingDirectory=/home/agentuser
ExecStart=/usr/bin/npx @agentvault/connect-agent-bridge \
  --credential /home/agentuser/agent.json \
  --store /home/agentuser/bridge-state.db
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now securecoms-bridge

Read the token after the first boot:

cat /home/agentuser/bridge-token

pm2 (for dev or non-root servers)

pm2 start "npx @agentvault/connect-agent-bridge --credential ./agent.json" \
  --name securecoms-bridge

Install behavior

agent-bridge install --credential <path> (launchd on macOS, systemd user unit on Linux) prepares and verifies the service rather than pointing it at your download:

  • The credential file is validated (readable, valid JSON, all required fields) and copied into a durable per-agent directory ~/securecoms-agent-<slug>/ (dir 0700, file 0600). The service runs from that copy, so moving or deleting the original download can't break the daemon. A directory already owned by a different agent identity is refused, never overwritten.
  • 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|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.

Security

Loopback-only by default. The daemon binds 127.0.0.1:7077. Non-browser clients (no Origin header) on the same machine are trusted as long as they supply the bearer token. Browser requests must come from a loopback origin or an explicitly allow-listed origin.

Bearer token. The token is 32 random bytes base64url-encoded, compared with a timing-safe equality check. It is printed once to stderr at boot and written to <credential-dir>/bridge-token (mode 0600).

DNS rebind protection. The daemon rejects requests whose Host header resolves to a non-loopback address. This blocks the standard DNS rebind attack against loopback services.

Origin allow-list. If an Origin header is present and doesn't resolve to a loopback address, the request is rejected unless the origin is in the --allow-origin list. Absent Origin (non-browser clients) is always allowed.

Cross-host use. The daemon refuses to bind a non-loopback address without TLS:

connect-agent-bridge --credential ./agent.json \
  --bind 0.0.0.0 \
  --tls-cert ./cert.pem \
  --tls-key ./key.pem

The loopback hop carries plaintext by design — the agent is the endpoint and the trust boundary is the machine. The SecureComs server still sees ciphertext only.


Owner signing key (tool settings)

The Connector can hold the owner's signing key, so it can check that a message or a tool setting really came from the agent's owner. The SecureComs server never supplies this key. The Connector reads it only from two files on this machine, once, when it starts.

Format. The key file is owner-signing-key.json and holds exactly three fields, nothing else:

{
  "owner_identity_id": "0a0a0a0a-1111-4222-8333-444444444444",
  "key_algo": "ed25519",
  "public_key": "<base64 of the 32-byte Ed25519 public key>"
}

owner_identity_id is the owner's identity id in lowercase. The credential file can carry the same object under owner_signing_key. If both are present they must match exactly; if they differ the Connector uses neither.

Location. owner-signing-key.json sits in the same folder as the credential file.

No symbolic links. A key file that is a symbolic link is refused, and the Connector then uses no key at all, whatever the credential holds.

Permissions. Keep the file at mode 0600, like the credential. A looser mode is logged as a warning and the key is still used.

Setting or changing the key. Use the pin command. All three flags are required:

agent-bridge pin --credential <credential.json> --file <owner-signing-key.json> --agent <agent_identity_id>

The key file must be in the same folder as the credential file, and --agent must be the credential's own agent identity, so the command cannot change another agent's credential. It prints the agent identity before it changes anything. It rewrites the key file and the credential's owner_signing_key together, through temporary files and renames, so an interrupted run leaves either the old key, the new key, or no key, never a wrong one. Restart the Connector afterwards to use the key.

Counters. Each owner-signed tool setting carries a counter that only goes up. Pinning the same key again keeps the stored counter. Pinning a new key starts a new counter, and the old key's stored settings are dropped.

Upgrade note

Owner messages stored before this release cannot be verified, because they were stored without their signature. On a Connector that holds the owner's signing key, a redelivered old message runs without tools or memory.


Attachments and any-language agents

The daemon is the universal substrate: an agent in any language (Python, Go, TypeScript, ...) connects over the local loopback WS/HTTP and never speaks MLS itself. The daemon performs all MLS encryption/decryption in TypeScript and hands the agent plaintext — message text and, for attachments, a local file path.

  • Receiving an attachment: the delivered message includes attachments: [{ filename, mime, size, path, sha256 }]. Read the file at path (saved under <store-dir>/attachments/<channel>/). No MLS, no key handling.
  • Sending an attachment: copy the file into the vault outbox (path from the authenticated GET /v1/vault-outbox), then POST /v1/send-attachment with { "channel_id": "...", "path": "<vault_outbox>/file.png", "caption": "optional" }. The daemon reads, encrypts, uploads, and dispatches it, then deletes the outbox copy. A path outside the outbox (including a received file under <store-dir>/attachments/) is refused with 400 path_outside_outbox.

This is why Python agents (which have no native MLS library) fully support attachments: the cryptography lives in the daemon, not the agent.

Files links (vault_ref). A message can instead point at an item already in the enclave's Files (FileSafe). The daemon does not fetch it on receipt: the delivered message carries the caption as text ("[Files link]" when there is none) and a reference, vault_refs: [{ enclave_id, node_id, content_hash, dek_commit, name_hint?, mime_hint?, size_hint? }]. The *_hint fields are the sender's unverified claims; treat them as data, never as a path or an instruction. A link whose enclave is not the channel's, or whose fields are malformed, is dropped (counted as refused_vault_refs on /healthz). To open one, call POST /v1/vault-read with { enclave_id, node_id, expected_content_hash: content_hash, expected_dek_commit: dek_commit }. The two pins go together: sending only one is a 400. If the item changed in Files after it was shared, the daemon refuses with 422 {"error":"vault_ref_changed","detail":{"pin":"..."}} and returns no bytes. /healthz advertises support as capabilities.vault_ref: 1.


Voice fast path

On a live voice call, the daemon can send an instant, persona-voiced one-sentence acknowledgement while your full agent harness is still thinking — so the human hears something immediately instead of dead air.

The credential file's voice block is now a fallback, not the primary source. As of @securecoms/agent-bridge 0.13.0, the daemon fetches this agent's voice settings from the backend (GET /api/v1/agents/{identity_id}/voice-settings) on start and again whenever it receives a voice_settings_changed ping, and prefers that backend row whenever its version is ≥ 1 — an owner has saved settings from the web app's "Voice settings" page (/app/agents/:identityId/voice). A version: 0 response (nothing saved yet) keeps the file's persona/voice/pace as a default, but the fast-path LLM call goes through the SecureComs backend proxy (POST /api/v1/voice/fast-complete) whenever the settings fetch itself succeeds — voice_settings_source is "backend", or "file" with version: 0 — and in that case the file's own fast_path.api_key/base_url/model are ignored; only the file's persona and enabled flag still matter, as the fallback source for those fields. The daemon needs no API key of its own for the proxied path — the backend proxy holds OPENROUTER_API_KEY and does the call. If the settings fetch itself fails at boot (network error, backend down), the daemon has no proxy config to fall back to and instead falls back to the file's own fast_path block in full, including its api_key/api_key_env/base_url/model — the daemon then calls your own model provider directly with that key until a later fetch succeeds.

Check which source is active via the daemon's health endpoint:

curl -H "Authorization: Bearer $(cat <credential-dir>/bridge-token)" \
  http://127.0.0.1:7077/healthz | jq '.voice_settings_version, .voice_settings_source'

voice_settings_source is "backend" (a saved row won), "file" (fell back to the credential file's voice block), or "none" (neither is configured).

Add a voice block to agent.json (used only as the fallback described above):

"voice": {
  "persona": { "display_name": "Cortina",
               "persona": "You are Cortina, a crisp, warm operations lead who co-owns AgentVault with Eric and Chris.",
               "quirks": ["opens with 'Right —' when sure", "asks one clarifying question instead of guessing"] },
  "fast_path": { "enabled": true, "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini",
                 "api_key_env": "SECURECOMS_VOICE_LLM_KEY", "timeout_ms": 2500, "max_tokens": 80 }
}
  • persona describes how the fast-path model should speak; it is folded into a compiled-in system prompt shared with the daemon's other voice guidance.
  • fast_path.api_key_env names an environment variable holding your LLM provider's API key (e.g. SECURECOMS_VOICE_LLM_KEY); api_key accepts one inline instead, but the env-var form is preferred so the key never lives in the credential file. Without a resolvable key, the fast path stays disabled even if enabled: true.
  • fast_path.base_url must be https:// or a loopback (127.0.0.1 / localhost / ::1) http:// URL — the daemon refuses any other non-loopback plaintext endpoint, the same rule it applies to itself.
  • Only a genuine live voice turn from a human (or unknown) sender fires the fast path; it never fires for the agent's own relayed turns, and a fast-path failure (timeout, network, bad response) is fail-soft — it never blocks or delays your full agent's reply.

The fast-path call runs through the SecureComs backend proxy — your own model key never pays for it — whenever the settings fetch succeeds (the fast_path.api_key/api_key_env/base_url/model fields above are ignored whenever voice_settings_source is "backend", or "file" with version: 0; they only take effect again if the settings fetch fails at boot, in which case the daemon falls back to the file's own fast_path including its key). Each proxied call is metered server-side (voice_fast_completions table; usage_daily metrics fast_voice_calls, fast_voice_tokens_in, fast_voice_tokens_out), capped at VOICE_FAST_CALLS_PER_MINUTE (default 60) per agent.

Calling your own provider directly (route: "direct")

To keep the fast-path call off the SecureComs proxy entirely, add "route": "direct" to the credential file's fast_path block:

"fast_path": { "enabled": true, "route": "direct", "base_url": "https://api.openai.com/v1",
               "model": "gpt-4o-mini", "api_key_env": "SECURECOMS_VOICE_LLM_KEY" }
  • With route: "direct" the daemon calls base_url with the file's own api_key/api_key_env, and never calls POST /api/v1/voice/fast-complete, even when the settings fetch succeeds. The backend voice settings (persona, dials, voice, pace) still apply; only the fast-path provider and key come from the file. A later voice_settings_changed refetch keeps the direct route.
  • Opt-in lives only in this file. There is no web or backend setting for it, and only the exact value "direct" counts: a block without route (or with any other value) behaves as described above, so an old fast_path block does not switch to direct on upgrade.
  • If the direct provider fails (timeout, HTTP error, bad response), nothing is spoken by the fast path and your full agent answers the turn. The daemon never retries through the SecureComs proxy.
  • route: "direct" without a resolvable key is a configuration error: the daemon logs voice.fast_path_direct_no_key once at start and runs with no fast path (full agent only). It does not fall back to the proxy.
  • The prompt sent to your provider is the same call-scoped prompt the proxy would get: the call's own spoken turns only, no typed chat, notes or memory. The x-securecoms-bridge-caps header is never sent to your provider.
  • Call summaries use the same client: with route: "direct" they are also generated by your provider, never the SecureComs proxy. With no usable key, call summaries are unavailable (as is the fast path).

Unified memory (0.29.0)

Agent Connector 0.29.0 replaces the Markdown notes of 0.27 and the semantic memory of 0.28 with one memory. In this release it works in the owner's private chat only. Rooms and other people's private chats are not remembered.

What the agent remembers.

  • Each message the owner types in their private chat. A message that looks like a password or a key is not saved at all.
  • What the owner says on a call in their private chat, when the Agent Connector gets the turn as transcribed speech from a relay that the server verified as the owner. A spoken turn that arrives before the Agent Connector has its runtime config after a restart is not saved. Spoken words cannot be pinned, and a call cannot forget.
  • The agent's own replies in that chat, as reference material. A message the agent sends that does not reply to a message is not saved.
  • Pinned facts. The owner asks the agent to pin a fact, and the Agent Connector posts Pinned: "<fact>" Say "forget that" to remove it. in the chat. Each word that carries meaning must be a word the owner typed. Words spoken on a call do not count. At most 200 pinned facts, each at most 400 characters.
  • "Forget that". The owner types it in their private chat. The agent removes one memory shown with that message, and the Agent Connector posts Forgot: "<text>". The agent makes one change (a pin or a forget) per owner message.

Where it is kept. Each memory is sealed per row in bridge-state.db (schema v12) on the agent's machine. The Agent Connector delivers memories only to the /v1/ws socket of a runtime that declares memory_unified in its hello. A harness socket never receives them. The model provider sees the memories delivered with each turn. Beside the pinned facts, a typed turn gets at most 10 memories and a voice turn at most 3. The Agent Connector waits up to 600 ms for a typed turn's memory search and up to 250 ms for a voice turn's.

Limits. The limit is 2 GB or 100,000 memories, whichever comes first. When it is full, the oldest automatic memories are removed first. Pinned facts are never removed. At 80%, the app shows: "{name}'s memory is 80% full ({used} of {limit}). The limit is 2 GB or 100,000 memories, whichever comes first. When it is full, the oldest automatic memories are removed first. Pinned facts are never removed." The app also says: "The more {name} remembers, the harder it is to find older details; pinned facts are always in front of it."

RAM. Plan for about 102 to 104 MiB more memory per agent at 100,000 memories (measured 2026-10-11 in a standalone process on an x86_64 laptop). A small store uses less.

The search model. The Agent Connector downloads its search model from downloads.securecoms.ai the first time the owner messages the agent in their private chat with memory on, if the model files are not already on the machine. On a machine that must make no such connection, set memory.model_source to import_only in the credential file and copy the model bundle in with agent-bridge models import <dir>. Without the model, the agent finds memories by keyword only. On Windows it finds memories by keyword only in this release.

If you embed the Agent Connector as a library (new BridgeAgent(cfg, deps)), pass hostMachine: true. Without it, no model is downloaded or loaded, no call heartbeat is written, and the agent finds memories by keyword only. The agent-bridge command passes it for you.

Compatibility.

  • Install @securecoms/agent-runtime 0.12.0 together with the Agent Connector and restart both (launchctl bootout then bootstrap, never kickstart). A runtime whose hello does not declare memory_unified (0.11.0 or older) gets no memories. That is not a supported pairing.
  • Harness daemons (Hermes, OpenClaw) must name memory.provider in their credential file. A daemon whose file omits it is treated as securecoms: its Agent Connector saves owner private-chat memories on disk, although its harness socket never receives them. A global npm install -g --prefix ~/.local reaches every daemon whose plist points at the global dist/bin.js, at its next restart. Check each credential file (jq .memory.provider <credential-file>) before you install.
  • Memory is off in a freshly started Agent Connector until a runtime-config refetch succeeds. An Agent Connector restarted while the backend is unreachable saves and recalls nothing until the backend answers.

Old notes and semantic memory. The Agent Connector copies a private chat's old memory into unified memory in the background, after the owner's first typed message in that chat on 0.29.0:

  • 0.27 notes become pinned facts. The 200-fact limit does not apply to them.
  • 0.28 semantic memory rows become automatic memories. Their search vectors are kept.
  • The chat's stored history becomes reference memories.
  • A message forgotten in 0.28 is not copied. Text that looks like a password or a key is not copied. Old facts, and the history of rooms and of other people's private chats, are not copied.

The old tables stay in this release, so a rollback works. Clear all and "forget that" also delete the matching old rows.

Off switches. There are four. Use the narrowest that fits.

  • Agent memory off in the agent settings. The agent saves nothing new and recalls nothing. It still sees the recent messages of the chat. Turning memory off does not delete memories. Use Clear all for that.
  • memory.enabled: false in the credential file, then a daemon restart. The same effect, and the backend cannot turn it back on. Any value other than true turns memory off.
  • memory.provider: "none" in the credential file, then a daemon restart. This turns memory off, and it also drops the recent history.
  • SECURECOMS_OWNER_DM_DEFAULT_GRANTS=off in the Agent Connector service environment. This turns memory off, and it also drops the owner private-chat tools.

SECURECOMS_TOOL_DENY=memory_note (runtime environment) removes only the pin and forget tool. The agent still saves and recalls memories.

Known limitations.

  • A pin can reorder the owner's words or leave one out, including a negation ("don't pay Bob, pay Alice" can be pinned as "pay Bob"). Read the Pinned: line, and say "forget that" if it is wrong.
  • Clear all deletes memories. It does not delete chat history.
  • Forget and clear are logical deletes: sealed bytes can stay in free database pages or the WAL until they are overwritten, and they still open under the device key.
  • The model provider sees the memories that the Agent Connector delivers.

Log events. All are content-free: counts and classes only, never memory text. memory.item_written (source, chunks), memory.item_skipped (reason_class), memory.pin_written, memory.item_forgotten, memory.note_refused (reason_class), memory.migration_ran (notes, recall, history, skipped, excluded, aborted, unreadable), memory.owner_scope_purged (count), memory.unified_off (reason_class: off, unrecognized, local or clear_pending), memory.ranking_worker_exited (inFlight), and these failure events with the error class only: memory.unified_clear_failed, memory.unified_switch_failed, memory.unified_report_failed, memory.unified_prepare_failed, memory.unified_reply_failed, memory.unified_boot_reconcile_failed, memory.migration_failed, memory.owner_scope_sweep_failed, memory.note_write_failed, memory.pinned_line_failed, memory.forgot_line_failed, memory.evict_failed, memory.reembed_failed, memory.model_upkeep_failed, memory.ranking_notify_failed and memory.ranking_worker_spawn_failed.

/healthz and the machine report. /healthz adds memory_hot_bytes, memory_deadline_misses, memory_reads, memory_reads_discarded and pid. The machine report adds memory_unified_enabled, memory_size_bytes, memory_item_count, memory_db_bytes and memory_near_full. All are numbers or booleans.

Upgrade order. Upgrade and restart the Agent Connector and the runtime together. First check memory.provider in the credential file of every daemon that a global install reaches (jq .memory.provider <credential-file>).

Rollback. Roll back the Agent Connector and the runtime together, to 0.28.2 and 0.11.0, and restart both. A 0.28.2 Agent Connector opens the database, ignores the unified tables, and works on the old notes, semantic memory rows and history that 0.29.0 kept. It does not see what 0.29.0 saved, pinned facts included. It never removes or clears the unified tables, so the size limit does not apply to them until you upgrade again. When 0.29.0 starts again, before it serves anything, it removes copied pins whose old note was deleted during the rollback, removes copied memories whose message was forgotten, and applies a Clear all done during the rollback. Old rows added during the rollback are copied after the owner's next typed message.


Release notes: 0.47.0

What's new

  • Decision Engine checks (not yet available). The Agent Connector can now ask the SecureComs Decision Engine to check a request before it runs, when the owner turns checks on for the agent and the workspace has opted in. It can flag or block a request; it never approves anything. No workspace can turn this on yet.

Good to know

  • After a restart, requests that were waiting for a check while the agent was paused or the Agent Connector was stopped are marked "not checked (restart)". If checks are set to block when unavailable, those requests are cancelled and the owner asks again.

Upgrade

  • This release upgrades the agent's local ledger. Stop every copy of the Agent Connector for the agent before starting this version.
  • Older versions cannot open the upgraded ledger: roll forward, not back. An older Agent Connector started on an upgraded ledger runs with approvals turned off.
  • Upgrade the agent runtime to 0.23.0 at the same time.

Release notes: 0.46.0

What's new

  • You approve what your agent changes. When an agent wants to send a request that changes something (anything other than a read), it now asks first. You see exactly what it will send in an approval sheet in SecureComs, and it runs only after you approve it on your device. Each approved request runs once.
  • A signed record of every approval. The Agent Connector keeps a hash-chained ledger of each request, your decision and the result, signed by a key that stays on the agent's computer. A copy appears in your chat with the agent. agent-bridge ledger verify and agent-bridge ledger export check and export it.
  • Set up approvals. On the agent page, choose Set up approvals, then run the agent-bridge countersign enroll line it shows on the agent's computer.
  • Pause wins. Pausing or stopping the agent cancels approved requests that have not run yet.

Good to know

  • To turn approvals off on one computer, set "countersign_enabled": false in the agent's credential file and restart the Agent Connector. Re-downloading the credential file turns them back on.
  • If the agent's owner changes, restart the Agent Connector.
  • If you think the ledger key was exposed, follow the "Ledger key compromise" runbook (agent-bridge countersign rotate-ledger-key --compromised).

Upgrade

Upgrade the Agent Connector and the agent runtime together (runtime 0.22.0). With an older Agent Connector, the new runtime refuses requests that change something instead of asking.

Release notes: 0.45.0

What's new

  • Pause and stop now reach the Agent Connector. When you pause or stop an agent in SecureComs, the Agent Connector holds all of the agent's work at once, in every chat. Resume releases it. A stopped Agent Connector restarts by itself when you resume the agent.
  • Revoke is final, rotate is not. If you revoke the agent's credential, the Agent Connector removes its connection file and stops for good. If you rotate the credential, it waits for you to install the new file and keeps its data.
  • Local pause and stop. On the agent's computer you can run agent-bridge pause, agent-bridge stop and agent-bridge resume. A local resume never lifts a pause set in SecureComs.
  • Health shows the control state. /healthz now includes control with the mode and whether work is held.

Good to know

  • On start the Agent Connector checks the agent's control state before it delivers any message. If it cannot reach SecureComs, it holds work and retries.
  • A pause no longer uses up a message's delivery attempts.

Upgrade

Recommended. Older Agent Connectors (0.44.1 and earlier) can lose replies to messages that arrived just before a stop. This release keeps them. Upgrade the Agent Connector only; the runtime and the OpenClaw and Hermes plugins do not change.

Release notes: 0.44.1

What's new

  • New name in messages. The Agent Connector now calls itself the "SecureComs Agent Connector" in its setup, service and error messages. The OpenClaw and Hermes plugins use the new name too.

Good to know

  • Nothing else changed. Commands, file names and settings stay the same. You still run agent-bridge, and the package is still @securecoms/agent-bridge.

Upgrade

Optional. Upgrade the Agent Connector and the runtime together (runtime 0.21.1). No OpenClaw or Hermes plugin change is needed.

Release notes: 0.44.0

What's new

  • Update notices. The SecureComs Agent Connector now tells SecureComs which Agent Connector and runtime versions it runs. SecureComs uses this to tell you when an update is available for your agent. The notice appears in the app later.

Good to know

  • The Agent Connector sends only version numbers and the time it last saw the runtime. It sends no messages, names or keys.
  • The Agent Connector sends the report when it starts, when the runtime connects, and every 6 hours.
  • The Agent Connector never updates itself. You stay in control of when to update.

Upgrade

Upgrade the Agent Connector and the runtime together (runtime 0.21.0). No OpenClaw or Hermes plugin change is needed.

Release notes: 0.43.0

What's new

  • Delete for everyone now reaches the bridge. When a person deletes their own message for everyone, the bridge removes it from the agent's memory, search index, queue and saved files. The bridge does not store that message again if it arrives a second time.

Good to know

  • Only the person who sent a message can remove it this way. A delete from anyone else is ignored.
  • Some copies stay. The bridge cannot remove facts or notes the agent made from the message, reminders created from it, the agent's own replies, the agent app's own session history, or text already sent to the AI model.
  • Messages received before this update are removed only if the bridge saved them in its memory.

Upgrade

Upgrade the bridge. No connector or runtime change is needed.

Release notes: 0.42.0

What's new

  • Reminders and cancellations requested after the agent read web content, files or images now ask you to confirm with a short code. Upgrade the agent runtime to 0.20.0 with this release.

Good to know

  • A message in your DM that is exactly confirm schedule <number> <code> or `cancel