@securecoms/agent-bridge 0.26.6 → 0.27.0

package/dist/bridge-agent.d.ts

@@ -33,6 +33,7 @@ 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 MemoryNoteResultFrame } from "./memory/note-frames.js";
 import { type ChatMessage } from "./voice/fast-prompt.js";
 import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
 import { type VaultListNode, type VaultReadExpectations } from "./vault.js";
@@ -114,7 +115,48 @@ export interface BridgeAuthorization {
      * audience owner_dm or on this mark, nothing else.
      */
     readonly relay_speaker?: "owner";
+    /**
+     * Markdown memory 7a (spec §8.3, OQ-B): true ONLY on authorizationFor's
+     * ownerDirect branch with memoryProvider "securecoms": the channel's pinned
+     * owner (never "anomalous") typed this turn in their DM, the roster is
+     * fresh at the held epoch and group (or the DM is cycle-fresh), and the
+     * owner-DM kill switch is on. Present only when true. An OFFER HINT: the
+     * bridge's W1 to W8 are the gate. Never set on the ownerRelayed branch
+     * (OQ-C, Eric approved 2026-10-06): voice turns read notes, never write,
+     * and never on any turn with a relay speaker claim (review I-1).
+     * NOT a tool grant: it is not, and must never be, in `tool_grants`.
+     * Reaches only the per-tool runtime consumer: withConsumerGrants strips it
+     * for a harness socket and the HTTP/SSE paths (review m-3).
+     */
+    readonly memory_write?: true;
+}
+/**
+ * Spec §8.2: what ws-server tells applyMemoryNote about the socket a
+ * memory_note frame arrived on. Read live: W2 is re-evaluated after awaits.
+ */
+export interface MemoryNoteContext {
+    /**
+     * THIS socket's in-flight record for a message id (the original, never the
+     * consumer copy) and the token of that delivery. A nack, backoff and
+     * redelivery on the same socket reuses the record object but gets a new
+     * token (review m-1).
+     */
+    lookup(messageId: string): {
+        record: BridgeMessage;
+        token: number;
+    } | undefined;
+    /** The socket's own session facts (OQ-J): consumer and the sticky harness claim. */
+    readonly session: {
+        readonly consumer: "runtime" | "unknown";
+        readonly harnessClaimed?: boolean;
+    };
+    /** The delivery token of the frame's message id, captured when the frame arrived; undefined when not in flight. */
+    token: number | undefined;
+    /** Per-socket request ids still being decided (M-2). At most MAX_PENDING_NOTE_REQUESTS (review m-3). */
+    pendingRequests: Set<string>;
 }
+/** 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;
 export interface BridgeMessage {
     channel_id: string;
     message_id: string;
@@ -142,6 +184,27 @@ export interface BridgeMessage {
      * @mention filter reads (not recomputed differently).
      */
     sender_is_agent?: boolean;
