agentchatme 1.0.2 → 1.0.21

package/dist/index.js

@@ -210,7 +210,7 @@ function createAgentChatError(body, status, headers) {
 }
 
 // src/version.ts
-var VERSION = "1.0.2" ;
+var VERSION = "1.0.21" ;
 
 // src/runtime.ts
 function detectRuntime() {
@@ -1255,22 +1255,36 @@ var AgentChatClient = class _AgentChatClient {
   // ─── Sync / read-state ────────────────────────────────────────────────────
   /**
    * 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) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set("limit", String(opts.limit));
-    if (opts?.after !== void 0) params.set("after", String(opts.after));
+    if (opts?.after !== void 0) params.set("after", opts.after);
     const qs = params.toString();
     return this.get(`/v1/messages/sync${qs ? `?${qs}` : ""}`, opts);
   }
-  syncAck(lastDeliveryId, opts) {
+  /**
+   * 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(lastDeliveryId2, opts) {
     return this.post(
       "/v1/messages/sync/ack",
-      { last_delivery_id: lastDeliveryId },
+      { last_delivery_id: lastDeliveryId2 },
       opts
     );
   }
@@ -1307,6 +1321,36 @@ var HELLO_ACK_TIMEOUT_MS = 4e3;
 var GAP_FILL_WINDOW_MS = 2e3;
 var MAX_BUFFERED_PER_CONVERSATION = 500;
 var GAP_FILL_LIMIT = 200;
+var SYNC_DRAIN_PAGE_SIZE = 200;
+var DEFAULT_DEDUP_CACHE_SIZE = 2048;
+var TERMINAL_CLOSE_CODES = /* @__PURE__ */ new Set([1008, 4401, 4403]);
+function isValidSyncRow(row) {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) return false;
+  const r = row;
+  if (typeof r.id !== "string") return false;
+  if (typeof r.conversation_id !== "string") return false;
+  if (typeof r.delivery_id !== "string" && r.delivery_id !== null) return false;
+  for (const key of ["sender", "sender_handle", "type", "created_at"]) {
+    if (r[key] !== void 0 && typeof r[key] !== "string") return false;
+  }
+  if (r.content !== void 0 && (typeof r.content !== "object" || r.content === null || Array.isArray(r.content))) {
+    return false;
+  }
+  return true;
+}
+function lastDeliveryId(rows) {
+  for (let i = rows.length - 1; i >= 0; i--) {
+    const id = rows[i]?.delivery_id;
+    if (typeof id === "string" && id.length > 0) return id;
+  }
+  return null;
+}
+function isThenable(value) {
+  return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+function toError(reason, context) {
+  return reason instanceof Error ? reason : new Error(`${context} handler failed: ${String(reason)}`);
+}
 var RealtimeClient = class {
   ws = null;
   options;
@@ -1318,9 +1362,37 @@ var RealtimeClient = class {
   reconnectTimer = null;
   helloAckTimer = null;
   authenticated = false;
+  // True only when the server echoed the 'ack' capability in hello.ok.
+  // Per-connection: reset on every close and re-negotiated on every HELLO.
+  ackMode = false;
+  // Set immediately before our own close(1008, 'HELLO ack timeout') so the
+  // onclose handler can tell this transient self-close apart from a
+  // server-initiated 1008 (which is terminal — invalid credentials).
+  helloTimeoutClose = false;
+  // Bounded LRU of recently-dispatched message ids (Set iteration order is
+  // insertion order — delete + re-add refreshes recency). Ids are added
+  // only AFTER a successful dispatch: adding earlier would let a failed
+  // dispatch suppress its own redelivery.
+  dedupSeen = /* @__PURE__ */ new Set();
+  // Envelopes injected by the REST drain, as opposed to live WS frames.
+  // Drain rows are acknowledged via the REST sync/ack cursor, never via a
+  // WS ack frame; everything else on the message.new pipeline (live frames,
+  // server-pushed reconnect backlog, gap-fill rows) takes the WS ack path
+  // when ack-mode is negotiated.
+  restDrainOrigin = /* @__PURE__ */ new WeakSet();
+  // Per-envelope dispatch settlement for drain rows: resolves true when
+  // every handler settled cleanly (or the row deduped), false when a
+  // handler threw/rejected. The drain awaits these before advancing the
+  // ack cursor. WeakMap so entries die with the envelope objects.
+  drainSettlements = /* @__PURE__ */ new WeakMap();
+  // Coalesces concurrent drains — the server-side ack pointer only moves
+  // forward, so one drain at a time is both sufficient and simpler to
+  // reason about than interleaved read cursors.
+  drainInFlight = false;
   orderStates = /* @__PURE__ */ new Map();
   disposed = false;
   constructor(options) {
+    const dedupCacheSize = typeof options.dedupCacheSize === "number" && Number.isFinite(options.dedupCacheSize) && options.dedupCacheSize >= 1 ? Math.floor(options.dedupCacheSize) : DEFAULT_DEDUP_CACHE_SIZE;
     this.options = {
       baseUrl: options.baseUrl ?? "wss://api.agentchat.me",
       reconnect: options.reconnect ?? true,
@@ -1331,6 +1403,7 @@ var RealtimeClient = class {
       client: options.client,
       onSequenceGap: options.onSequenceGap,
       autoDrainOnConnect: options.autoDrainOnConnect ?? Boolean(options.client),
+      dedupCacheSize,
       webSocket: options.webSocket
     };
   }
@@ -1359,15 +1432,24 @@ var RealtimeClient = class {
     const url = `${this.options.baseUrl}/v1/ws`;
     this.ws = new WebSocketCtor(url);
     this.authenticated = false;
+    this.ackMode = false;
+    this.helloTimeoutClose = false;
     this.ws.onopen = () => {
       try {
-        this.ws.send(JSON.stringify({ type: "hello", api_key: this.options.apiKey }));
+        this.ws.send(
+          JSON.stringify({
+            type: "hello",
+            api_key: this.options.apiKey,
+            capabilities: ["ack"]
+          })
+        );
       } catch (err) {
         this.emitError(err instanceof Error ? err : new ConnectionError("HELLO send failed"));
         return;
       }
       this.helloAckTimer = setTimeout(() => {
         this.emitError(new ConnectionError("HELLO ack timeout"));
+        this.helloTimeoutClose = true;
         try {
           this.ws?.close(1008, "HELLO ack timeout");
         } catch {
@@ -1384,6 +1466,8 @@ var RealtimeClient = class {
       if (!this.authenticated) {
         if (message.type === "hello.ok") {
           this.authenticated = true;
+          const caps = message.capabilities;
+          this.ackMode = Array.isArray(caps) && caps.includes("ack");
           this.reconnectAttempts = 0;
           if (this.helloAckTimer) {
             clearTimeout(this.helloAckTimer);
@@ -1396,7 +1480,11 @@ var RealtimeClient = class {
             }
           }
           if (this.options.autoDrainOnConnect && this.options.client) {
-            void this.drainOfflineEnvelopes();
+            this.drainOfflineEnvelopes().catch((err) => {
+              this.emitError(
+                err instanceof Error ? err : new ConnectionError("sync drain failed")
+              );
+            });
           }
         }
         return;
@@ -1416,6 +1504,9 @@ var RealtimeClient = class {
         this.helloAckTimer = null;
       }
       this.authenticated = false;
+      this.ackMode = false;
+      const selfClosedForHelloTimeout = this.helloTimeoutClose;
+      this.helloTimeoutClose = false;
       for (const handler of this.disconnectHandlers) {
         try {
           handler({ code: event.code, reason: event.reason, wasClean: event.wasClean });
@@ -1423,53 +1514,155 @@ var RealtimeClient = class {
         }
       }
       this.resetOrderStates();
+      if (TERMINAL_CLOSE_CODES.has(event.code) && !selfClosedForHelloTimeout) {
+        this.emitError(
+          new ConnectionError(
+            `WebSocket closed with terminal code ${event.code}${event.reason ? ` (${event.reason})` : ""}; the server rejected the session and auto-reconnect has stopped. Check the API key, then create a new RealtimeClient.`
+          )
+        );
+        return;
+      }
       this.scheduleReconnect();
     };
   }
   /**
    * 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.
+   *
+   * `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.
    *
-   * 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).
+   * 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.
    */
   async drainOfflineEnvelopes() {
     const client = this.options.client;
     if (!client) return;
-    while (true) {
+    if (this.drainInFlight) return;
+    this.drainInFlight = true;
+    try {
+      await this.runDrain(client);
+    } finally {
+      this.drainInFlight = false;
+    }
+  }
+  async runDrain(client) {
+    let after;
+    let acksFrozen = false;
+    while (!this.disposed) {
       let batch;
       try {
-        batch = await client.sync();
+        batch = await client.sync({ after, limit: SYNC_DRAIN_PAGE_SIZE });
       } catch (err) {
         this.emitError(err instanceof Error ? err : new ConnectionError("sync drain failed"));
         return;
       }
-      if (batch.envelopes.length === 0) return;
-      let highestDeliveryId = -1;
-      for (const env of batch.envelopes) {
-        if (env.delivery_id > highestDeliveryId) highestDeliveryId = env.delivery_id;
-        const wrapped = {
+      if (!Array.isArray(batch)) {
+        this.emitError(
+          new ConnectionError(
+            `sync drain: expected a bare array from /v1/messages/sync, got ${typeof batch}`
+          )
+        );
+        return;
+      }
+      if (this.disposed) return;
+      if (batch.length === 0) return;
+      const rows = [];
+      let invalidIndex = -1;
+      for (const [index, item] of batch.entries()) {
+        if (!isValidSyncRow(item)) {
+          invalidIndex = index;
+          break;
+        }
+        rows.push(item);
+      }
+      const envelopes = rows.map((row) => {
+        const envelope = {
           type: "message.new",
-          payload: env.message
+          payload: row
         };
-        this.processOrderedMessage(wrapped);
+        this.restDrainOrigin.add(envelope);
+        return envelope;
+      });
+      for (const envelope of envelopes) {
+        this.processOrderedMessage(envelope);
       }
-      if (highestDeliveryId >= 0) {
-        try {
-          await client.syncAck(highestDeliveryId);
-        } catch (err) {
-          this.emitError(err instanceof Error ? err : new ConnectionError("sync ack failed"));
-          return;
+      if (!acksFrozen) {
+        let ackCursor = null;
+        for (let i = 0; i < rows.length; i++) {
+          const row = rows[i];
+          const envelope = envelopes[i];
+          if (!row || !envelope) break;
+          const settlement = this.drainSettlements.get(envelope);
+          if (settlement) {
+            const ok = await settlement;
+            if (!ok) {
+              acksFrozen = true;
+              break;
+            }
+          } else if (this.isBufferedInOrderState(row)) {
+            acksFrozen = true;
+            break;
+          }
+          const deliveryId = row.delivery_id;
+          if (typeof deliveryId === "string" && deliveryId.length > 0) {
+            ackCursor = deliveryId;
+          }
         }
+        if (ackCursor !== null) {
+          try {
+            await client.syncAck(ackCursor);
+          } catch (err) {
+            this.emitError(err instanceof Error ? err : new ConnectionError("sync ack failed"));
+            return;
+          }
+        }
+      }
+      if (invalidIndex >= 0) {
+        this.emitError(
+          new ConnectionError(
+            `sync drain: row ${invalidIndex} failed validation \u2014 processed the ${rows.length}-row prefix and stopped; the ack cursor was not advanced past it`
+          )
+        );
+        return;
       }
-      if (batch.envelopes.length < 100) return;
+      if (batch.length < SYNC_DRAIN_PAGE_SIZE) return;
+      const nextAfter = lastDeliveryId(rows);
+      if (nextAfter === null) return;
+      after = nextAfter;
     }
   }
+  // True when a drain row is currently parked in the per-conversation
+  // out-of-order buffer (its dispatch is deferred to the gap-fill
+  // machinery — natural arrival, gap-fill fetch, or forced resolveGap).
+  isBufferedInOrderState(row) {
+    if (typeof row.seq !== "number") return false;
+    const state = this.orderStates.get(row.conversation_id);
+    return state !== void 0 && state.buffer.has(row.seq);
+  }
   scheduleReconnect() {
     if (this.disposed) return;
     if (!this.options.reconnect) return;
@@ -1586,11 +1779,115 @@ var RealtimeClient = class {
     }
   }
   dispatch(message) {
+    if (this.isMessageNew(message)) {
+      void this.dispatchMessageNew(message);
+      return;
+    }
     const handlers = this.handlers.get(message.type);
     if (!handlers) return;
     for (const handler of handlers) {
-      handler(message);
+      try {
+        const result = handler(message);
+        if (isThenable(result)) {
+          result.catch((err) => this.emitError(toError(err, message.type)));
+        }
+      } catch (err) {
+        this.emitError(toError(err, message.type));
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  dispatchMessageNew(message) {
+    const isDrainRow = this.restDrainOrigin.has(message);
+    const messageId = this.extractMessageId(message);
+    let settlement;
+    if (messageId !== null && this.dedupHit(messageId)) {
+      settlement = Promise.resolve(true);
+      if (!isDrainRow) this.sendAckFrame(messageId);
+    } else {
+      const handlers = this.handlers.get("message.new");
+      const pending = [];
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            const result = handler(message);
+            if (isThenable(result)) pending.push(result);
+          } catch (err) {
+            pending.push(Promise.reject(err));
+          }
+        }
+      }
+      settlement = Promise.allSettled(pending).then((outcomes) => {
+        let ok = true;
+        for (const outcome of outcomes) {
+          if (outcome.status === "rejected") {
+            ok = false;
+            this.emitError(toError(outcome.reason, "message.new"));
+          }
+        }
+        if (!ok) return false;
+        if (messageId !== null) {
+          this.dedupAdd(messageId);
+          if (!isDrainRow) this.sendAckFrame(messageId);
+        }
+        return true;
+      });
     }
+    if (isDrainRow) this.drainSettlements.set(message, settlement);
+    return settlement;
+  }
+  /**
+   * 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.
+   */
+  sendAckFrame(messageId) {
+    if (!this.ackMode) return;
+    if (!this.ws || this.ws.readyState !== 1 || !this.authenticated) return;
+    try {
+      this.ws.send(JSON.stringify({ type: "ack", message_id: messageId }));
+    } catch {
+    }
+  }
+  // Membership check that also refreshes recency on a hit (Set iteration
+  // order is insertion order, so delete + re-add moves the id to the back
+  // of the eviction queue).
+  dedupHit(messageId) {
+    if (!this.dedupSeen.has(messageId)) return false;
+    this.dedupSeen.delete(messageId);
+    this.dedupSeen.add(messageId);
+    return true;
+  }
+  dedupAdd(messageId) {
+    this.dedupSeen.delete(messageId);
+    this.dedupSeen.add(messageId);
+    while (this.dedupSeen.size > this.options.dedupCacheSize) {
+      const oldest = this.dedupSeen.values().next().value;
+      if (oldest === void 0) break;
+      this.dedupSeen.delete(oldest);
+    }
+  }
+  extractMessageId(message) {
+    const id = message.payload?.id;
+    return typeof id === "string" && id.length > 0 ? id : null;
   }
   isMessageNew(message) {
     return message.type === "message.new";