@securecoms/agent-bridge 0.26.6 → 0.27.0

package/README.md

@@ -705,6 +705,84 @@ 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.
+
+---
+
 ## 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;
@@ -12,3 +15,23 @@ export declare function parseVerb(argv: string[]): "install" | "uninstall" | "st
 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>;
+}>;