+    /**
+     * Audit r2 N-L3 (PR-1): this turn is a voice transcript. W8 never quotes
+     * such a record. Present only when true. Set when either holds:
+     *   - the turn is relay-attributed (`speaker` set). `speaker` is honoured
+     *     only from a sender the server roster marks `is_relay`, so on this path
+     *     the mark does not depend on the body. The room relay's `sendTurn`
+     *     (connect-room-relay/src/turns.ts) also sets `transcribed: true`, and
+     *     the hosted voice worker reaches the bridge only through that relay;
+     *   - the E2E body says `transcribed: true`. The owner's own web client sets
+     *     it on an on-device transcript (connect-web MessagingShell.tsx
+     *     `sendConfirmedVoiceToChannel`, reached from CallPanel's
+     *     `sendAgentMessage` via `confirmedSendBody`).
+     * LIMITATION (spec §15): on the owner-device path the mark is an
+     * UNAUTHENTICATED claim in the body. A modified or legacy client, or a
+     * device added under the owner's identity by a compromised server (the
+     * ADR-0010 gap), can send speech-derived text without it, and the bridge
+     * then treats it as typed. That adds no capability (the sender could type
+     * the same words), so the mark is fail-closed but not a cryptographic
+     * guarantee.
+     */
+    transcribed?: true;
     /**
      * Track 5: materialized attachment metadata for `artifact_share` messages.
      * Each entry corresponds to one downloaded+decrypted file saved to disk.
@@ -1067,6 +1130,56 @@ export declare class BridgeAgent {
     private startedAt;
     private readonly store;
     private readonly memory;
+    /**
+     * Markdown memory 7a: the one owner of every note mutation and of the
+     * delivery cache (spec §6.3, §7.2). One per store, so one per identity.
+     */
+    private readonly notes;
+    /**
+     * Fix round 1 (concern 1): the applied clear generation when each pending
+     * runtime turn was FIRST staged (W7b compares it). Keyed by message id,
+     * persisted inside the sealed runtime_inbox payload and restored with it;
+     * never a BridgeMessage field. Removed when the turn is acked or shed.
+     */
+    private readonly ingestGeneration;
+    /** Spec §11.2 (OQ-L): set by refetchRuntimeConfig (Task 8); notes are on until a payload says otherwise. */
+    private memoryConfig;
+    /**
+     * Task 8 fix round 1 (review I-1, N-L5): set once the BOOT refetch has
+     * returned, on success or failure. Until then prepareNotesForTurn only
+     * fills and never runs the legacy import: the boot drain pulls turns before
+     * the boot refetch, and an import there would move facts into notes that a
+     * clear issued while the machine was offline then deletes for good.
+     * warmRestoredNotes runs the import for the buffered (drained) turns after.
+     */
+    private bootConfigSettled;
+    /**
+     * Final review M-1: false until a config refetch has returned a payload in
+     * THIS process. Until then notes are off for reads and writes
+     * (notesProviderOn), whatever memoryConfig says: the last applied payload
+     * may have turned notes off, and that state is not persisted. Distinct from
+     * bootConfigSettled, which turns true when the boot refetch RETURNED, on
+     * success or failure (settled is not notes-on).
+     */
+    private memoryConfigConfirmed;
+    /**
+     * Final review I-1: true once a /v1/ws consumer completed a hello that
+     * declares it reads notes (MEMORY_NOTES_FEATURE) as the runtime, with no
+     * harness claim on that socket (ws-server). A 0.9.x runtime's hello does not
+     * declare it, a harness socket never qualifies, and a socket that sends no
+     * hello never does. Until then no legacy fact is moved into notes (those
+     * consumers recall facts, never notes) and the report says
+     * memory_notes: false. Per process and never reset: a runtime restart
+     * closes the socket but is not a downgrade.
+     */
+    private notesConsumerSeen;
+    /** Review M-1: the refetch now running, and the ONE follow-up every caller during it shares. */
+    private refetchInFlight;
+    private refetchFollowUp;
+    /** Review M-4: the (payload, applied) pair last logged as regressed. */
+    private regressedLogged;
+    /** Review M-5: an out-of-range applied generation is logged once. */
+    private generationRangeLogged;
     /** Task 2: warn-once-per-channel guard for the enclave-map fallback (below). */
     private enclaveFallbackWarned;
     /** Task 2: dedupe guard so ingestOnce writes a channel's enclave at most once
@@ -1128,6 +1241,7 @@ export declare class BridgeAgent {
      * loose until the next save.
      */
     refetchRuntimeConfig(): Promise<void>;
+    private refetchRuntimeConfigOnce;
     /**
      * Enforce the inbound-buffer cap with a DROP-OLDEST policy.
      *
@@ -1777,6 +1891,101 @@ export declare class BridgeAgent {
      * never falls back to the runtime's retired plaintext JSON files.
      */
     private memoryForTurn;
