@securecoms/agent-bridge 0.26.6 → 0.28.0

package/dist/memory/recall/recall-book.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Semantic memory 7b: the bridge's recall index and read path (spec §4, §7).
+ * Runs every mutation inside the NotesBook mutex (`exclusive`), which is the
+ * per-identity memory mutex. Embedding and sealing happen OUTSIDE it (M2).
+ *
+ * I8: `index` is reached only from BridgeAgent.tapRecall (the ingest tap and
+ * the restore re-run). recall-single-writer.arch.test.ts pins that.
+ */
+import type { RecallCapture, RecallRow, RuntimeInboxRewrite, SqliteMlsStateStore } from "@agentvault/connect-mls-store";
+import { type ServiceLog } from "../../service-log.js";
+import type { Embedder } from "../embedder/client.js";
+export type IndexSkip = "mode" | "audience" | "voice" | "length" | "secret" | "stamp_missing" | "cleared" | "epoch" | "purged" | "duplicate" | "store";
+export interface RecallTapCapture {
+    readonly generation: number | undefined;
+    readonly capture: RecallCapture;
+}
+export interface RecallItem {
+    readonly id: number;
+    readonly text: string;
+    readonly sent_at: number;
+}
+export type RecallStore = Pick<SqliteMlsStateStore, "recallState" | "recallCapture" | "sealRecallText" | "sealRecallVec" | "insertRecall" | "readRecallRows" | "readRecallRow" | "openRecallText" | "openRecallVec" | "updateRecallVec" | "listPendingRecall" | "deleteRecall" | "recentMemoryMessageIds">;
+export declare class RecallBook {
+    private readonly d;
+    constructor(d: {
+        store: RecallStore;
+        embedder: Embedder;
+        exclusive: <T>(fn: () => Promise<T>) => Promise<T>;
+        modelId: string;
+        threshold: number;
+        now?: () => number;
+        log?: ServiceLog;
+    });
+    /**
+     * Spec §4 order: (1) seal and embed outside the mutex; (2) take the mutex;
+     * (3) one transaction (insertRecall) that re-checks I6, I7 and M-A, then I9.
+     * A seal failure inserts nothing (fail closed, §5.2). An embedder failure
+     * inserts a pending row (sealed_vec NULL) for the re-embed (§8).
+     */
+    index(i: {
+        conversationId: string;
+        messageId: string;
+        text: string;
+        sentAt: number;
+        capture: RecallCapture;
+    }): Promise<{
+        ok: true;
+        recallId: number;
+    } | {
+        ok: false;
+        reason: IndexSkip;
+    }>;
+    private static readonly MAP_MAX;
+    private static readonly IDLE_MS;
+    private static readonly TOP_K;
+    private static readonly TEXT_MAX_CHARS;
+    private static readonly QUERY_TIMEOUT_MS;
+    private readonly caches;
+    private readonly entries;
+    private readonly warming;
+    private same;
+    private nowMs;
+    cacheWarm(conversationId: string): boolean;
+    /**
+     * §7.3 (H2): snapshot first, open outside the mutex, install under it. Never on a turn's path. Never rejects:
+     * a read failure leaves the cache cold (fail closed: no recall).
+     *
+     * Final-review item 1 (HIGH): prepare() starts this warm on a cold cache and the same turn's tap inserts while
+     * the vectors are still opening. At the row cap that insert count-prunes and moves the content epoch, so the old
+     * "install only if all four epochs are unchanged" rule never installed, and the next turn repeated the race
+     * forever; below the cap the new row was missing from the installed cache. So at install, under the mutex, the
+     * rows and the capture are re-read synchronously:
+     *   - the clear generation, the mode epoch and the purge epoch must equal the snapshot's, else NOTHING installs
+     *     (a clear, a mode change or a purge during the warm always wins);
+     *   - the content epoch may differ (an insert, a prune, a forget or a re-embed): the cache is reconciled to the
+     *     re-read rows (ids gone are dropped, the few new ids are opened here, under the mutex) and installed with the
+     *     re-read capture.
+     */
+    warm(conversationId: string): Promise<void>;
+    /**
+     * §7.1: compute at ingest. Snapshot the capture FIRST (H2); `receipt`
+     * replaces its purge and mode epochs with the ones captured when the turn
+     * was received (Task 16 fix H-2), so a purge or a mode change after receipt
+     * refuses too. 150 ms bound on the query embed; a cold cache starts a warm
+     * and gives nothing.
+     */
+    prepare(p: {
+        messageId: string;
+        conversationId: string;
+        query: string;
+        excludeIds: ReadonlySet<string>;
+        timeoutMs?: number;
+        receipt?: {
+            purgeEpoch: number;
+            modeEpoch: number;
+        };
+    }): Promise<void>;
+    /** Q3 + Q6: the entry's own conversation, and its capture still current at delivery. Synchronous (ws flush). */
+    deliverable(messageId: string, conversationId: string): readonly RecallItem[] | undefined;
+    /**
+     * Spec §9.1 (H5, W9): delete one recall row and spend this message's destructive operation, in ONE store
+     * transaction (`deleteRecall` with the prepared rewrite). The caller has already checked that the id was
+     * shown with this delivery. `precommit` is the caller's last check (W1, W2), run inside the mutex with no
+     * await before the synchronous delete; a non-null veto deletes nothing.
+     *
+     * A forget is a delete, never an insert: I8 (single writer of insertRecall) is untouched.
+     * The delete moves the content epoch (audit r1 H5). The vector cache is dropped. A pending map entry that
+     * matched the capture just before the delete keeps its other items and adopts the new capture (the delete
+     * is the only change between the two reads, both inside the mutex with no await between them).
+     */
+    forget(conversationId: string, recallId: number, rewrite: RuntimeInboxRewrite, precommit?: () => "message" | "mode" | null): Promise<"ok" | "unknown_id" | "budget" | "message" | "mode">;
+    /**
+     * Spec §8 (Task 19): a pending row just took its vector (`updateRecallVec`, which moves no epoch). A warm cache
+     * whose capture is still current gains the row, so an active conversation's cache (kept warm by use) does not
+     * hide re-embedded rows until it idles out. A stale cache is dropped. Called inside `exclusive`.
+     */
+    onReembeddedLocked(conversationId: string, row: RecallRow, vec: Float32Array): void;
+    /** Spec §7.1: removed at ack, nack or retire. */
+    drop(messageId: string): void;
+    /** §5.4: one conversation's cache and its pending map entries. Called inside `exclusive`. */
+    dropConversationLocked(conversationId: string): void;
+    /** A retention change or a prune can remove rows: drop every vector cache. Called inside `exclusive`. */
+    dropAllCachesLocked(): void;
+    /** A clear or markdown mode: drop every cache and every map entry. Called inside `exclusive`. */
+    dropAllLocked(): void;
+    /** §7.3: a cache idle for 30 minutes is dropped. */
+    dropIdleCaches(now: number): void;
+    /**
+     * Task 17 fix round 1 (HIGH): at the row cap every insert count-prunes, so without this every pending map
+     * entry of the conversation went stale at the next insert and recall stopped. An entry is rebased only when
+     * its capture equals the exact pre-insert capture (clear generation, mode and purge epochs equal; the content
+     * epoch moved by this one insert alone) and none of its items was pruned. Anything else stays stale.
+     */
+    private rebaseEntriesLocked;
+    /** Spec §7.3 and audit r1 H7: an insert APPENDS its vector to a warm, current cache, inside the mutex. */
+    protected onInsertedLocked(conversationId: string, row: RecallRow, vec: Float32Array | null, r: {
+        pruned: readonly number[];
+        capture: RecallCapture;
+    }): void;
+}

