@securecoms/agent-bridge 0.37.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;
@@ -2934,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,