@securecoms/agent-bridge 0.36.0 → 0.38.0

package/dist/bridge-agent.d.ts

@@ -519,6 +519,12 @@ export interface BridgeAgentDeps {
      * Injected so tests do not wait the full window.
      */
     voiceCoalesceWindowMs?: number;
+    /**
+     * Image + caption coalescing: how long a caption-less image share waits for
+     * its sender's caption (default CAPTION_COALESCE_WINDOW_MS; 0 disables the
+     * hold, every image is staged at once as before).
+     */
+    captionCoalesceWindowMs?: number;
     /**
      * B7 (FileSafe vault): persistence for the vault kekset's owner-pin TOFU
      * state. Defaults to a {@link FileOwnerAuthorityStore} at
@@ -566,6 +572,30 @@ export declare function voiceWindowEligible(t: {
     voiceGuidance: string | undefined;
     isCallStart: boolean;
 }): boolean;
+/**
+ * Image + caption coalescing (2026-11-11). The web client sends an image with a
+ * caption as TWO channel messages: an `artifact_share` with no text, then a plain
+ * text message. Delivered as two turns, the agent answered the bare image and
+ * then the caption without the image. A caption-less image share from a sender
+ * that is not an agent is staged durably but HELD this long; the next message
+ * from the same sender in the same channel, if it is a text turn, is delivered
+ * as ONE frame: the caption's id, text, authorization and memory, plus the held
+ * images' attachments. Anything else in the channel releases the held images
+ * first, in order. Rules (see BridgeAgent.holdCaptionImage and the text path):
+ *  - consecutive images from the same sender join one hold (the window restarts
+ *    from the latest image), up to CAPTION_MERGE_MAX_ATTACHMENTS; with no caption
+ *    each image is released as its own frame, in order, as before;
+ *  - the merge happens only when every held image's authorization equals the
+ *    caption's (never widens or narrows a grant), else the images go alone first;
+ *  - in a room, a caption the @mention filter rejects drops the held images too
+ *    (image + caption was one message, addressed elsewhere); a caption-less image
+ *    alone still follows the unchanged broadcast rule;
+ *  - close() releases nothing: held images stay in runtime_inbox and a restart
+ *    restores them as ordinary turns.
+ */
+export declare const CAPTION_COALESCE_WINDOW_MS = 1500;
+/** The connectors accept at most 8 attachments per frame (#1450): a hold never grows past that. */
+export declare const CAPTION_MERGE_MAX_ATTACHMENTS = 8;
 /** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
 export declare const DEFAULT_MAX_BUFFER = 1000;
 /**
@@ -1119,6 +1149,14 @@ export declare class BridgeAgent {
     private readonly voiceCoalescedIds;
     /** Merged turn id -> the absorbed fragments' held frames, retired with it. */
     private readonly voiceCoalescedTails;
+    /** Image + caption coalescing: the open hold per channel (CAPTION_COALESCE_WINDOW_MS). */
+    private readonly captionHolds;
+    /**
+     * Ids of held images whose content was consumed (capped FIFO): merged into a caption frame, or dropped with a
+     * caption the room filter rejected. A redelivered row is acked, never downloaded or delivered (audit L1, round 2).
+     */
+    private readonly captionConsumedIds;
+    private readonly captionCoalesceWindowMs;
     /** (4) recv.lag: application queue ids already measured (capped FIFO), so a re-pulled row is not re-counted. */
     private readonly recvLagSeen;
     private static readonly RECV_LAG_SEEN_CAP;
@@ -1240,6 +1278,29 @@ export declare class BridgeAgent {
      */
     private mcpPolicyWritten;
     private mcpPolicyWrittenJson;
+    /** Deletion-ack ruling §3: the manifest counter in force when `mcpPolicyWrittenJson` was written (never read live). */
+    private mcpPolicyWrittenCounter;
+    /** Ruling §3: newest counter whose written policy the runtime fully acted on. Memory only, monotonic, starts at 0. */
+    private mcpDeletionsThrough;
+    /** Ruling §3: the last `credentials_present` an accepted frame carried; null until one arrives. */
+    private mcpCredentialsPresentValue;
+    /** Ruling §3: per attached socket, whether its latest hello declared mcp_deletion_ack_v1 (harness noted false). */
+    private readonly mcpDeletionAckSockets;
+    /** Ruling §3 rate: the ack-derived report values in the last report posted (null until one is). */
+    private lastReportedMcpAck;
+    /** #1351 round 2 M-1: bumped on every byte-changing policy write (and on the inert document being put in force). */
+    private policyWriteSeq;
+    /** M-1: per ack-capable socket, the policyWriteSeq at the dispatch of each owner-DM turn, by message id (bounded). */
+    private readonly mcpTurnSeq;
+    /**
+     * #1351 round 2 H-1: the ack values the REPORT may carry. An ack lands seconds after an owner-DM turn and a report
+     * posted then would time the turn (record_report sets applied_at). So, as the tool-status sender: `open` holds a
+     * change while its 15-minute UTC bucket is open, `closed` what the report carries, and the only post is from one
+     * timer at the next bucket boundary plus jitter.
+     */
+    private mcpAckOpen;
+    private mcpAckClosed;
+    private mcpAckTimer;
     /** PR-B2 follow-up: a failed write is retried on this backoff (the last value repeats) until one lands or close(). */
     private readonly mcpPolicyRetryDelaysMs;
     private mcpPolicyRetryTimer;
@@ -2911,6 +2972,33 @@ export declare class BridgeAgent {
      * deferring fast reply was actually published — F3).
      */
     private speakAndSettle;
+    /**
+     * Image + caption coalescing: stage a caption-less image share durably but
+     * HELD, joining its sender's open hold in this channel or opening one. The
+     * hold's job takes the channel queue now, so every later frame of the channel
+     * (all staged through stageRuntimeMessageInOrder or the queue) waits behind it.
+     * Returns false on backpressure (the row stays unacked). The caller has
+     * checked the id is not already staged (a redelivered row).
+     */
+    private holdCaptionImage;
+    /** Release one held image as its own frame: the room web_search count it skipped at staging runs now (audit M3). */
+    private releaseCaptionImage;
+    /**
+     * Retire held images whose content left with a merged frame or was dropped with a filtered caption. Never throws
+     * (audit M1: a throw here left the hold job asleep and the channel queue wedged): a row that cannot be retired
+     * stays in runtime_inbox and comes back at a restart as an ordinary turn.
+     */
+    private retireCaptionImages;
+    /** Audit L3: best-effort removal of the decrypted files of images dropped with a filtered caption. Never throws. */
+    private unlinkCaptionImages;
+    private noteCaptionConsumed;
+    private armCaptionHold;
+    /** Detach a hold synchronously: nothing joins or merges into it after this. */
+    private detachCaptionHold;
+    /** Detach (if still open) and wake the hold's job with its outcome. Idempotent on the outcome. */
+    private closeCaptionHold;
+    /** The open hold a text turn from `senderId` in `channelId` may take, if any. */
+    private captionHoldFor;
     /**
      * Stage a runtime frame without overtaking a turn of the same channel that
      * is still queued behind the fast path (F2): while the channel has a queue,
@@ -3744,6 +3832,45 @@ export declare class BridgeAgent {
     private readonly mcpClientSockets;
     noteMcpClientSocket(token: object, declared: boolean): void;
     clearMcpClientSocket(token: object): void;
+    /** Deletion-ack ruling §3: ws-server notes every runtime hello's mcp_deletion_ack_v1 declaration (harness: false). */
+    noteMcpDeletionAckSocket(token: object, declared: boolean): void;
+    /** #1351 round 2 observation: with no ack-capable socket left (detached, or re-hello'd without the feature), the last
+     *  credentials value is no longer known: forget it, so a later socket does not inherit a stale value. */
+    private forgetCredentialsIfNoAckSocket;
+    clearMcpDeletionAckSocket(token: object): void;
+    /** #1351 round 2 M-1: ws-server calls this when it sends an owner-DM turn to an ack-capable socket. Bounded. */
+    noteMcpTurnDispatch(token: object, messageId: string): void;
+    /** Ruling §3 / §5.3: the AND over attached sockets, false with none attached (as mcpClientCapable). */
+    private mcpDeletionAckCapable;
+    /**
+     * Deletion-ack ruling (2026-10-31) §3 acceptance. ws-server has validated the frame shape and the socket (declared
+     * mcp_deletion_ack_v1 and mcp_client_v1, no harness). `credentials_present` is taken as is. `applied_sha256` advances
+     * `mcpDeletionsThrough` only when it is the SHA-256 of the bytes THIS bridge last wrote (JSON + newline) and still
+     * holds in force, and that document's top state is one whose deletion set covers the signed removal; then to the
+     * counter recorded at that write, never the live one. Anything else is ignored silently. Never throws.
+     */
+    noteMcpDeletionAck(token: object, frame: {
+        credentials_present: boolean;
+        message_id?: string;
+        applied_sha256?: string;
+    }): void;
+    /** H-1: a change of the ack values goes into the open bucket; the report sees it only once the bucket has closed. */
+    private noteMcpAckChanged;
+    private promoteMcpAck;
+    /** H-1: one timer, at the first bucket boundary strictly after now plus a jitter in [0, 60 s), as the tool-status sender. */
+    private scheduleMcpAckReport;
+    /**
+     * Ruling §5.3: the three keys. The two ack values come from the CLOSED bucket only (H-1), so no report, whatever
+     * posts it, reveals an owner-DM turn before its 15-minute bucket has closed. `mcp_r3_hold` is not DM timing: live.
+     */
+    private reportedMcpAck;
+    private mcpAckSignature;
+    /**
+     * A SOCKET change (attach, detach, a hello) can change which keys the report carries; their values are the closed
+     * ones, so this is not owner-DM timing and may use the capability refetch. An ACK never comes here (H-1): it goes
+     * through noteMcpAckChanged and the bucket timer.
+     */
+    private maybeReportMcpAck;
     /** MCP Task 18: ws-server registers (or, with null, removes) a socket's loopback catalog lister. */
     noteMcpCatalogLister(token: object, lister: McpCatalogLister | null): void;
     /**
@@ -3790,6 +3917,8 @@ export declare class BridgeAgent {
      * switches and the new capability, then a debounced refetch (one per burst) only when needed.
      */
     private onCapabilityMaybeChanged;
+    /** Debounced, with a max wait: a burst that never pauses still refetches at most maxWait after its first change. */
+    private scheduleCapabilityRefetch;
     /**
      * A refetch re-renders skills.json (owner_dm_search_cap counts web_extract only with the capability, D39) and posts
      * the report. Needed under a manifest in force, or when the reported value is stale. Never before the boot fetch.

package/dist/grants/mcp-policy.d.ts

@@ -33,6 +33,13 @@ import { type ServiceLog } from "../service-log.js";
  * backend can write that name (ws-server.test.ts same-build row).
  */
 export declare const MCP_POLICY_WRITER_FEATURE = "mcp_policy_writer_v1";
+/**
+ * Deletion-ack ruling (2026-10-31) §3: declared in the hello reply and by the runtime in its hello. Only a socket that
+ * declared it (and mcp_client_v1, no harness) may send `mcp_deletion_ack`.
+ */
+export declare const MCP_DELETION_ACK_FEATURE = "mcp_deletion_ack_v1";
+/** Ruling §3: the top states whose deletion set covers the manifest's signed `removed` (ok), or everything on disk. */
+export declare const MCP_ACK_STATES: ReadonlySet<string>;
 export type McpEntitlementReading = "entitled" | "not_entitled" | "suspended";
 /**
  * OQ-1 ruling (ADR G). Only `true`/"entitled" is in force and only `false`/"not_entitled" is the deleting downgrade.