package/dist/memory/recall/reembed.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Spec §8: lazy re-embed. Rows whose model_id is NULL (pending) or another model's are embedded again by background
+ * jobs: open the text, a priority-1 embedder job, seal under the new vector AAD, then inside the memory mutex a
+ * compare-and-set on the old model_id. One row per job, at most 16 rows per tick (the bridge ticks once a second;
+ * the shared embedder enforces 16 per second per machine, §20 E1.4). Paused while any call heartbeat of this OS user
+ * is fresh (H1, B-20).
+ *
+ * The capture is read BEFORE the row is re-read, opened and embedded, and the write re-checks it inside its
+ * transaction (`updateRecallVec`), bound to the recall id read (Task 18 carry M-4). A clear, a mode change or a purge
+ * that lands during the embed refuses the write; a row forgotten, pruned or purged takes no vector.
+ *
+ * Never an insert: the single-writer rule (I8) is untouched. Embedding and sealing happen outside the mutex (M2).
+ */
+import type { RecallRow, SqliteMlsStateStore } from "@agentvault/connect-mls-store";
+import type { Embedder } from "../embedder/client.js";
+export type ReembedStore = Pick<SqliteMlsStateStore, "recallCapture" | "listPendingRecall" | "readRecallRow" | "openRecallText" | "sealRecallVec" | "updateRecallVec">;
+export declare class ReembedQueue {
+    private readonly d;
+    constructor(d: {
+        store: ReembedStore;
+        embedder: Embedder;
+        exclusive: <T>(fn: () => Promise<T>) => Promise<T>;
+        modelId: string;
+        paused: () => boolean;
+        now?: () => number;
+        /** Inside the mutex, after a successful write: the bridge appends the vector to a warm, current cache. */
+        onEmbeddedLocked?: (conversationId: string, row: RecallRow, vec: Float32Array) => void;
+        embedTimeoutMs?: number;
+    });
+    private running;
+    private readonly parked;
+    /** Rows embedded and written by this call (0 when paused, not ready, already running or nothing pending). */
+    tick(): Promise<number>;
+    private tickOnce;
+}

