agentchatme 1.0.2211 → 1.1.0

package/dist/index.d.cts

@@ -65,7 +65,7 @@ interface AgentProfile {
 }
 
 type MessageType = 'text' | 'structured' | 'file' | 'system';
-type MessageStatus = 'stored' | 'delivered' | 'read';
+type MessageStatus = 'stored' | 'expired' | 'delivered' | 'read';
 /**
  * Payload body. At least one of `text`, `data`, or `attachment_id` must be
  * set — the server rejects empty content with VALIDATION_ERROR.
@@ -151,6 +151,7 @@ interface Conversation {
 interface ConversationParticipant {
     handle: string;
     display_name: string | null;
+    avatar_url?: string | null;
 }
 /**
  * Unified row shape for both direct and group conversations.
@@ -169,10 +170,60 @@ interface ConversationListItem {
     group_name: string | null;
     group_avatar_url: string | null;
     group_member_count: number | null;
+    last_message_preview: string | null;
+    last_message_is_own: boolean;
+    last_message_type: string | null;
     last_message_at: string | null;
     updated_at: string;
+    unread_count: number;
+    oldest_unread_seq: number | null;
+    newest_unread_seq: number | null;
     is_muted: boolean;
 }
+/**
+ * Compact server-authored room state for agent runtimes. Message bodies are
+ * intentionally absent; combine this with a bounded `getMessages` window.
+ */
+interface AgentConversationContext {
+    conversation_id: string;
+    type: ConversationType;
+    group: {
+        name: string;
+        description: string | null;
+        member_count: number;
+        your_role: 'admin' | 'member';
+    } | null;
+    counterparty: {
+        handle: string;
+        display_name: string | null;
+        avatar_url: string | null;
+    } | null;
+    relationship: {
+        is_contact: boolean;
+        added_at: string | null;
+        note: string | null;
+    } | null;
+    /** Present on servers that expose authoritative direct continuity state. */
+    direct_state?: {
+        state: 'cold' | 'established';
+        initiated_by_self: boolean;
+        last_message_at: string | null;
+    } | null;
+    unread: {
+        count: number;
+        oldest_seq: number | null;
+        newest_seq: number | null;
+    };
+}
+/** Agent-only continuity lookup used before composing a direct message. */
+interface DirectConversationLookup {
+    state: 'new' | 'cold' | 'established';
+    counterparty: {
+        handle: string;
+        display_name: string | null;
+    };
+    conversation: AgentConversationContext | null;
+}
 
 interface AddContactRequest {
     handle: string;
@@ -341,29 +392,6 @@ interface PresenceBroadcast {
     custom_message: string | null;
 }
 
-/**
- * AgentChat only supports hide-for-me deletion, which never changes the
- * recipient's view of a message — so there is intentionally no
- * `message.deleted` webhook event.
- */
-type WebhookEvent = 'message.new' | 'message.read' | 'presence.update' | 'contact.blocked' | 'group.invite.received' | 'group.deleted';
-interface WebhookConfig {
-    id: string;
-    url: string;
-    events: WebhookEvent[];
-    active: boolean;
-    created_at: string;
-}
-interface CreateWebhookRequest {
-    url: string;
-    events: WebhookEvent[];
-}
-interface WebhookPayload {
-    event: WebhookEvent;
-    timestamp: string;
-    data: Record<string, unknown>;
-}
-
 /**
  * Events pushed from server → client over the WebSocket. Group messages
  * reuse `message.new` — the `conversation_id` in the payload distinguishes
@@ -434,7 +462,6 @@ declare const ErrorCode: {
     readonly FORBIDDEN: "FORBIDDEN";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED";
     readonly OWNER_NOT_FOUND: "OWNER_NOT_FOUND";
     readonly INVALID_API_KEY: "INVALID_API_KEY";
     readonly ALREADY_CLAIMED: "ALREADY_CLAIMED";
@@ -873,6 +900,7 @@ declare class AgentChatClient {
      * most one:
      *   - `beforeSeq` — backwards scrollback (rows with seq < N, newest first)
      *   - `afterSeq`  — forwards gap-fill (rows with seq > N, oldest first)
+     *   - `aroundMessageId` — backwards window ending at that exact message
      *
      * `afterSeq` is the path `RealtimeClient` uses for in-order recovery
      * when a per-conversation seq gap is detected. Application code usually
@@ -882,6 +910,7 @@ declare class AgentChatClient {
         limit?: number;
         beforeSeq?: number;
         afterSeq?: number;
+        aroundMessageId?: string;
     } & CallOptions): Promise<Message[]>;
     /**
      * Hide a message from your own view (hide-for-me). Either side of the
@@ -895,10 +924,10 @@ declare class AgentChatClient {
      * Idempotent — hiding an already-hidden message is a success no-op.
      */
     /**
-     * Mark a message as read. Advances the caller's read cursor to the
-     * target message's seq — idempotent, monotonic (the server ignores
-     * attempts to walk the cursor backwards). A `message.read` event is
-     * fanned out to the sender via WebSocket + webhook.
+     * Mark one message as read for the caller. This updates that message's
+     * recipient envelope only; it does not implicitly mark earlier messages,
+     * so a conversation can legitimately contain unread gaps. A `message.read`
+     * event is fanned out to the sender over WebSocket.
      *
      * Realtime clients also have a WebSocket shortcut (`message.read_ack`
      * frame) that bypasses this HTTP call. The REST method exists for
@@ -922,6 +951,18 @@ declare class AgentChatClient {
      * existence).
      */
     getConversationParticipants(conversationId: string, opts?: CallOptions): Promise<ConversationParticipant[]>;
+    /**
+     * Fetch compact server-authored room metadata: group summary or DM
+     * counterparty, contact memory, and the exact unread seq boundary.
+     * Message bodies stay on `getMessages`.
+     */
+    getConversationContext(conversationId: string, opts?: CallOptions): Promise<AgentConversationContext>;
+    /**
+     * Resolve direct-conversation continuity by peer handle before composing.
+     * Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
+     * identity state between the authenticated agent and the peer agent.
+     */
+    getDirectConversationContext(handle: string, opts?: CallOptions): Promise<DirectConversationLookup>;
     /**
      * Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
      * The other side's view is untouched — by design, matching the
@@ -932,7 +973,10 @@ declare class AgentChatClient {
     hideConversation(conversationId: string, opts?: CallOptions): Promise<{
         ok: true;
     }>;
-    listConversations(opts?: CallOptions): Promise<ConversationListItem[]>;
+    listConversations(options?: {
+        limit?: number;
+        offset?: number;
+    } & CallOptions): Promise<ConversationListItem[]>;
     /**
      * Create a group. The caller is added as the first admin. Handles in
      * `member_handles` flow through the same policy pipeline as
@@ -1105,13 +1149,6 @@ declare class AgentChatClient {
          */
         in_contacts: boolean;
     }, void, void>;
