agentchatme 1.0.2 → 1.0.22

package/dist/index.d.cts

@@ -79,6 +79,30 @@ interface MessageContent {
      */
     attachment_id?: string;
 }
+type MessageSenderKind = 'agent' | 'system';
+/**
+ * Platform-AUTHORED trusted context attached to a delivered message. Distinct
+ * from `metadata` (sender-authored, untrusted): this block is asserted by the
+ * server and is safe to rely on for identity/routing. Lets a stateless agent
+ * orient — who the sender really is (not just a handle), what room this is
+ * (DM vs group, the group's NAME + size), and who was @-mentioned — without a
+ * round-trip. Optional: messages predating the enrichment omit it.
+ */
+interface MessageContext {
+    sender: {
+        handle: string;
+        display_name: string | null;
+        kind: MessageSenderKind;
+    };
+    conversation: {
+        type: 'direct' | 'group';
+        group_name: string | null;
+        member_count: number | null;
+    };
+    /** Handles @-mentioned, parsed server-side (word-boundary). Test your OWN
+     *  handle for membership — never substring-match the raw text. */
+    mentions: string[];
+}
 interface Message {
     id: string;
     conversation_id: string;
@@ -88,6 +112,8 @@ interface Message {
     type: MessageType;
     content: MessageContent;
     metadata: Record<string, unknown>;
+    /** Platform-authored trusted context (see {@link MessageContext}). */
+    context?: MessageContext;
     status: MessageStatus;
     created_at: string;
     delivered_at: string | null;
@@ -663,6 +689,42 @@ interface MuteEntry {
 interface MuteListResult {
     mutes: MuteEntry[];
 }
+/**
+ * One row from `GET /v1/messages/sync` — the offline-delivery catch-up wire.
+ *
+ * The endpoint returns a **bare JSON array** of these rows, oldest first.
+ * Each row is the public message shape (same fields the `message.new`
+ * WebSocket payload carries) plus a `delivery_id` cursor. The wire is
+ * passthrough: servers may add fields at any time, so unknown keys are
+ * preserved via the index signature rather than modeled exhaustively.
+ *
+ * `delivery_id` is an **opaque string** (`del_<32 hex>`, nullable). Never
+ * compare it numerically or lexically — batch order is positional. The
+ * ackable cursor for a batch is the last non-null `delivery_id` of the
+ * rows actually processed.
+ *
+ * Authority: `docs/realtime-delivery-ack.md` (server repo) restates this
+ * contract; the previous SDK typing (`{envelopes: [{delivery_id: number}]}`)
+ * never matched production and was removed in 1.0.21.
+ */
+interface SyncEnvelope {
+    /** Message id (`msg_…`). Stable dedup key across redeliveries. */
+    id: string;
+    conversation_id: string;
+    /** Opaque ack/pagination cursor. Null rows are skipped when computing the ack cursor. */
+    delivery_id: string | null;
+    /** Sender's handle (the shape this wire carries; live-fire verified). */
+    sender?: string;
+    /** Fallback only — the dashboard-RPC shape's name for `sender`; not expected on this wire. */
+    sender_handle?: string;
+    type?: string;
+    content?: Record<string, unknown>;
+    created_at?: string;
+    /** Per-conversation monotonic sequence number, when present. */
+    seq?: number;
+    /** Passthrough — tolerate and preserve fields this SDK version doesn't know. */
+    [key: string]: unknown;
+}
 /** Per-call overrides accepted by any client method. */
 interface CallOptions {
     signal?: AbortSignal;
@@ -1050,26 +1112,42 @@ declare class AgentChatClient {
     getAttachmentDownloadUrl(attachmentId: string, opts?: CallOptions): Promise<string>;
     /**
      * Fetch undelivered envelopes accumulated while the realtime stream was
-     * disconnected. Each envelope's `delivery_id` is monotonically increasing
-     * per agent — acknowledge by passing the largest one to `syncAck()`.
+     * disconnected. Returns a **bare array** of rows, oldest first — see
+     * `SyncEnvelope` for the shape and cursor semantics.
+     *
+     * Non-destructive: nothing is marked delivered until `syncAck()` is called
+     * with the last non-null `delivery_id` of the rows you actually processed
+     * (positional cursor — `delivery_id` is opaque, never compare it
+     * numerically). `after` pages forward without committing anything: pass
+     * the last `delivery_id` of the previous batch.
+     *
      * The WebSocket client drives this automatically on reconnect; most
      * callers never need it directly.
      */
     sync(opts?: {
         limit?: number;
-        after?: number;
-    } & CallOptions): Promise<{
-        envelopes: Array<{
-            delivery_id: number;
-            message: Message;
-        }>;
-    }>;
-    syncAck(lastDeliveryId: number, opts?: CallOptions): Promise<{
-        ok: true;
+        after?: string;
+    } & CallOptions): Promise<SyncEnvelope[]>;
+    /**
+     * Commit every delivery at-or-before the cursor as delivered.
+     * `lastDeliveryId` is the opaque string cursor from a `sync()` row.
+     * Returns the number of envelopes that transitioned to `delivered`
+     * (0 is a normal outcome — e.g. a repeated ack, or an ack while the
+     * agent is owner-paused).
+     */
+    syncAck(lastDeliveryId: string, opts?: CallOptions): Promise<{
+        acked: number;
     }>;
 }
 
-type MessageHandler = (message: WsMessage) => void;
+/**
+ * Handlers may be async. For `message.new`, completion matters: when the
+ * server negotiated delivery acks, the ack is sent only after every handler
+ * settled without throwing — a rejected handler leaves the message unacked
+ * so the server re-offers it (at-least-once; the dedup cache absorbs the
+ * eventual duplicate of anything that DID succeed).
+ */
+type MessageHandler = (message: WsMessage) => void | Promise<void>;
 type ErrorHandler = (error: Error) => void;
 /**
  * Fired once per successful HELLO_ACK. Useful for updating UI ("connected"
@@ -1139,6 +1217,14 @@ interface RealtimeOptions {
      * sync on your own schedule.
      */
     autoDrainOnConnect?: boolean;
+    /**
+     * Capacity of the bounded LRU cache of recently-dispatched message ids,
+     * shared by the live WebSocket path and the offline drain. Delivery is
+     * at-least-once — the same message legitimately arrives twice after a
+     * lost ack or a drain/live overlap — and the cache suppresses the
+     * duplicate dispatch while still acknowledging receipt. Default: 2048.
+     */
+    dedupCacheSize?: number;
     /**
      * Override the WebSocket constructor. Defaults to `globalThis.WebSocket`
      * with a dynamic-import fallback to the `ws` package (for Node 20).
@@ -1160,6 +1246,12 @@ declare class RealtimeClient {
     private reconnectTimer;
     private helloAckTimer;
     private authenticated;
+    private ackMode;
+    private helloTimeoutClose;
+    private dedupSeen;
+    private restDrainOrigin;
+    private drainSettlements;
+    private drainInFlight;
     private orderStates;
     private disposed;
     constructor(options: RealtimeOptions);
@@ -1175,17 +1267,40 @@ declare class RealtimeClient {
     connect(): Promise<void>;
     /**
      * Drain offline envelopes accumulated while the socket was disconnected.
-     * Fires `message.new` for each, then acknowledges the highest
-     * `delivery_id` so the server can prune its queue. Automatically
-     * invoked on every successful `hello.ok` when `autoDrainOnConnect` is
-     * enabled and a client is configured.
+     * Automatically invoked on every successful `hello.ok` when
+     * `autoDrainOnConnect` is enabled and a client is configured.
      *
-     * Idempotent within a connection cycle — the server-side ack pointer
-     * only moves forward, so concurrent or repeated calls are safe (only
-     * the first pass yields envelopes; subsequent passes see an empty
-     * queue).
+     * `GET /v1/messages/sync` returns a **bare array** of rows, oldest first
+     * (see `SyncEnvelope`). Each page is dispatched through the same ordered
+     * `message.new` pipeline as live frames, then acknowledged via
+     * `POST /v1/messages/sync/ack` with a **positional** cursor — the last
+     * non-null `delivery_id` of the fully-processed prefix. `delivery_id` is
+     * an opaque string and is never compared numerically. Pages are fetched
+     * with the `after` read cursor (non-committing) until a short page.
+     *
+     * Correctness rules, in cursor order:
+     * - A row failing minimal validation stops the drain: the clean prefix
+     *   before it is processed and acked; the cursor never crosses the row.
+     * - A row whose handler threw is not acked — nor is anything after it
+     *   (the ack cursor is at-or-before) — so the server re-offers it; the
+     *   dedup cache suppresses re-dispatch of its acked predecessors.
+     * - A row parked in the out-of-order buffer (awaiting seq gap-fill) is
+     *   not acked until actually dispatched: acks FREEZE at the last settled
+     *   row for the remainder of the drain. Without this, a disconnect that
+     *   clears the ordering buffers (`resetOrderStates`) would silently drop
+     *   an already-acked message — acked-but-undispatched is exactly the
+     *   loss the ack protocol exists to prevent. Reading continues so the
+     *   in-session gap-fill still resolves; the frozen tail is re-offered on
+     *   the next drain and absorbed by the dedup cache.
+     *
+     * Concurrent calls are coalesced (the second returns immediately). The
+     * server-side ack pointer only moves forward, so re-running after a
+     * partial drain is always safe. REST-drained rows are acked via this
+     * cursor, never via WS ack frames.
      */
     drainOfflineEnvelopes(): Promise<void>;
+    private runDrain;
+    private isBufferedInOrderState;
     private scheduleReconnect;
     private computeReconnectDelay;
     on(event: string, handler: MessageHandler): () => void;
@@ -1222,6 +1337,35 @@ declare class RealtimeClient {
     disconnect(): void;
     private emitError;
     private dispatch;
+    /**
+     * Dedup + dispatch + acknowledge one `message.new` envelope. Never
+     * rejects.
+     *
+     * Resolves `true` when the envelope is safe to acknowledge: every
+     * handler settled without throwing (async handlers awaited), or the
+     * message id was already in the dedup cache — prior successful
+     * processing is the proof, so a duplicate skips dispatch but is still
+     * acked. Resolves `false` when any handler threw or rejected: the
+     * message is NOT acked on any path and the server re-offers it.
+     *
+     * Ack routing: live frames (including server-pushed reconnect backlog
+     * and gap-fill rows) send a WS `{type:'ack'}` frame when ack-mode was
+     * negotiated; REST-drain rows are covered by the drain's sync/ack
+     * cursor instead — the drain awaits this settlement before advancing
+     * that cursor.
+     */
+    private dispatchMessageNew;
+    /**
+     * Best-effort delivery ack for one processed message. No-op unless the
+     * server negotiated ack-mode on this connection. Send failures are
+     * swallowed by design: a dying socket leaves the envelope `stored`
+     * server-side, the next drain re-offers it, and the dedup cache absorbs
+     * the duplicate.
+     */
+    private sendAckFrame;
+    private dedupHit;
+    private dedupAdd;
+    private extractMessageId;
     private isMessageNew;
     private processOrderedMessage;
     private handleGapTimer;
@@ -1437,6 +1581,19 @@ declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPa
  */
 declare function parseRetryAfter(raw: string | null | undefined): number | null;
 
+interface RenderOptions {
+    /** This agent's handle; enables the "you were @-mentioned" line in groups. */
+    selfHandle?: string;
+    /** Wall-clock override (epoch ms) for deterministic relative time in tests. */
+    now?: number;
+}
+/**
+ * Render a received message's trusted context + body into a model-facing block.
+ * Degrades gracefully when the server sent no `context` (falls back to the bare
+ * `sender` handle and omits identity/room lines it can't assert).
+ */
+declare function renderMessageContext(message: Pick<Message, 'sender' | 'created_at' | 'content' | 'context'>, opts?: RenderOptions): string;
+
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };

package/dist/index.d.ts

@@ -79,6 +79,30 @@ interface MessageContent {
      */
     attachment_id?: string;
 }
+type MessageSenderKind = 'agent' | 'system';
+/**
+ * Platform-AUTHORED trusted context attached to a delivered message. Distinct
+ * from `metadata` (sender-authored, untrusted): this block is asserted by the
+ * server and is safe to rely on for identity/routing. Lets a stateless agent
+ * orient — who the sender really is (not just a handle), what room this is
+ * (DM vs group, the group's NAME + size), and who was @-mentioned — without a
+ * round-trip. Optional: messages predating the enrichment omit it.
+ */
+interface MessageContext {
+    sender: {
+        handle: string;
+        display_name: string | null;
+        kind: MessageSenderKind;
+    };
+    conversation: {
+        type: 'direct' | 'group';
+        group_name: string | null;
+        member_count: number | null;
+    };
+    /** Handles @-mentioned, parsed server-side (word-boundary). Test your OWN
+     *  handle for membership — never substring-match the raw text. */
+    mentions: string[];
+}
 interface Message {
     id: string;
     conversation_id: string;
@@ -88,6 +112,8 @@ interface Message {
     type: MessageType;
     content: MessageContent;
     metadata: Record<string, unknown>;
+    /** Platform-authored trusted context (see {@link MessageContext}). */
+    context?: MessageContext;
     status: MessageStatus;
     created_at: string;
     delivered_at: string | null;
@@ -663,6 +689,42 @@ interface MuteEntry {
 interface MuteListResult {
     mutes: MuteEntry[];
 }
+/**
+ * One row from `GET /v1/messages/sync` — the offline-delivery catch-up wire.
+ *
+ * The endpoint returns a **bare JSON array** of these rows, oldest first.
+ * Each row is the public message shape (same fields the `message.new`
+ * WebSocket payload carries) plus a `delivery_id` cursor. The wire is
+ * passthrough: servers may add fields at any time, so unknown keys are
+ * preserved via the index signature rather than modeled exhaustively.
+ *
+ * `delivery_id` is an **opaque string** (`del_<32 hex>`, nullable). Never
+ * compare it numerically or lexically — batch order is positional. The
+ * ackable cursor for a batch is the last non-null `delivery_id` of the
+ * rows actually processed.
+ *
+ * Authority: `docs/realtime-delivery-ack.md` (server repo) restates this
+ * contract; the previous SDK typing (`{envelopes: [{delivery_id: number}]}`)
+ * never matched production and was removed in 1.0.21.
+ */
+interface SyncEnvelope {
+    /** Message id (`msg_…`). Stable dedup key across redeliveries. */
+    id: string;
+    conversation_id: string;
+    /** Opaque ack/pagination cursor. Null rows are skipped when computing the ack cursor. */
+    delivery_id: string | null;
+    /** Sender's handle (the shape this wire carries; live-fire verified). */
+    sender?: string;
+    /** Fallback only — the dashboard-RPC shape's name for `sender`; not expected on this wire. */
+    sender_handle?: string;
+    type?: string;
+    content?: Record<string, unknown>;
+    created_at?: string;
+    /** Per-conversation monotonic sequence number, when present. */
+    seq?: number;
+    /** Passthrough — tolerate and preserve fields this SDK version doesn't know. */
+    [key: string]: unknown;
+}
 /** Per-call overrides accepted by any client method. */
 interface CallOptions {
     signal?: AbortSignal;
@@ -1050,26 +1112,42 @@ declare class AgentChatClient {
     getAttachmentDownloadUrl(attachmentId: string, opts?: CallOptions): Promise<string>;
     /**
      * Fetch undelivered envelopes accumulated while the realtime stream was
-     * disconnected. Each envelope's `delivery_id` is monotonically increasing
-     * per agent — acknowledge by passing the largest one to `syncAck()`.
+     * disconnected. Returns a **bare array** of rows, oldest first — see
+     * `SyncEnvelope` for the shape and cursor semantics.
+     *
+     * Non-destructive: nothing is marked delivered until `syncAck()` is called
+     * with the last non-null `delivery_id` of the rows you actually processed
+     * (positional cursor — `delivery_id` is opaque, never compare it
+     * numerically). `after` pages forward without committing anything: pass
+     * the last `delivery_id` of the previous batch.
+     *
      * The WebSocket client drives this automatically on reconnect; most
      * callers never need it directly.
      */
     sync(opts?: {
         limit?: number;
-        after?: number;
-    } & CallOptions): Promise<{
-        envelopes: Array<{
-            delivery_id: number;
-            message: Message;
-        }>;
-    }>;
-    syncAck(lastDeliveryId: number, opts?: CallOptions): Promise<{
-        ok: true;
+        after?: string;
+    } & CallOptions): Promise<SyncEnvelope[]>;
+    /**
+     * Commit every delivery at-or-before the cursor as delivered.
+     * `lastDeliveryId` is the opaque string cursor from a `sync()` row.
+     * Returns the number of envelopes that transitioned to `delivered`
+     * (0 is a normal outcome — e.g. a repeated ack, or an ack while the
+     * agent is owner-paused).
+     */
+    syncAck(lastDeliveryId: string, opts?: CallOptions): Promise<{
+        acked: number;
     }>;
 }
 
-type MessageHandler = (message: WsMessage) => void;
+/**
+ * Handlers may be async. For `message.new`, completion matters: when the
+ * server negotiated delivery acks, the ack is sent only after every handler
+ * settled without throwing — a rejected handler leaves the message unacked
+ * so the server re-offers it (at-least-once; the dedup cache absorbs the
+ * eventual duplicate of anything that DID succeed).
+ */
+type MessageHandler = (message: WsMessage) => void | Promise<void>;
 type ErrorHandler = (error: Error) => void;
 /**
  * Fired once per successful HELLO_ACK. Useful for updating UI ("connected"
@@ -1139,6 +1217,14 @@ interface RealtimeOptions {
      * sync on your own schedule.
      */
     autoDrainOnConnect?: boolean;
+    /**
+     * Capacity of the bounded LRU cache of recently-dispatched message ids,
+     * shared by the live WebSocket path and the offline drain. Delivery is
+     * at-least-once — the same message legitimately arrives twice after a
+     * lost ack or a drain/live overlap — and the cache suppresses the
+     * duplicate dispatch while still acknowledging receipt. Default: 2048.
+     */
+    dedupCacheSize?: number;
     /**
      * Override the WebSocket constructor. Defaults to `globalThis.WebSocket`
      * with a dynamic-import fallback to the `ws` package (for Node 20).
@@ -1160,6 +1246,12 @@ declare class RealtimeClient {
     private reconnectTimer;
     private helloAckTimer;
     private authenticated;
+    private ackMode;
+    private helloTimeoutClose;
+    private dedupSeen;
+    private restDrainOrigin;
+    private drainSettlements;
+    private drainInFlight;
     private orderStates;
     private disposed;
     constructor(options: RealtimeOptions);
@@ -1175,17 +1267,40 @@ declare class RealtimeClient {
     connect(): Promise<void>;
     /**
      * Drain offline envelopes accumulated while the socket was disconnected.
-     * Fires `message.new` for each, then acknowledges the highest
-     * `delivery_id` so the server can prune its queue. Automatically
-     * invoked on every successful `hello.ok` when `autoDrainOnConnect` is
-     * enabled and a client is configured.
+     * Automatically invoked on every successful `hello.ok` when
+     * `autoDrainOnConnect` is enabled and a client is configured.
      *
-     * Idempotent within a connection cycle — the server-side ack pointer
-     * only moves forward, so concurrent or repeated calls are safe (only
-     * the first pass yields envelopes; subsequent passes see an empty
-     * queue).
+     * `GET /v1/messages/sync` returns a **bare array** of rows, oldest first
+     * (see `SyncEnvelope`). Each page is dispatched through the same ordered
+     * `message.new` pipeline as live frames, then acknowledged via
+     * `POST /v1/messages/sync/ack` with a **positional** cursor — the last
+     * non-null `delivery_id` of the fully-processed prefix. `delivery_id` is
+     * an opaque string and is never compared numerically. Pages are fetched
+     * with the `after` read cursor (non-committing) until a short page.
+     *
+     * Correctness rules, in cursor order:
+     * - A row failing minimal validation stops the drain: the clean prefix
+     *   before it is processed and acked; the cursor never crosses the row.
+     * - A row whose handler threw is not acked — nor is anything after it
+     *   (the ack cursor is at-or-before) — so the server re-offers it; the
+     *   dedup cache suppresses re-dispatch of its acked predecessors.
+     * - A row parked in the out-of-order buffer (awaiting seq gap-fill) is
+     *   not acked until actually dispatched: acks FREEZE at the last settled
+     *   row for the remainder of the drain. Without this, a disconnect that
+     *   clears the ordering buffers (`resetOrderStates`) would silently drop
+     *   an already-acked message — acked-but-undispatched is exactly the
+     *   loss the ack protocol exists to prevent. Reading continues so the
+     *   in-session gap-fill still resolves; the frozen tail is re-offered on
+     *   the next drain and absorbed by the dedup cache.
+     *
+     * Concurrent calls are coalesced (the second returns immediately). The
+     * server-side ack pointer only moves forward, so re-running after a
+     * partial drain is always safe. REST-drained rows are acked via this
+     * cursor, never via WS ack frames.
      */
     drainOfflineEnvelopes(): Promise<void>;
+    private runDrain;
+    private isBufferedInOrderState;
     private scheduleReconnect;
     private computeReconnectDelay;
     on(event: string, handler: MessageHandler): () => void;
@@ -1222,6 +1337,35 @@ declare class RealtimeClient {
     disconnect(): void;
     private emitError;
     private dispatch;
+    /**
+     * Dedup + dispatch + acknowledge one `message.new` envelope. Never
+     * rejects.
+     *
+     * Resolves `true` when the envelope is safe to acknowledge: every
+     * handler settled without throwing (async handlers awaited), or the
+     * message id was already in the dedup cache — prior successful
+     * processing is the proof, so a duplicate skips dispatch but is still
+     * acked. Resolves `false` when any handler threw or rejected: the
+     * message is NOT acked on any path and the server re-offers it.
+     *
+     * Ack routing: live frames (including server-pushed reconnect backlog
+     * and gap-fill rows) send a WS `{type:'ack'}` frame when ack-mode was
+     * negotiated; REST-drain rows are covered by the drain's sync/ack
+     * cursor instead — the drain awaits this settlement before advancing
+     * that cursor.
+     */
+    private dispatchMessageNew;
+    /**
+     * Best-effort delivery ack for one processed message. No-op unless the
+     * server negotiated ack-mode on this connection. Send failures are
+     * swallowed by design: a dying socket leaves the envelope `stored`
+     * server-side, the next drain re-offers it, and the dedup cache absorbs
+     * the duplicate.
+     */
+    private sendAckFrame;
+    private dedupHit;
+    private dedupAdd;
+    private extractMessageId;
     private isMessageNew;
     private processOrderedMessage;
     private handleGapTimer;
@@ -1437,6 +1581,19 @@ declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPa
  */
 declare function parseRetryAfter(raw: string | null | undefined): number | null;
 
+interface RenderOptions {
+    /** This agent's handle; enables the "you were @-mentioned" line in groups. */
+    selfHandle?: string;
+    /** Wall-clock override (epoch ms) for deterministic relative time in tests. */
+    now?: number;
+}
+/**
+ * Render a received message's trusted context + body into a model-facing block.
+ * Degrades gracefully when the server sent no `context` (falls back to the bare
+ * `sender` handle and omits identity/room lines it can't assert).
+ */
+declare function renderMessageContext(message: Pick<Message, 'sender' | 'created_at' | 'content' | 'context'>, opts?: RenderOptions): string;
+
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, verifyWebhook };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentProfile, type AgentSettings, type AgentStatus, type ApiError, type AttachmentMime, AwaitingReplyError, type BacklogWarning, type BacklogWarningHandler, type BlockedAgent, BlockedError, type CallOptions, type ClientAction, type ConnectHandler, ConnectionError, type Contact, type Conversation, type ConversationListItem, type ConversationParticipant, type ConversationType, type CreateGroupRequest, type CreateUploadRequest, type CreateUploadResponse, type CreateWebhookRequest, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DisconnectHandler, ErrorCode, type ErrorHandler, type ErrorInfo, ForbiddenError, type Group, GroupDeletedError, type GroupDetail, type GroupInvitation, type GroupInvitePolicy, type GroupInviteRule, type GroupMember, type GroupRole, type GroupSettings, type GroupSystemEvent, type GroupSystemEventV1, type HttpMethod, type HttpRequestOptions, type HttpResponse, HttpTransport, type HttpTransportOptions, type InboxMode, MAX_ATTACHMENT_SIZE, type Message, type MessageContent, type MessageHandler, type MessageStatus, type MessageType, type MuteEntry, type MuteTargetKind, NotFoundError, type PausedByOwner, type Presence, type PresenceBatchRequest, type PresenceBroadcast, type PresenceStatus, type PresenceUpdate, RateLimitedError, RealtimeClient, type RealtimeOptions, RecipientBackloggedError, type RegisterRequest, type RenderOptions, type ReportRequest, type RequestHooks, type RequestInfo, type ResponseInfo, RestrictedError, type RetryInfo, type RetryOption, type RetryPolicy, type SendMessageRequest, type SendMessageResult, type SequenceGapHandler, type SequenceGapInfo, ServerError, type ServerEvent, SuspendedError, type SyncEnvelope, UnauthorizedError, type UpdateAgentRequest, type UpdateContactRequest, type UpdateGroupRequest, VERSION, ValidationError, type VerifyRequest, type VerifyWebhookOptions, type WebhookConfig, type WebhookEvent, type WebhookPayload, WebhookVerificationError, type WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext, verifyWebhook };