package/dist/memory/secret-scan.d.ts

@@ -0,0 +1,5 @@
+/** The `_suspect` port with skip_long_token false. Same order, same 20-character floor. */
+export declare function suspectWholeField(v: string): string | null;
+export declare function scanNote(input: string): string | null;
+/** Test-only: expand the fixture placeholders (the Python twin is `expand`). */
+export declare function expandFixture(text: string): string;

package/dist/memory-taps.d.ts

@@ -3,6 +3,7 @@ interface MemorySink {
     record(input: MemoryRecordInput): Promise<{
         seq: number;
         deduped: boolean;
+        dropped?: true;
     }>;
 }
 /** Record an inbound (peer) text turn the agent actually consumed. Best-effort:
@@ -11,8 +12,8 @@ interface MemorySink {
  *  `modality` defaults to "text"; Task 4 (voice-mode carrier) passes "voice"
  *  for a turn whose InboxEntry had the server-set `voiceMode` flag, so memory
  *  continuity reflects how the turn actually arrived. */
-export declare function recordInboundMemory(sink: MemorySink, channelId: string, senderId: string, text: string, messageId: string, modality?: "text" | "voice"): Promise<void>;
+export declare function recordInboundMemory(sink: MemorySink, channelId: string, senderId: string, text: string, messageId: string, modality?: "text" | "voice", expectPurgeEpoch?: number): Promise<void>;
 /** Record the agent's own outbound reply. Best-effort. `modality` is "voice"
  *  for a line the voice fast path spoke (H1), else "text". */
-export declare function recordOutboundMemory(sink: MemorySink, channelId: string, text: string, messageId: string, modality?: "text" | "voice"): Promise<void>;
+export declare function recordOutboundMemory(sink: MemorySink, channelId: string, text: string, messageId: string, modality?: "text" | "voice", expectPurgeEpoch?: number): Promise<void>;
 export {};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.26.6";
+export declare const BRIDGE_VERSION = "0.28.0";

package/dist/voice/fast-prompt.d.ts

@@ -38,6 +38,8 @@ export declare const FAST_FACTS_CHARS_CAP = 2000;
  */
 export declare const FAST_DEFER_RULE: string;
 export declare function isRefusal(reply: string): boolean;