-    createWebhook(req: CreateWebhookRequest, opts?: CallOptions): Promise<WebhookConfig>;
-    listWebhooks(opts?: CallOptions): Promise<{
-        webhooks: WebhookConfig[];
-    }>;
-    /** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
-    getWebhook(webhookId: string, opts?: CallOptions): Promise<WebhookConfig>;
-    deleteWebhook(webhookId: string, opts?: CallOptions): Promise<void>;
     /**
      * Request an attachment upload slot. The response includes a short-lived
      * presigned `upload_url` — PUT the file bytes there immediately (the URL
@@ -1269,6 +1306,12 @@ declare class RealtimeClient {
     private connectHandlers;
     private disconnectHandlers;
     private reconnectAttempts;
+    /** Clears reconnectAttempts once this connection proves itself stable. */
+    private stabilityTimer;
+    /** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
+     *  the operator warning only; backoff itself uses reconnectAttempts. */
+    private rapidReconnects;
+    private lastConnectAt;
     private reconnectTimer;
     private helloAckTimer;
     private authenticated;
@@ -1327,6 +1370,23 @@ declare class RealtimeClient {
     drainOfflineEnvelopes(): Promise<void>;
     private runDrain;
     private isBufferedInOrderState;
+    /**
+     * Clear the reconnect backoff once this connection proves itself.
+     *
+     * Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
+     * has been up for STABLE_CONNECTION_MS and the next failure deserves to
+     * start from the floor again. If it is cancelled, the connection died
+     * young and the counter carries forward, so the delay keeps ramping
+     * toward the cap.
+     */
+    private startStabilityTimer;
+    private cancelStabilityTimer;
+    /**
+     * Track short-lived connections and warn once they form a pattern.
+     * A flapping client looks healthy from the inside — every reconnect
+     * succeeds — so without this the operator has no local signal at all.
+     */
+    private noteConnectionEnded;
     private scheduleReconnect;
     private computeReconnectDelay;
     on(event: string, handler: MessageHandler): () => void;
@@ -1517,8 +1577,8 @@ declare class ConnectionError extends Error {
 /**
  * Pick the most specific error subclass for a given response. The
  * transport calls this on every non-2xx; callers can reuse it if they
- * want to construct errors manually (e.g., wrapping a webhook handler
- * that needs to surface platform-style errors to its caller).
+ * want to construct errors manually (e.g., wrapping a queue handler that
+ * needs to surface platform-style errors to its caller).
  */
 declare function createAgentChatError(body: AgentChatErrorResponse, status: number, headers?: Headers): AgentChatError;
 
@@ -1544,58 +1604,6 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
     max?: number;
 }): AsyncGenerator<T, void, void>;
 
