@securecoms/agent-bridge 0.27.0 → 0.28.0

package/dist/bridge-agent.d.ts

@@ -33,6 +33,8 @@ import { type OwnerAuthorityStore, type OwnerPin } from "@agentvault/connect-cli
 import type { BridgeConfig } from "./config.js";
 import { LatencyRecorder } from "./latency.js";
 import type { AttachmentMeta, VaultRefEntry } from "./attachments.js";
+import { type Embedder } from "./memory/embedder/client.js";
+import { type RecallItem, type RecallTapCapture } from "./memory/recall/recall-book.js";
 import { type MemoryNoteResultFrame } from "./memory/note-frames.js";
 import { type ChatMessage } from "./voice/fast-prompt.js";
 import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
@@ -154,6 +156,12 @@ export interface MemoryNoteContext {
     token: number | undefined;
     /** Per-socket request ids still being decided (M-2). At most MAX_PENDING_NOTE_REQUESTS (review m-3). */
     pendingRequests: Set<string>;
+    /**
+     * 7b spec §9.1 (H5): the recall ids shown with THIS socket's delivery of `messageId` that carries
+     * `token`, else undefined. Task 18 fix round 1 (M2): the caller passes `ctx.token`, the token captured
+     * when the frame ARRIVED, never the token read after an await.
+     */
+    shownRecall(messageId: string, token: number | undefined): ReadonlySet<number> | undefined;
 }
 /** Review m-3: pending memory_note requests per socket; a frame beyond this refuses `invalid` with no echo. */
 export declare const MAX_PENDING_NOTE_REQUESTS = 8;