+    /**
+     * Spec §11.2 (OQ-L), §6.5: apply one parsed `payload.memory`. An unreadable
+     * value turns notes off and deletes nothing. A readable one goes through
+     * NotesBook.clear, which purges only on a HIGHER generation (under the note
+     * mutex) and resyncs on equal or lower; a lower one logs
+     * memory.clear_generation_regressed. Content-free logs only.
+     *
+     * While a purge is pending (the payload is above the applied generation)
+     * notes are held OFF, and they come back on only after the purge committed.
+     * A purge that throws therefore leaves notes off (fail closed); it is
+     * caught here (review M-2) so the rest of the config still applies and
+     * reports, and the next refetch retries it. A refetch that fails before
+     * this point keeps the last applied state.
+     */
+    private applyPayloadMemory;
+    /**
+     * 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
+     * mirror value cannot 422 the whole report, and the event logs once.
+     */
+    private reportedClearGeneration;
+    /**
+     * W1 and R1: the provider is securecoms, a config payload has arrived in
+     * this process (final review M-1), and the parsed payload keeps notes on.
+     */
+    private notesProviderOn;
+    /**
+     * Final review I-1: ws-server calls this when a socket completes a hello as
+     * the runtime (no harness claim) that declares MEMORY_NOTES_FEATURE. The
+     * first one also refetches the runtime config, so the report says
+     * memory_notes: true now rather than at the next 6-hour refetch.
+     */
+    noteNotesConsumer(): void;
+    /**
+     * R2 (spec §7.3): the frozen marks that only the full owner predicate in
+     * authorizationFor sets. `memory_write` (the pinned owner typed this turn)
+     * or `relay_speaker === "owner"` (the pinned owner spoke it through the
+     * relay; read only, never write, OQ-C). Strict `=== true` / `=== "owner"`:
+     * `audience === "owner_dm"` alone is not enough (§0.1 item 7).
+     *
+     * Review I-1 (spec §8.3): the owner-DM kill switch is re-checked HERE, at
+     * read time, and so is the provider (R1). A turn restored from
+     * runtime_inbox carries the marks frozen by the previous process; with
+     * SECURECOMS_OWNER_DM_DEFAULT_GRANTS now off, or the provider no longer
+     * securecoms, it gets no notes, and the boot warm runs no legacy import.
+     */
+    private notesReadable;
+    /** The applied clear generation, for a socket that gets no notes (R5 decided first, review m-2). */
+    notesAppliedGeneration(): number;
+    /**
+     * ws-server flush (synchronous). R1 to R3 here; R5 in withConsumerNotes; R4
+     * holds because nothing else calls this. Reads only the generation-checked
+     * cache (N-M1): a miss gives no notes. `generation` is the applied clear
+     * generation the socket records for W7b.
+     */
+    notesForDelivery(m: BridgeMessage): {
+        notes?: string;
+        generation: number;
+    };
+    /**
+     * §7.2 Warm and §10 import, BEFORE the turn is staged. Never throws.
+     * The import runs only for a `memory_write` turn (M-6: owner-DM channels
+     * only); the turn's own frozen authorization is the proof NotesBook checks.
+     */
+    private prepareNotesForTurn;
+    /**
+     * §7.2 + N-L5: after the boot refetch applied any clear, warm each channel
+     * holding an R2-eligible restored turn, before start() returns (bin.ts
+     * attaches /v1/ws only after start()). `this.buffer` also holds the turns
+     * the boot drain pulled; their prepare ran fill-only (review I-1), so the
+     * legacy import for them runs here, after the purge.
+     */
+    private warmRestoredNotes;
+    /**
+     * Spec §8.2: the write gate for one `memory_note` frame, fail closed, in
+     * table order: W1, well formed (and a request_id not already pending on
+     * this socket, M-2), W2, W3, W4(a), W4(b), W8, W5, then W2 and W1 once more
+     * after the await, then under the note mutex W7, W2 and W1 again after the
+     * seal and right before the synchronous commit, and W7b (the generation
+     * stamped when the turn was first staged, re-checked inside the store
+     * transaction; a turn with no stamp refuses `cleared`). Every refusal logs `memory.note_refused
+     * { reason_class }` and nothing else (§8.6); no note text, frame body or id
+     * is ever logged. Never rejects: an unexpected throw refuses with `store`.
+     *
+     * Everything that decides WHERE and WHETHER a note is written comes from
+     * the bridge-held in-flight record that `ctx.lookup` returns for THIS
+     * socket, never from the frame: the channel (W3), the frozen
+     * authorization (W4(a)), the sender (W4(b)), and the source text and the
+     * `transcribed` mark (W8). The note text that reaches NotesBook is the
+     * owner's own span, produced only by `prepareStoredNote` (W8 then W5).
+     *
+     * LEAF LOCK: heldPosition (W4(b)) is awaited BEFORE the note mutex is
+     * taken; nothing under the mutex awaits it.
+     */
+    applyMemoryNote(raw: Record<string, unknown>, ctx: MemoryNoteContext): Promise<MemoryNoteResultFrame>;
     memoryContext(conversationId: string, limit?: number): Promise<import("@agentvault/connect-mls-store").MemoryContextResult>;
     /**
      * Voice front desk, step 1 — decided SYNCHRONOUSLY inside the ingest cycle,
@@ -2107,6 +2316,8 @@ export declare class BridgeAgent {
      *   room_kill_switch         SECURECOMS_ROOM_DEFAULT_GRANTS as read at startup
      *   per_tool_consumer        a consumer that declared per-tool grant
      *                            enforcement is attached
+     *   memory_write             the turn carries memory_write (Markdown memory
+     *                            7a, spec §8.3): a boolean, never content
      */
     private logAuthzDecision;
     /**
@@ -2377,6 +2588,19 @@ 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). */
+    private stagedPayload;
+    /**
+     * Seal `message` into runtime_inbox with the current ingest stamp and record
+     * the stamp that is actually persisted. Task 7 n-1: a same-id re-stage is
+     * compared on the MESSAGE only, never the stamp, so a clear between two
+     * stagings of one message is not a payload conflict (which would fail the
+     * stage and leave the backend row redelivered forever). The row is not
+     * rewritten, so the FIRST staging's stamp stays authoritative: the owner's
+     * clear still covers a turn first ingested before it. A prior row with no
+     * valid stamp gets none, so its write refuses `cleared`.
+     */
+    private stageSealed;
     private restoreRuntimeInbox;
     /**
      * Seal a runtime frame before the backend queue id may be acknowledged.

package/dist/consumer-grants.d.ts

@@ -17,6 +17,7 @@ export declare const PER_TOOL_GRANTS_FEATURE = "per_tool_grants";
  *
  * Never mutates `m`: the buffer and in-flight records keep the original, so a
  * later per-tool consumer still receives it. The stripped copy keeps every
- * other field (audience, relay_speaker) as is.
+ * other field (audience, relay_speaker) as is, except `memory_write`, which
+ * no non-per-tool consumer ever receives (Markdown memory 7a, review m-3).
  */
 export declare function withConsumerGrants(m: BridgeMessage, perToolConsumer: boolean): BridgeMessage;