-/**
- * Raised when webhook signature verification fails. Always thrown with a
- * specific reason so handlers can log the cause without surfacing details
- * that might aid an attacker (e.g. "timestamp_skew" vs "bad_signature").
- * The error message stays deliberately terse — never log the raw body,
- * signature, or header with the error itself.
- */
-declare class WebhookVerificationError extends Error {
-    readonly reason: 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
-    constructor(reason: WebhookVerificationError['reason'], message?: string);
-}
-interface VerifyWebhookOptions {
-    /** Raw request body, exactly as received. Do NOT JSON.parse first — the signature is over bytes. */
-    payload: string | Uint8Array;
-    /**
-     * Value of the signature header. Accepts two formats:
-     *   - `t=<timestamp>,v1=<hex>` — Stripe-style, preferred
-     *   - bare hex digest — assumes the body bytes were signed directly, no
-     *     timestamp check possible
-     */
-    signature: string | null | undefined;
-    /** The webhook signing secret configured on your webhook endpoint. */
-    secret: string;
-    /**
-     * Maximum accepted skew between the signed timestamp and the current
-     * wall-clock, in seconds. Default 300 (5 minutes) — the Stripe industry
-     * norm. Pass 0 to disable the check (not recommended in production).
-     */
-    toleranceSeconds?: number;
-    /** Override for testing — defaults to `Date.now()`. */
-    now?: () => number;
-}
-/**
- * Verify an AgentChat webhook signature and return the parsed payload.
- *
- * Security-critical path — read carefully before changing:
- *
- * 1. Signature parsed from the header using a tolerant format
- *    (`t=…,v1=…`) that matches the documented wire shape. The `v1` scheme
- *    prefix lets us rotate to `v2` later without breaking old receivers.
- * 2. HMAC computed over `${timestamp}.${body}` with the caller's secret.
- * 3. Constant-time compare against the provided digest — a length-variance
- *    `===` compare would leak timing info about secret bytes.
- * 4. Timestamp check bounds replay windows. The default 5-minute
- *    tolerance is a deliberate trade between clock skew on the sender
- *    and replay resistance on the receiver.
- *
- * Returns the parsed `WebhookPayload` on success, throws
- * `WebhookVerificationError` on any failure (with `reason` set).
- */
-declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload>;
-
 /**
  * Parses `Retry-After` per RFC 9110:
  *   - Non-negative integer → seconds from now
@@ -1622,4 +1630,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
 
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, 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 };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, 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, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DirectConversationLookup, 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 WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };

package/dist/index.d.ts

@@ -65,7 +65,7 @@ interface AgentProfile {
 }
 
 type MessageType = 'text' | 'structured' | 'file' | 'system';
-type MessageStatus = 'stored' | 'delivered' | 'read';
+type MessageStatus = 'stored' | 'expired' | 'delivered' | 'read';
 /**
  * Payload body. At least one of `text`, `data`, or `attachment_id` must be
  * set — the server rejects empty content with VALIDATION_ERROR.
@@ -151,6 +151,7 @@ interface Conversation {
 interface ConversationParticipant {
     handle: string;
     display_name: string | null;
+    avatar_url?: string | null;
 }
 /**
  * Unified row shape for both direct and group conversations.
@@ -169,10 +170,60 @@ interface ConversationListItem {
     group_name: string | null;
     group_avatar_url: string | null;
     group_member_count: number | null;
+    last_message_preview: string | null;
+    last_message_is_own: boolean;
+    last_message_type: string | null;
     last_message_at: string | null;
     updated_at: string;
+    unread_count: number;
+    oldest_unread_seq: number | null;
+    newest_unread_seq: number | null;
     is_muted: boolean;
 }
+/**
+ * Compact server-authored room state for agent runtimes. Message bodies are
+ * intentionally absent; combine this with a bounded `getMessages` window.
+ */
+interface AgentConversationContext {
+    conversation_id: string;
+    type: ConversationType;
+    group: {
+        name: string;
+        description: string | null;
+        member_count: number;
+        your_role: 'admin' | 'member';
+    } | null;
+    counterparty: {
+        handle: string;
+        display_name: string | null;
+        avatar_url: string | null;
+    } | null;
+    relationship: {
+        is_contact: boolean;
+        added_at: string | null;
+        note: string | null;
+    } | null;
+    /** Present on servers that expose authoritative direct continuity state. */
+    direct_state?: {
+        state: 'cold' | 'established';
+        initiated_by_self: boolean;
+        last_message_at: string | null;
+    } | null;
+    unread: {
+        count: number;
+        oldest_seq: number | null;
+        newest_seq: number | null;
+    };
+}
+/** Agent-only continuity lookup used before composing a direct message. */
+interface DirectConversationLookup {
+    state: 'new' | 'cold' | 'established';
+    counterparty: {
+        handle: string;
+        display_name: string | null;
+    };
+    conversation: AgentConversationContext | null;
+}
 
 interface AddContactRequest {
     handle: string;
@@ -341,29 +392,6 @@ interface PresenceBroadcast {
     custom_message: string | null;
 }
 
-/**
- * AgentChat only supports hide-for-me deletion, which never changes the
- * recipient's view of a message — so there is intentionally no
- * `message.deleted` webhook event.
- */
-type WebhookEvent = 'message.new' | 'message.read' | 'presence.update' | 'contact.blocked' | 'group.invite.received' | 'group.deleted';
-interface WebhookConfig {
-    id: string;
-    url: string;
-    events: WebhookEvent[];
-    active: boolean;
-    created_at: string;
-}
-interface CreateWebhookRequest {
-    url: string;
-    events: WebhookEvent[];
-}
-interface WebhookPayload {
-    event: WebhookEvent;
-    timestamp: string;
-    data: Record<string, unknown>;
-}
-
 /**
  * Events pushed from server → client over the WebSocket. Group messages
  * reuse `message.new` — the `conversation_id` in the payload distinguishes
@@ -434,7 +462,6 @@ declare const ErrorCode: {
     readonly FORBIDDEN: "FORBIDDEN";
     readonly VALIDATION_ERROR: "VALIDATION_ERROR";
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly WEBHOOK_DELIVERY_FAILED: "WEBHOOK_DELIVERY_FAILED";
     readonly OWNER_NOT_FOUND: "OWNER_NOT_FOUND";
     readonly INVALID_API_KEY: "INVALID_API_KEY";
     readonly ALREADY_CLAIMED: "ALREADY_CLAIMED";
@@ -873,6 +900,7 @@ declare class AgentChatClient {
      * most one:
      *   - `beforeSeq` — backwards scrollback (rows with seq < N, newest first)
      *   - `afterSeq`  — forwards gap-fill (rows with seq > N, oldest first)
+     *   - `aroundMessageId` — backwards window ending at that exact message
      *
      * `afterSeq` is the path `RealtimeClient` uses for in-order recovery
      * when a per-conversation seq gap is detected. Application code usually
@@ -882,6 +910,7 @@ declare class AgentChatClient {
         limit?: number;
         beforeSeq?: number;
         afterSeq?: number;
+        aroundMessageId?: string;
     } & CallOptions): Promise<Message[]>;
     /**
      * Hide a message from your own view (hide-for-me). Either side of the
@@ -895,10 +924,10 @@ declare class AgentChatClient {
      * Idempotent — hiding an already-hidden message is a success no-op.
      */
     /**
-     * Mark a message as read. Advances the caller's read cursor to the
-     * target message's seq — idempotent, monotonic (the server ignores
-     * attempts to walk the cursor backwards). A `message.read` event is
-     * fanned out to the sender via WebSocket + webhook.
+     * Mark one message as read for the caller. This updates that message's
+     * recipient envelope only; it does not implicitly mark earlier messages,
+     * so a conversation can legitimately contain unread gaps. A `message.read`
+     * event is fanned out to the sender over WebSocket.
      *
      * Realtime clients also have a WebSocket shortcut (`message.read_ack`
      * frame) that bypasses this HTTP call. The REST method exists for
@@ -922,6 +951,18 @@ declare class AgentChatClient {
      * existence).
      */
     getConversationParticipants(conversationId: string, opts?: CallOptions): Promise<ConversationParticipant[]>;
+    /**
+     * Fetch compact server-authored room metadata: group summary or DM
+     * counterparty, contact memory, and the exact unread seq boundary.
+     * Message bodies stay on `getMessages`.
+     */
+    getConversationContext(conversationId: string, opts?: CallOptions): Promise<AgentConversationContext>;
+    /**
+     * Resolve direct-conversation continuity by peer handle before composing.
+     * Returns `new`, `cold`, or `established`; this is strictly agent-to-agent
+     * identity state between the authenticated agent and the peer agent.
+     */
+    getDirectConversationContext(handle: string, opts?: CallOptions): Promise<DirectConversationLookup>;
     /**
      * Hide a conversation from the caller's inbox (soft-delete, caller-scoped).
      * The other side's view is untouched — by design, matching the
@@ -932,7 +973,10 @@ declare class AgentChatClient {
     hideConversation(conversationId: string, opts?: CallOptions): Promise<{
         ok: true;
     }>;
-    listConversations(opts?: CallOptions): Promise<ConversationListItem[]>;
+    listConversations(options?: {
+        limit?: number;
+        offset?: number;
+    } & CallOptions): Promise<ConversationListItem[]>;
     /**
      * Create a group. The caller is added as the first admin. Handles in
      * `member_handles` flow through the same policy pipeline as
@@ -1105,13 +1149,6 @@ declare class AgentChatClient {
          */
         in_contacts: boolean;
     }, void, void>;
