@securecoms/agent-bridge 0.26.6 → 0.28.0

package/README.md

@@ -705,6 +705,125 @@ including its key). Each proxied call is metered server-side
 
 ---
 
+## Markdown notes (0.27.0)
+
+SecureComs-runtime agents keep short notes of what the owner asks them to
+remember, in the owner's private chat only. The runtime saves a note with the
+`memory_note` tool, and the bridge stores only a quote of the owner's own
+current message. Each note is sealed per row in `bridge-state.db` (schema
+v10) and is delivered only to the runtime's `/v1/ws` socket, never to a
+harness, HTTP, SSE, a room, another chat or the voice fast path.
+
+**Compatibility.**
+
+- Install `@securecoms/agent-runtime` 0.10.0 together with the bridge and
+  restart both (`launchctl bootout` then `bootstrap`, never `kickstart`). The
+  bridge moves legacy owner-DM facts into notes, and reports
+  `memory_notes: true`, only after a runtime whose hello declares
+  `memory_notes` has connected in that bridge process. A 0.9.x runtime's
+  hello does not, so a 0.27 bridge with a 0.9.x runtime keeps today's facts
+  and recall, but it 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 harness socket still never receives notes and never turns on the import
+  or the report, so naming the provider is defence in depth. 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 installing.
+- A `/v1/ws` consumer that sends no hello waits about 2 seconds for its first
+  delivery.
+- Notes are off in a freshly started bridge until a runtime-config refetch
+  succeeds. A bridge restarted while the backend is unreachable serves no
+  notes and accepts no writes until the backend answers.
+
+**Known limitations.**
+
+- Text the owner pastes counts as the owner's own words, up to the
+  600-unit short-message bound.
+- A quote can drop a condition or a negation ("Never cc X" can be saved as
+  "cc X"). Ask the agent what it saved.
+- Short notes in CJK or Thai (fewer than 2 space-separated tokens) are
+  refused.
+- UUIDs and long letter-and-digit tokens are refused as possible secrets.
+- Forget and clear are logical deletes: sealed bytes can stay in free
+  database pages until they are overwritten, and they still open under the
+  device key.
+- "Clear all notes" does not delete chat history or legacy facts. Legacy facts
+  that did not fit before can become notes after a clear.
+- The voice fast path still sends the last 10 DM messages through the
+  backend proxy.
+
+**Off switches.** There are three. Use the narrowest that fits.
+
+- `memory.provider: "none"` in the credential file, then a daemon restart.
+  This turns notes off, and it also drops the recent history.
+- `SECURECOMS_OWNER_DM_DEFAULT_GRANTS=off` in the bridge service environment.
+  This also drops the owner-DM tools, not only `memory_note`.
+- `SECURECOMS_TOOL_DENY=memory_note` removes only the note tool.
+
+**Log events.** All are content-free: counts and classes only, never note text.
+`memory.note_written` (`op`, `notes_count`, `doc_chars`),
+`memory.note_refused` (`reason_class`), `memory.notes_cache_miss`,
+`memory.note_open_failed`, `memory.import_partial` (`remaining`),
+`memory.config_unrecognized`, `memory.clear_generation_regressed`,
+`memory.clear_failed`, `memory.applied_generation_out_of_range`,
+`memory.notes_fill_failed`, `memory.import_failed`,
+`memory.note_write_failed` (error class only), and `ws.hello_timeout` (no
+fields: a `/v1/ws` socket sent no hello and delivery opened after the wait).
+
+**Upgrade order.** Upgrade and restart the bridge 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.** A 0.26.x bridge leaves the notes sealed on disk and reads
+neither the notes nor the legacy facts already moved into them, until it is
+upgraded again; the same holds for a 0.9.x runtime. Roll back the runtime and
+the bridge together, and restart both: the bridge decides once per process
+that a notes-reading runtime is present.
+
+## Semantic memory: model download and retention
+
+<!-- [COPY, NEW] the three paragraphs below, the log-line paragraph included (7b Task 19, spec §19 LOW; first sentence corrected in the 7b-2 final-review fix round). Gate: Eric sign-off before npm publish (release PR). -->
+
+Semantic memory downloads its model from downloads.securecoms.ai when the owner first messages the agent in their private chat after semantic memory is turned on, not when the setting is saved. 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>`.
+
+If you change the memory provider or turn off owner-DM defaults, semantic memory rows stay on the machine until their retention ends, but they are never used.
+
+The bridge logs `memory.model_download_enabled` (no fields) once per process
+when semantic memory is turned on with `model_source` `download`.
+
+<!-- [COPY, NEW] (7b Task 19 fix round 2). Gate: Eric sign-off before npm publish (release PR). -->
+
+If you embed the bridge as a library (`new BridgeAgent(cfg, deps)`), semantic recall stays inert unless you pass `hostMachine: true`: no model is downloaded or loaded, and no call heartbeat is written. The `agent-bridge` command passes it for you.
+
+---
+
+## Release notes: 0.28.0
+
+0.28.0 adds semantic memory in the owner's private chat. Install it together
+with `@securecoms/agent-runtime` 0.11.0 and restart both.
+
+- **Semantic memory.** The agent recalls sealed memory rows in the owner's
+  private chat only. See "Semantic memory: model download and retention"
+  above for the model download, retention and library-embedding paragraphs.
+- **Off switches.** The three switches under "Markdown notes (0.27.0)" apply
+  unchanged: `memory.provider: "none"`, `SECURECOMS_OWNER_DM_DEFAULT_GRANTS=off`,
+  and (notes only) `SECURECOMS_TOOL_DENY=memory_note`.
+- **`import_only`.** Set `memory.model_source` to `import_only` on a machine
+  that must make no model download.
+- **`models import`.** `agent-bridge models import <dir>` copies a model bundle
+  in for `import_only` machines. <!-- [COPY, NEW] the one-line CLI confirmation "imported <names>" printed by `models import` (src/bin.ts). Gate: Eric sign-off before npm publish (release PR). -->
+
+## Test commands
+
+```
+npx vitest run && npx tsc --noEmit -p .
+```
+
+The suite runs with a temporary HOME (`test-support/tmp-home.global-setup.ts`), so no test writes under your real `~/.securecoms`.
+
+---
+
 ## Flags and environment
 
 | Flag | Env var | Default | Description |

package/dist/bin.d.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { BridgeAgent } from "./bridge-agent.js";
+import { createHttpServer } from "./http-server.js";
+import { attachAgentWebSocket } from "./ws-server.js";
 import { type ResolveNodeDeps } from "./service/resolve-node.js";
 import { type Harness } from "./service/wire.js";
 export declare function nodeMajorOk(version: string): boolean;
@@ -8,7 +11,27 @@ 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" | null;
+export declare function parseVerb(argv: string[]): "install" | "uninstall" | "status" | "wire" | "unwire" | "models" | null;
 export declare function slugFromCredentialPath(credentialPath: string): string;
 export declare function chooseInstallExecPath(runningExecPath: string, override: string | undefined, deps: ResolveNodeDeps): string;
 export declare function realCopyConnector(srcDir: string, dstDir: string, harness: Harness): void;
+/**
+ * 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
+ * while the machine was offline) and warms the restored turns before it
+ * resolves, so no route or socket exists while a stale note could be served.
+ * main() can listen only on the server this returns. `readTls` runs after
+ * start(), as the inline read did.
+ */
+export declare function startThenServe(agent: BridgeAgent, opts: {
+    token: string;
+    allowOrigins: string[];
+    readTls: () => {
+        cert: string;
+        key: string;
+    } | undefined;
+}): Promise<{
+    server: ReturnType<typeof createHttpServer>["server"];
+    closeAllSseStreams: () => void;
+    agentWs: ReturnType<typeof attachAgentWebSocket>;
+}>;