+/** Spec §15 item 7 (OQ-M, Eric approved): the same line with or without notes, so it tells the proxy nothing. */
+export declare const FAST_NOTES_DEFER_LINE = "If the answer may depend on something the owner asked you to remember, defer.";
 export declare function buildFastMessages(args: {
     persona: VoicePersona;
     guidance: string;
@@ -61,6 +63,9 @@ export declare function buildFastMessages(args: {
     /** The agent's identity display name ("one name", 2026-10-01): the only
      *  source of the prompt's "You are <name>." line. */
     agentName?: string;
+    /** Spec §15 item 7: append the fixed notes-defer line. The caller sets it
+     *  from provider and DM-ness only, never from whether notes exist. */
+    notesDeferLine?: boolean;
 }): ChatMessage[];
 /** The fast model appends this when the full agent must answer next. */
 export declare const DEFER_TOKEN = "[[DEFER]]";

package/dist/ws-server.d.ts

@@ -9,6 +9,11 @@ export interface AgentWebSocketOptions {
     inflightStaleAfterMs?: number;
     /** Test seam: the clock the delivery ages are measured on. */
     now?: () => number;
+    /**
+     * Test seam: how long a socket's deliveries wait for its hello (default
+     * HELLO_WAIT_MS). 0 delivers at once, as before N-H2.
+     */
+    helloWaitMs?: number;
 }
 /**
  * FB-P1-024 / #842 ruling §3: a stale-in-flight OBSERVATION, not a lease.
@@ -21,6 +26,28 @@ export interface AgentWebSocketOptions {
  */
 export declare const INFLIGHT_STALE_SWEEP_MS = 60000;
 export declare const INFLIGHT_STALE_AFTER_MS: number;
-export declare function attachAgentWebSocket(server: HttpServer, agent: BridgeAgent, opts: AgentWebSocketOptions): {
+/**
+ * Audit r2 N-H2 (ruling PR-2): a new socket's deliveries wait for its first
+ * hello, or this long for a consumer that sends none. Without the hold, a
+ * turn buffered before the runtime connected went out in the connection
+ * handler's first flush, before the hello could mark the socket a runtime
+ * consumer, so it never carried its notes.
+ */
+export declare const HELLO_WAIT_MS = 2000;
+/** Spec §8.5: the hello-reply feature that tells the runtime it may offer memory_note on this socket. */
+export declare const MEMORY_NOTES_FEATURE = "memory_notes";
+/** Semantic memory 7b (spec §7.2 Q4): the hello feature a runtime declares to receive `memory.recall`; the bridge echoes it. */
+export declare const MEMORY_RECALL_FEATURE = "memory_recall";
+/**
+ * Every BridgeAgent member this module touches, directly or through the
+ * consumer helpers. The handlers take `WsAgent`, so tsc rejects a call to a
+ * member missing from this list. The ws-server test fakes are passed `as
+ * never` from files tsc does not check, so the fake-coverage tests assert each
+ * fake against this list at run time (7b gate fix: a member added here without
+ * a fake made three tests throw "is not a function").
+ */
+export declare const WS_AGENT_MEMBERS: readonly ["ackRuntimeMessages", "action", "admitRuntimeDelivery", "applyMemoryNote", "clearHarnessReport", "clearPerToolConsumer", "isRuntimeMessageRetired", "noteNotesConsumer", "notePerToolConsumer", "noteRecallConsumer", "noteSessionClose", "noteSessionEvicted", "noteSessionOpen", "notesAppliedGeneration", "notesForDelivery", "recallForDelivery", "recordHarnessReport", "recordRuntimeReply", "reportStatusGated", "requeueFailedRuntimeDeliveries", "requeueFront", "runtimeReplyReceipt", "send", "sendA2A", "subscribe", "takeDeliverable", "wakeListeners"];
+export type WsAgent = Pick<BridgeAgent, (typeof WS_AGENT_MEMBERS)[number]>;
+export declare function attachAgentWebSocket(server: HttpServer, agent: WsAgent, opts: AgentWebSocketOptions): {
     close(): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.26.6",
+  "version": "0.28.0",
   "type": "module",
   "engines": {
     "node": ">=22.5.0"
@@ -58,6 +58,7 @@
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
     "esbuild": "0.24.0",
+    "onnxruntime-web": "1.29.0",
     "typescript": "^5.4.0",
     "vitest": "^3.2.6"
   }