@securecoms/agent-bridge 0.29.0 → 0.30.1

package/README.md

@@ -56,17 +56,23 @@ The bundled connectors give tools only to the agent owner's turns. Each harness
 
 On an older harness the connector 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 connector 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 connector files) so the harness loads the new connector, then restart the harness gateway.
 
-### Room tool rule (0.26.6 and later)
+### 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, a same-org human sender's turn may use `current_time` only. Cross-org and unknown rooms get no tools. The owner DM keeps `current_time` and `web_search`. Replies to room turns are re-classified when they are sent.
+<!-- [COPY, approved by Eric 2026-10-12] -->
+
+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`. <!-- [COPY, approved by Eric 2026-10-12] --> Replies to room turns are re-classified when they are sent.
 
 Operator steps:
 
-- **Deploy order:** backend (already live), then this bridge, then `@securecoms/agent-runtime` 0.9.9. A new runtime on an old bridge offers no tools on the owner's relayed voice turns. Room grants need both the new bridge and the new runtime.
+- **Deploy order:** backend (already live), then this bridge, then `@securecoms/agent-runtime` 0.13.0. A new runtime on an old bridge offers no tools on the owner's relayed voice turns. Room grants need both the new bridge and the new runtime.
 - **Re-wire connectors:** re-run `agent-bridge wire --harness ...` on every Hermes and OpenClaw host after upgrading. Connectors are copied at wire time and an upgrade does not refresh them. A bridge downgrade after re-wiring makes the new connectors refuse tools on the owner's voice turns.
 - **Kill switch:** `SECURECOMS_ROOM_DEFAULT_GRANTS` (bridge 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` (bridge 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. <!-- [COPY, approved by Eric 2026-10-12] -->
+- **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 bridge 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. <!-- [COPY, approved by Eric 2026-10-12] -->
+- **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. <!-- [COPY, approved by Eric 2026-10-12] -->
 - **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 a bridge restart, a reply to a room turn granted before the restart is not re-classified. Only `current_time` output can be affected.
+- **Restart residual:** after a bridge restart, a reply to a room turn granted before the restart is not re-classified. `current_time` and `web_search` output can be affected. <!-- [COPY, approved by Eric 2026-10-12] -->
+- **`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. <!-- [COPY, approved by Eric 2026-10-12] -->
 - **Post-deploy probe:** count `connect.roster_mirror_unresolved` warnings and rooms reading `unknown`. A high rate means roster mirror drift is hiding room tools.
 
 ---
@@ -596,6 +602,68 @@ The loopback hop carries plaintext by design — the agent is the endpoint and t
 
 ---
 
+## Owner signing key (tool settings)
+
+<!-- [COPY, approved by Eric 2026-10-12] owner-signed tool grants spec 2026-10-12 section 10 K-19. -->
+
+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:
+
+```json
+{
+  "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:
+
+```bash
+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
+
+<!-- [COPY, approved by Eric 2026-10-12] owner-signed tool grants spec 2026-10-12 section 10 K-27. -->
+
+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,
@@ -867,6 +935,82 @@ copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.30.1
+
+<!-- [COPY, approved by Eric 2026-10-14] -->
+
+0.30.1 makes sure only one copy of an agent runs, and makes install say
+clearly when the agent did not start.
+
+- **Reinstall once after you upgrade.** Run the install command again for
+  each agent. It writes a new service file. The old file restarts the
+  Connector every time it stops, so a refused second copy would keep
+  restarting and print the "already running" message every 10 seconds.
+- **One copy per agent on a computer.** A second copy of the same agent
+  stops before it connects and prints: `This agent is already running on this
+  computer (process <pid>). Stop that copy first, or run: agent-bridge status`
+- **Port already in use.** If another program holds the Connector's port, the
+  agent does not start and prints: `Port <n> is already in use by another
+  program on this computer, so the agent did not start.`
+- **Install checks that the agent really started.** Install now waits up to
+  75 seconds for the Connector to answer its health check. If it does not
+  answer, install fails and names the service log.
+- **Install refuses a second install of the same agent.** If the agent is
+  already installed in another folder or with a different key, install stops
+  before it changes anything and prints: `This agent is already installed in
+  <dir> with a different key. Uninstall it first: agent-bridge uninstall
+  --label <label>`. A downloaded copy such as `margo (1).json` installs as the
+  same agent, not as a new one.
+- **The service restarts only after a failure.** On macOS the new service
+  file restarts the Connector only when it exits with an error. On Linux the
+  unit uses `Restart=on-failure`.
+- **Prepared for one active connection per agent.** When the server reports
+  that the agent connected from another place, this copy stops all network
+  traffic and prints: `This agent connected from another place, so this copy
+  stopped. Stop the other copy, then restart this one.` It stays stopped and
+  does not restart itself. The server side of this check is not turned on yet.
+
+---
+
+## Release notes: 0.30.0
+
+<!-- [COPY, approved by Eric 2026-10-12] -->
+
+0.30.0 lets the owner choose which read tools an agent has, and the Connector
+checks that choice against the owner's own signing key. Install it together
+with `@securecoms/agent-runtime` 0.13.0 and restart both. See "Owner signing
+key (tool settings)" above.
+
+- **Owner-set tools.** In the web app the owner chooses tools for the private
+  chat (`web_search`, `fetch_url`, `http_request` with GET, `sql_query`) and
+  for rooms in the owner's org (`web_search`). `current_time` is always on.
+- **A key is required.** The choice takes effect only on a Connector that
+  holds the owner's signing key (the `pin` command). Without a key, the
+  agent keeps today's tools: `current_time` and `web_search` in the private
+  chat, `current_time` in rooms.
+- **What the Connector checks.** It checks the owner's signature on each
+  private-chat message and on the tool settings. A message it has already
+  processed gets no tools. If the settings the server sends differ from what
+  the owner signed, the agent falls back to today's tools, limited to what the
+  owner signed.
+- **Signed targets.** The endpoints for `http_request` and the databases for
+  `sql_query` come from the signed settings only. A `sqlite` path must be its
+  real path.
+- **Room web search.** Rooms in the owner's org can use `web_search`. The
+  limit is 50 calls a day for each room and 200 a day for each agent (UTC
+  days). The agent posts one notice in a room when that room reaches its limit.
+- **Agent frameworks.** An agent that runs through another agent framework
+  (Hermes or OpenClaw) gets no tools from SecureComs once it holds a key and
+  signed settings.
+- **Older runtime.** With `@securecoms/agent-runtime` 0.12.2 or older, the
+  Connector uses the fallback in every place.
+- **Off switches.** `SECURECOMS_OWNER_DM_MANIFEST_GRANTS` and
+  `SECURECOMS_ROOM_MANIFEST_GRANTS` are new. See "Room tool rule" above.
+- **Upgrade note.** Owner messages stored before this release cannot be
+  verified. See "Upgrade note" above.
+
+---
+
 ## Release notes: 0.29.0
 
 <!-- [COPY, NEW] Approved by Eric 2026-10-11 (plan Task 37). -->
@@ -887,11 +1031,14 @@ together with `@securecoms/agent-runtime` 0.12.0 and restart both. See
 - **Off switches.** A new credential key, `memory.enabled: false`, turns memory
   off on the machine. `SECURECOMS_TOOL_DENY=memory_note` now removes only the
   pin and forget tool; automatic memory continues.
-- **Skills in the owner's private chat.** With runtime 0.12.0, the memory
-  tool gate refuses every skill on the owner's private-chat turns. Only
-  `current_time`, `echo`, `memory_note`, and `web_search`, `fetch_url`,
-  `http_request` (GET) and `sql_query` with arguments that pass the gate, run
-  there. Skills in rooms are not changed.
+<!-- [COPY, approved by Eric 2026-10-12] skills spec 2026-10-12 section 7 C-5. -->
+- **Tools in the owner's private chat.** With runtime 0.12.0 or later, the
+  memory tool gate checks every tool call on the owner's private-chat turns.
+  The tools this bridge grants there are `current_time`, which runs as usual,
+  and `web_search`, which runs when its query does not repeat a number, link,
+  address or wording from memory or the chat history that the owner did not
+  type in that message. Custom skills are not offered on any turn, in the
+  private chat or in rooms, and were not before this release.
 - **`/healthz`.** New `memory_hot_bytes`, `memory_deadline_misses`,
   `memory_reads`, `memory_reads_discarded` and `pid`.
 

package/dist/bin.d.ts

@@ -1,9 +1,22 @@
 #!/usr/bin/env node
+/**
+ * SecureComs Agent Bridge — HTTP daemon entry point.
+ * Long-running diagnostics go to stderr through the content-free service
+ * logger. The local bearer token is persisted to the `bridge-token` file (see
+ * tokenFile below); startup emits only a fixed token-loaded event, never the
+ * token, its fingerprint, or its path. This prevents the former
+ * `BRIDGE_TOKEN=<value>` leak into journald/launchd logs.
+ */
+import { type BridgeConfig } from "./config.js";
 import { BridgeAgent } from "./bridge-agent.js";
 import { createHttpServer } from "./http-server.js";
 import { attachAgentWebSocket } from "./ws-server.js";
+import { createServer as netCreateServer } from "node:net";
+import { type DaemonHealth } from "./service/install-prep.js";
 import { type ResolveNodeDeps } from "./service/resolve-node.js";
 import { type Harness } from "./service/wire.js";
+import { type ServiceLog } from "./service-log.js";
+import { type LockResult } from "./service/instance-lock.js";
 export declare function nodeMajorOk(version: string): boolean;
 /**
  * A redacted bearer-token hint for explicit foreground install output: a short
@@ -11,10 +24,13 @@ export declare function nodeMajorOk(version: string): boolean;
  * diagnostics do not call this helper or expose even the hint.
  */
 export declare function tokenFingerprint(token: string): string;
-export declare function parseVerb(argv: string[]): "install" | "uninstall" | "status" | "wire" | "unwire" | "models" | null;
+export declare function parseVerb(argv: string[]): "install" | "uninstall" | "status" | "wire" | "unwire" | "models" | "pin" | null;
 export declare function slugFromCredentialPath(credentialPath: string): string;
 export declare function chooseInstallExecPath(runningExecPath: string, override: string | undefined, deps: ResolveNodeDeps): string;
+export declare function realGetHealth(port: number): DaemonHealth | null;
 export declare function realCopyConnector(srcDir: string, dstDir: string, harness: Harness): void;
+/** The stderr line (with newline) a failed service verb prints. */
+export declare function formatServiceError(verb: string, e: unknown): string;
 /**
  * Markdown memory 7a, N-L5: start the agent, THEN create the HTTP server and
  * attach /v1/ws. start() applies the runtime config (and any clear issued
@@ -35,3 +51,69 @@ export declare function startThenServe(agent: BridgeAgent, opts: {
     closeAllSseStreams: () => void;
     agentWs: ReturnType<typeof attachAgentWebSocket>;
 }>;
+/** B1 `held` poll (spec §4.1.2, audit r2 M-3): the holder may be this same
+ *  service's previous process, still inside shutdown()'s 8 s drain window. */
+export declare const HELD_POLL_TOTAL_MS = 10000;
+export declare const HELD_POLL_INTERVAL_MS = 500;
+/** Extra acquires after the poll when "held" carries no holder pid (a takeover
+ *  race). M1 names a real pid or is not printed. */
+export declare const HELD_NO_PID_REACQUIRES = 3;
+/** shutdown()'s hard-exit fallback for a hung agent.close() drain (ADR-0008 H1). */
+export declare const SHUTDOWN_HARD_EXIT_MS = 8000;
+/** The lock surface runMode uses (InstanceLock in production). */
+export interface RunModeLock {
+    acquire(): {
+        result: LockResult;
+        holderPid?: number;
+    };
+    release(): void;
+    lastError?: unknown;
+}
+/**
+ * Everything run mode touches outside the process, injected so the start
+ * order, the refusal exits and the release timing are testable
+ * (bin-run-mode.test.ts). `exit` never returns in production; runMode
+ * returns right after calling it so a recording test double also stops.
+ */
+export interface RunModeDeps {
+    credentialPath: string;
+    storePath?: string;
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+    home: string;
+    newLock(path: string): RunModeLock;
+    newAgent(cfg: BridgeConfig): BridgeAgent;
+    /** The B2 pre-bind's socket layer (node:net in production). */
+    net: {
+        createServer: typeof netCreateServer;
+    };
+    serve: typeof startThenServe;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    /** Arms the shutdown hard-exit fallback; returns its cancel. */
+    setHardExitTimer(cb: () => void, ms: number): () => void;
+    onSignal(signal: "SIGINT" | "SIGTERM", handler: () => void): void;
+    /** Synchronous `process.once("exit")` registration. */
+    onExit(handler: () => void): void;
+    exit(code: number): void;
+    /** One line of approved user-facing copy (spec §8). */
+    print(line: string): void;
+    log: ServiceLog;
+}
+/**
+ * The daemon's run mode (spec §4.1.1). Order, each step gated on the last:
+ *   1. loadConfig (+ daemon args, bind check);
+ *   2. canonical-UUID check of identity_id (it becomes a path);
+ *   3. B1 per-identity lock at ~/.securecoms/locks/<identity_id>.lock;
+ *   4. resolveToken (it can WRITE the token file, so only after the lock);
+ *   5. B2 pre-bind of daemon.port: a bare net server that destroys every
+ *      connection, so a taken port refuses before the store opens or any
+ *      call to SecureComs is made;
+ *   6. new BridgeAgent (opens the SQLite MLS store);
+ *   7. startThenServe, then hand the pre-bound handle to the HTTP server.
+ * The lock is released only after agent.close() settles (audit H-2): in the
+ * close().finally, in the hard-exit fallback, and in a synchronous exit
+ * backstop. Never at shutdown() entry: a second copy must not open the MLS
+ * store while this one is still draining it.
+ */
+export declare function runMode(deps: RunModeDeps): Promise<void>;