@@ -314,6 +322,26 @@ export interface BridgeAgentDeps {
      * it undefined and gets homedir().
      */
     home?: string;
+    /**
+     * 7b Task 15: the embedder. Tests inject a fake. Undefined in the production construction (`hostMachine`, no
+     * `home`) builds the real EmbedderClient; undefined anywhere else gets INERT_EMBEDDER, so no test reaches a real one
+     * (Task 19 fix M2: a test that injects neither no longer builds a real client on the developer's homedir()).
+     */
+    embedder?: Embedder;
+    /**
+     * 7b Task 19 fix M2: true only in the production construction (bin.ts). This agent owns machine-level state under
+     * homedir(): the call heartbeat (~/.securecoms/run/voice-call), the model marker and GC (~/.securecoms/models) and
+     * the one-second maintenance timer that drives them. A test that injects `home` gets the same, under its temp home.
+     * A construction with neither (most direct test constructions) touches none of those paths.
+     *
+     * Library callers: omit it and semantic recall stays inert (INERT_EMBEDDER: the report says `preparing` or
+     * `off`, no model is downloaded or loaded, no call heartbeat is written and other bridges' background work is
+     * never paused by this one). Pass `true` only for the one process per agent that should own those paths, as
+     * bin.ts does. host-machine.arch.test.ts pins bin.ts as the only production construction.
+     */
+    hostMachine?: boolean;
+    /** 7b Task 15 (E1 delta M5): injected platform, default process.platform. */
+    platform?: NodeJS.Platform;
     /** Injectable so tests can assert recorded stages; defaults to a fresh one. */
     latency?: LatencyRecorder;
     /**
@@ -1126,6 +1154,57 @@ export declare class BridgeAgent {
     /** The ONE follow-up cycle every trigger during the in-flight cycle shares. */
     private ingestFollowUp;
     private runtimeConfigTimer?;
+    /** Semantic memory 7b (spec §5.4, audit r2 H-A): the hourly left-channel purge. */
+    private membershipSweepTimer?;
+    /** 7b Task 15 (spec §5.3): the hourly recall prune, modelled on the membership sweep. */
+    private recallPruneTimer?;
+    private recallPruneWork;
+    private readonly platform;
+    private readonly embedder;
+    /** 7b Task 16: the recall index (the single writer, I8: reached only from tapRecall). */
+    private readonly recall;
+    /** 7b Task 19 (spec §8, H1, ruling P-1): this identity's call heartbeat, and every identity's for the pause. */
+    private readonly heartbeat;
+    /** 7b Task 19 (spec §8): lazy re-embed of pending rows (never an insert; I8 untouched). */
+    private readonly reembed;
+    /** 7b Task 19: the one-second maintenance timer (heartbeat refresh, re-embed, daily marker and GC). */
+    private recallMaintenanceTimer?;
+    private recallMaintenanceWork;
+    private maintenanceTickN;
+    /** The previous re-embed tick did work: poll again next second instead of waiting for the minute. */
+    private reembedHot;
+    private lastModelUpkeepAt;
+    /** Fix L3: the marker is touched on the first tick with recall on, then daily, independent of the GC cadence. */
+    private lastMarkerTouchAt;
+    /** Fix M2: BridgeAgentDeps.hostMachine, or an injected home (see there). */
+    private readonly machinePaths;
+    /** Spec §19 LOW (Federal pre-flight notice): logged once per process. */
+    private modelDownloadNoticeLogged;
+    /**
+     * 7b Task 16 (spec §4 M1, fix H-1): turns restored from runtime_inbox at
+     * boot AND turns the boot drain ingested before the boot refetch settled;
+     * tapped once by reindexRestoredTurns after it.
+     */
+    private readonly deferredRecallIds;
+    /** 7b fix H-2: recall epochs captured at receipt in the ingest cycle, consumed by stageSealed (cleared at cycle end). */
+    private readonly recallReceipt;
+    /** 7b fix H-2: the persisted receipt epochs of each staged turn (like ingestGeneration; deleted at ack). */
+    private readonly recallStageEpochs;
+    /** 7b Task 16: in-flight fire-and-forget index taps; close() waits for them (bounded). */
+    private readonly recallTapWork;
+    /**
+     * Final-review item 2: conversations whose `audience` skip was already logged in this process. A room (or any
+     * conversation the owner-DM gate refuses) refuses every turn the same way, so the line is written once per
+     * conversation per process, not once per inbound message. Bounded: cleared when it reaches 4096 entries.
+     */
+    private readonly recallAudienceLogged;
+    /** Off until a payload arrives (spec §5.3: before the first payload of a process, recall neither indexes nor reads nor purges). */
+    private recallConfig;
+    /** The membership sweep now running, if any; close() waits for it (bounded). */
+    private membershipSweepWork;
+    /** Task 13 fix round LOW 3: when each channel last delivered an inbound row to this process. */
+    private readonly lastInboundAt;
+    private readonly membershipSweeper;
     private readonly listeners;
     private startedAt;
     private readonly store;
@@ -1173,6 +1252,8 @@ export declare class BridgeAgent {
      * closes the socket but is not a downgrade.
      */
     private notesConsumerSeen;
+    /** 7b spec §7.2 Q4: a runtime socket (no harness claim) declared memory_recall at least once in this process (Task 19 reports it). */
+    private recallConsumerSeen;
     /** Review M-1: the refetch now running, and the ONE follow-up every caller during it shares. */
     private refetchInFlight;
     private refetchFollowUp;
@@ -1812,6 +1893,17 @@ export declare class BridgeAgent {
      * A timeout rejects with the SDK's `FetchDeadlineError`.
      */
     private fetchBounded;
+    /** H-A rule 4 (audit r1 C2): GET /api/v1/channels/{id}; only 404 is "gone" (404, not 403, for non-members). */
+    private probeChannelMembership;
+    /** §5.4: one conversation's turns, facts, notes and recall, inside the memory mutex, with every in-memory copy. */
+    private purgeConversation;
+    /**
+     * 7b Task 17: the purged conversation's recall cache and pending map
+     * entries go too, inside the memory mutex. The purge already moved the
+     * purge and content epochs inside its transaction, so `warm` and
+     * `deliverable` refuse even before this drop runs (M-A3, M-A4).
+     */
+    private onConversationPurged;
     /** M6 (Task 11): idempotent get-or-create resolve of the enclave's hidden
      *  vault channel id — used as the fallback when a caller omits
      *  vaultChannelId. Mirrors connect-web's filesafe-api.ts resolveVaultChannel
@@ -1875,6 +1967,7 @@ export declare class BridgeAgent {
     recordMemory(input: import("@agentvault/connect-mls-store").MemoryRecordInput): Promise<{
         seq: number;
         deduped: boolean;
+        dropped?: true;
     }>;
     /**
      * OpenClaw collapses text history and workspace facts into the owner's
@@ -1906,6 +1999,82 @@ export declare class BridgeAgent {
      * this point keeps the last applied state.
      */
     private applyPayloadMemory;
+    /** Spec §5.3 (H3): mode state lives in the store; level-triggered after every refetch. Never throws. */
+    private applyRecallModeFromPayload;
+    /** A retention change or a prune removed rows: drop the vector caches. Called only inside notes.exclusive. */
+    private onRecallRetentionChangedLocked;
+    /** Markdown mode deleted every row: drop the caches and the per-message map. Called only inside notes.exclusive. */
+    private onRecallPurgedAllLocked;
+    /**
+     * 7b spec §7.1, §7.2: Q1 (config half) and Q2 here, then the 150 ms bound
+     * inside RecallBook.prepare. Called beside prepareNotesForTurn, before the
+     * turn is staged. The receipt epochs (Task 16 fix H-2) narrow the capture:
+     * the in-cycle receipt, else the persisted staging marks; marks that exist
+     * but lack an epoch give no recall (fail closed). Never throws.
+     */
+    private prepareRecallForTurn;
+    /** ws flush (synchronous). Q1 to Q3 and Q6 again at delivery, on the ORIGINAL message; Q4 lives in withConsumerRecall. */
+    recallForDelivery(m: BridgeMessage): readonly RecallItem[] | undefined;
+    /** ws-server: a runtime socket with no harness claim declared memory_recall. */
+    noteRecallConsumer(): void;
+    /** @internal test seam */
+    recallWarm(c: string): Promise<void>;
+    /** @internal test seam */
+    recallCacheWarm(c: string): boolean;
+    /** @internal test seam */
+    recallDeliverable(id: string, c: string): readonly RecallItem[] | undefined;
+    /** I1 and Q1's config half (spec §4, §7.2): provider, payload semantic, kill switch, store enabled. */
+    private recallProviderOn;
+    /**
+     * Spec §4: the tap's capture, synchronous, taken before the tap's first
+     * await (fact 5: the ingest stamp is deleted at ack). The purge and mode
+     * epochs are the ones persisted at staging, captured at RECEIPT (Task 14,
+     * audit r2 M-A; fix H-2), so a purge or a mode change after receipt, even
+     * across a restart, refuses the insert. A missing value is -1, which no
+     * real epoch equals: the tap skips it (`purged` / `epoch`), fail closed.
+     */
+    captureRecallTap(messageId: string, channelId: string): RecallTapCapture;
+    /** One content-free skip line (reason class only). */
+    private logRecallSkip;
+    /**
+     * The single writer (I8). Gates I1 to I5 here, in spec §4 table order; I6
+     * (capture half) here, and I6, I7, M-A and I9 again inside the store
+     * transaction. A skip logs only its reason class. Never throws.
+     */
+    private tapRecall;
+    /** Fire-and-forget tap from the ingest cycle; tracked so close() and tests can wait for it. */
+    private spawnRecallTap;
+    /** @internal test seam: resolves once every in-flight ingest tap has settled. */
+    settleRecallTaps(): Promise<void>;
+    /**
+     * Spec §4 M1: after the boot refetch settles, tap the deferred turns: those
+     * restored from runtime_inbox (a crash between staging and the tap) and
+     * those the boot drain ingested before the recall config was known (fix
+     * H-1). I9 absorbs a first run that committed. The authorization is the
+     * frozen mark; I1 is re-read here; the capture carries the persisted
+     * receipt epochs (fix H-2). A turn no longer held logs `stamp_missing`.
+     */
+    private reindexRestoredTurns;
+    /**
+     * Spec §5.3 hourly prune; audit r1 H5: inside the memory mutex, and a prune
+     * that deleted rows drops the vector caches. Never throws.
+     * @internal test seam
+     */
+    runRecallPruneTick(): Promise<void>;
+    /**
+     * 7b Task 19, the one-second maintenance tick minus the heartbeat refresh (the timer does that). Never throws.
+     * - Once a day (and on the first tick): touch this identity's model marker while recall is on and the files are
+     *   on disk, then GC model trees this manifest does not name and no marker has used for 30 days (spec §6.4 item 6).
+     * - Re-embed (spec §8) while recall is on: every minute, and every second while the previous tick did work.
+     * @internal test seam
+     */
+    runRecallMaintenanceTick(n: number): Promise<void>;
+    /**
+     * Spec §9.2 (Task 19): capability versus state, plus the H6 hold count and the newest completed sweep time
+     * (Task 13 carry). Pure reads: never starts, connects or spawns the embedder (plan audit r1 LOW).
+     */
+    private reportedRecall;
+    private reportedRecallState;
     /**
      * Review M-5: the report key only for a value the backend accepts
      * (0..MAX_CLEAR_GENERATION); otherwise the key is omitted, so one bad
@@ -2475,7 +2644,12 @@ export declare class BridgeAgent {
      * which Date.parse would read as LOCAL time, so a bare timestamp is UTC.
      */
     private recordRecvLag;
+    /**
+     * 7b Task 16 carry: the cycle's receipt epochs are dropped in a `finally`,
+     * so a cycle that throws leaves no stale entry for a later staging to read.
+     */
     private ingestCycle;
+    private ingestCycleBody;
     drain(channelId: string | undefined, waitSeconds: number): Promise<BridgeMessage[]>;
     /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
     subscribe(listener: () => void): () => void;
@@ -2588,7 +2762,12 @@ export declare class BridgeAgent {
     isRuntimeMessageRetired(messageId: string): boolean;
     /** Complete the durable handoff only after the runtime explicitly acks. */
     ackRuntimeMessages(messageIds: string[]): void;
-    /** The sealed runtime_inbox payload: the message plus its ingest stamp (never on the message object). */
+    /**
+     * The sealed runtime_inbox payload: the message plus its ingest stamp and receipt recall epochs (never on the message object).
+     * Task 18 fix round 1: any bridge-private key already on the message is stripped first (the same splitStagedKeys), so
+     * only the bridge's own marks are persisted. A message whose W9 budget is durably spent (agent_memory_w9_spent: an ack
+     * then a backend redelivery) is staged with W9_KEY = W9_MAX, so the budget stays spent.
+     */
     private stagedPayload;
     /**
      * Seal `message` into runtime_inbox with the current ingest stamp and record
@@ -2601,6 +2780,8 @@ export declare class BridgeAgent {
      * valid stamp gets none, so its write refuses `cleared`.
      */
     private stageSealed;
+    /** In-memory mirror of the persisted marks (staging and restore). */
+    private applyStagedMarks;
     private restoreRuntimeInbox;
     /**
      * Seal a runtime frame before the backend queue id may be acknowledged.

package/dist/config.d.ts

@@ -38,6 +38,13 @@ export interface BridgeConfig {
      * a backend voice-settings refetch replaces `voice` wholesale.
      */
     voiceFastPathMode?: FastPathMode;
+    /**
+     * Spec §6.6 (M6): credential `memory.model_source`. "import_only" stops every model
+     * network connection; files arrive only through `models import <dir>`. Local only:
+     * the backend cannot set it (it never writes the credential). Anything but the exact
+     * string "import_only" is "download".
+     */
+    modelSource: "download" | "import_only";
 }
 export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 export declare function loadConfig(opts: {

package/dist/embedder-manifest.json

@@ -0,0 +1,52 @@
+{
+  "manifest": {
+    "modelId": "minilm-l6-v2-int8",
+    "dims": 384,
+    "maxTokens": 256,
+    "pooling": "mean",
+    "normalize": true,
+    "similarityThreshold": 0.19,
+    "onnxInputs": [
+      "input_ids",
+      "attention_mask",
+      "token_type_ids"
+    ],
+    "onnxOutput": "last_hidden_state",
+    "wasmSha256": "ec8580a9d7b9476ceee52e10a7f94124e4dc71a019d666ed6d4726697c109a4d",
+    "wasmSize": 13961845,
+    "files": [
+      {
+        "name": "model.onnx",
+        "urlPath": "/models/embeddings/minilm-l6-v2-int8/afdb6f1a0e45b715d0bb9b11772f032c399babd23bfc31fed1c170afc848bdb1/model.onnx",
+        "sha256": "afdb6f1a0e45b715d0bb9b11772f032c399babd23bfc31fed1c170afc848bdb1",
+        "size": 22972370
+      },
+      {
+        "name": "vocab.txt",
+        "urlPath": "/models/embeddings/minilm-l6-v2-int8/07eced375cec144d27c900241f3e339478dec958f92fddbc551f295c992038a3/vocab.txt",
+        "sha256": "07eced375cec144d27c900241f3e339478dec958f92fddbc551f295c992038a3",
+        "size": 231508
+      },
+      {
+        "name": "LICENSE",
+        "urlPath": "/models/embeddings/minilm-l6-v2-int8/d83f8f68a86e308e30d1ddf3d1b9984500f0c39ab8a1c7d274ab2799c21155b4/LICENSE",
+        "sha256": "d83f8f68a86e308e30d1ddf3d1b9984500f0c39ab8a1c7d274ab2799c21155b4",
+        "size": 9934
+      },
+      {
+        "name": "NOTICE",
+        "urlPath": "/models/embeddings/minilm-l6-v2-int8/99446995c7800bd9ce033f24c477b00daa50f06da85e441e903f4ce1e32c7507/NOTICE",
+        "sha256": "99446995c7800bd9ce033f24c477b00daa50f06da85e441e903f4ce1e32c7507",
+        "size": 320
+      }
+    ]
+  },
+  "tokenizer": {
+    "lowercase": true,
+    "stripAccents": true,
+    "unkToken": "[UNK]",
+    "unknownDropped": false,
+    "addSpecialTokens": true,
+    "maxInputCharsPerWord": 100
+  }
+}