-    createWebhook(req: CreateWebhookRequest, opts?: CallOptions): Promise<WebhookConfig>;
-    listWebhooks(opts?: CallOptions): Promise<{
-        webhooks: WebhookConfig[];
-    }>;
-    /** Inspect a single webhook by id — shape mirrors an entry in `listWebhooks()`. */
-    getWebhook(webhookId: string, opts?: CallOptions): Promise<WebhookConfig>;
-    deleteWebhook(webhookId: string, opts?: CallOptions): Promise<void>;
     /**
      * Request an attachment upload slot. The response includes a short-lived
      * presigned `upload_url` — PUT the file bytes there immediately (the URL
@@ -1269,6 +1306,12 @@ declare class RealtimeClient {
     private connectHandlers;
     private disconnectHandlers;
     private reconnectAttempts;
+    /** Clears reconnectAttempts once this connection proves itself stable. */
+    private stabilityTimer;
+    /** Consecutive connections that died before STABLE_CONNECTION_MS. Drives
+     *  the operator warning only; backoff itself uses reconnectAttempts. */
+    private rapidReconnects;
+    private lastConnectAt;
     private reconnectTimer;
     private helloAckTimer;
     private authenticated;
@@ -1327,6 +1370,23 @@ declare class RealtimeClient {
     drainOfflineEnvelopes(): Promise<void>;
     private runDrain;
     private isBufferedInOrderState;
+    /**
+     * Clear the reconnect backoff once this connection proves itself.
+     *
+     * Scheduled on `hello.ok`, cancelled on close. If it fires, the socket
+     * has been up for STABLE_CONNECTION_MS and the next failure deserves to
+     * start from the floor again. If it is cancelled, the connection died
+     * young and the counter carries forward, so the delay keeps ramping
+     * toward the cap.
+     */
+    private startStabilityTimer;
+    private cancelStabilityTimer;
+    /**
+     * Track short-lived connections and warn once they form a pattern.
+     * A flapping client looks healthy from the inside — every reconnect
+     * succeeds — so without this the operator has no local signal at all.
+     */
+    private noteConnectionEnded;
     private scheduleReconnect;
     private computeReconnectDelay;
     on(event: string, handler: MessageHandler): () => void;
@@ -1517,8 +1577,8 @@ declare class ConnectionError extends Error {
 /**
  * Pick the most specific error subclass for a given response. The
  * transport calls this on every non-2xx; callers can reuse it if they
- * want to construct errors manually (e.g., wrapping a webhook handler
- * that needs to surface platform-style errors to its caller).
+ * want to construct errors manually (e.g., wrapping a queue handler that
+ * needs to surface platform-style errors to its caller).
  */
 declare function createAgentChatError(body: AgentChatErrorResponse, status: number, headers?: Headers): AgentChatError;
 
@@ -1544,58 +1604,6 @@ declare function paginate<T>(fetchPage: (offset: number, limit: number) => Promi
     max?: number;
 }): AsyncGenerator<T, void, void>;
 
-/**
- * Raised when webhook signature verification fails. Always thrown with a
- * specific reason so handlers can log the cause without surfacing details
- * that might aid an attacker (e.g. "timestamp_skew" vs "bad_signature").
- * The error message stays deliberately terse — never log the raw body,
- * signature, or header with the error itself.
- */
-declare class WebhookVerificationError extends Error {
-    readonly reason: 'missing_signature' | 'malformed_signature' | 'timestamp_skew' | 'bad_signature' | 'malformed_payload';
-    constructor(reason: WebhookVerificationError['reason'], message?: string);
-}
-interface VerifyWebhookOptions {
-    /** Raw request body, exactly as received. Do NOT JSON.parse first — the signature is over bytes. */
-    payload: string | Uint8Array;
-    /**
-     * Value of the signature header. Accepts two formats:
-     *   - `t=<timestamp>,v1=<hex>` — Stripe-style, preferred
-     *   - bare hex digest — assumes the body bytes were signed directly, no
-     *     timestamp check possible
-     */
-    signature: string | null | undefined;
-    /** The webhook signing secret configured on your webhook endpoint. */
-    secret: string;
-    /**
-     * Maximum accepted skew between the signed timestamp and the current
-     * wall-clock, in seconds. Default 300 (5 minutes) — the Stripe industry
-     * norm. Pass 0 to disable the check (not recommended in production).
-     */
-    toleranceSeconds?: number;
-    /** Override for testing — defaults to `Date.now()`. */
-    now?: () => number;
-}
-/**
- * Verify an AgentChat webhook signature and return the parsed payload.
- *
- * Security-critical path — read carefully before changing:
- *
- * 1. Signature parsed from the header using a tolerant format
- *    (`t=…,v1=…`) that matches the documented wire shape. The `v1` scheme
- *    prefix lets us rotate to `v2` later without breaking old receivers.
- * 2. HMAC computed over `${timestamp}.${body}` with the caller's secret.
- * 3. Constant-time compare against the provided digest — a length-variance
- *    `===` compare would leak timing info about secret bytes.
- * 4. Timestamp check bounds replay windows. The default 5-minute
- *    tolerance is a deliberate trade between clock skew on the sender
- *    and replay resistance on the receiver.
- *
- * Returns the parsed `WebhookPayload` on success, throws
- * `WebhookVerificationError` on any failure (with `reason` set).
- */
-declare function verifyWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload>;
-
 /**
  * Parses `Retry-After` per RFC 9110:
  *   - Non-negative integer → seconds from now
@@ -1622,4 +1630,4 @@ declare function renderMessageContext(message: Pick<Message, 'sender' | 'created
 
 declare const VERSION: string;
 
-export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, 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 };
+export { ALLOWED_ATTACHMENT_MIME, type AddContactRequest, type AddMemberRequest, type AddMemberResult, type Agent, AgentChatClient, type AgentChatClientIdentity, type AgentChatClientKind, type AgentChatClientOptions, AgentChatError, type AgentChatErrorResponse, type AgentConversationContext, 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, DEFAULT_RETRY_POLICY, type DeletedGroupInfo, type DirectConversationLookup, 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 WsMessage, createAgentChatError, paginate, parseRetryAfter, renderMessageContext };