@cubos/agent-sdk 0.0.1142885 → 0.0.1143127

package/README.md

@@ -439,13 +439,28 @@ Transient stream failures do not end a subscription: the SDK reconnects with
 exponential backoff and reports them through `onError`, for logging or a
 "reconnecting" hint.
 
-Two failures that look like silence get handled rather than reported. A **401**
-buys one immediate reconnect with a forced token refresh — a short-lived token
-expiring under a stream that outlives it is the expected case, not a
-misconfiguration — and only a second rejection is final. A connection that stops
-sending **anything**, keep-alive comments included, is dropped and reopened after
-`idleTimeoutMs` (30s, twice the server's keep-alive interval): a half-open socket
-otherwise leaves the reader waiting forever with no error to react to.
+Three failures that look like silence get handled rather than reported. A
+**401** buys one immediate reconnect with a forced token refresh — a short-lived
+token expiring under a stream that outlives it is the expected case, not a
+misconfiguration — and only a second rejection is final. A **429** — the per-user
+cap on open streams, which one tab too many reaches — waits out the server's
+`Retry-After` and reconnects, since the cap clears the moment any tab closes. A
+connection that stops sending **anything**, keep-alive comments included, is
+dropped and reopened after `idleTimeoutMs` (30s, twice the server's keep-alive
+interval): a half-open socket otherwise leaves the reader waiting forever with
+no error to react to.
+
+And a stream has to **prove itself before it is trusted**. The server sends a
+frame on every connect, so until a connection has delivered one — and again
+whenever one ends — `subscribe` polls the same log every 3s through the `after`
+cursor, and the conversation row with it. On a healthy network the frame lands
+inside the first poll's 2s grace and no poll is ever made. On a network whose
+proxy holds a `text/event-stream` response until it ends (corporate TLS
+inspection, some antivirus — Chrome negotiating HTTP/1.1 with a host that speaks
+h2 is the tell), every connection sits silent until something cuts it, and the
+reply used to show up only after a page reload; now it shows up within 3s. The
+same rule covers the gap between a drop and the reconnect that follows. One
+cursor serves both paths, so nothing is delivered twice.
 
 What remains final — a 4xx that survived the refresh, a deleted conversation —
 closes the subscription for good and fires **`onFatal`** (`onError` sees it too).

package/dist/client.d.ts

@@ -249,9 +249,10 @@ export declare class AgentClient {
      * the page before this one, and `latestChangeSeq` to start a subscription
      * from here instead of replaying everything.
      *
-     * `hasOlder` is false only when the server returned fewer events than asked
-     * for — the one honest signal that the log is exhausted, since a page can
-     * hold events that are not messages.
+     * `hasOlder` says whether any event precedes this page, which is not the
+     * same as whether the page was full: a page can hold events that are not
+     * messages, and a page shorter than asked for is what the server's own cap
+     * on `limit` returns for a large request.
      */
     /**
      * One page of the conversation's **event log**, oldest-first — the same rows
@@ -423,9 +424,23 @@ export declare class AgentClient {
      * to skip that backfill and receive only what is new; that is what makes
      * paging backwards meaningful, since otherwise the stream re-delivers the
      * history you just paged through.
+     *
+     * **A stream has to prove itself before it is trusted.** Until a connection
+     * delivers its first frame — and again whenever one ends — the same log is
+     * polled every `STREAM_POLL_INTERVAL_MS` with the `after` cursor, and the
+     * conversation row with it. On a healthy network the server's first frame
+     * arrives well inside the first poll's grace and no poll is ever made. On a
+     * network whose proxy holds a `text/event-stream` response until it ends —
+     * which it never does — every connection sits silent until something cuts
+     * it, and without this the reply only ever showed up after a page reload.
+     * The same rule covers the gap between a drop and the reconnect that follows.
      */
     subscribe(id: string, handlers: ConversationHandlers, opts?: {
         since?: number;
+        /** Overrides `STREAM_POLL_GRACE_MS` for this subscription. */
+        pollGraceMs?: number;
+        /** Overrides `STREAM_POLL_INTERVAL_MS` for this subscription. */
+        pollIntervalMs?: number;
     }): ConversationSubscription;
     /** Live chat list. Fires per conversation whose activity advances; upsert by
      * id and re-sort by `lastActivityAt` locally. */

package/dist/errors.d.ts

@@ -50,3 +50,10 @@ export declare class AgentNetworkError extends AgentError {
     constructor(message: string, cause: unknown, timedOut?: boolean);
 }
 export declare function raiseForStatus(res: Response, fallback: string): Promise<void>;
+/**
+ * Milliseconds from a `Retry-After`, which is either a delta in seconds or an
+ * HTTP date. Returns null when absent or unusable, so the caller can decide not
+ * to retry rather than guess an interval. Shared by the request retry and the
+ * stream reconnect, which honour the same header from the same limiter.
+ */
+export declare function parseRetryAfter(header: string | null): number | null;

package/dist/generated/schema.d.ts

@@ -4995,10 +4995,14 @@ export interface paths {
         /**
          * List conversation events
          * @description Returns one page of the conversation's append-only event log in `seq` ascending order. Discarded (rolled-back) events are filtered out; use `events/stream` for the live delta view that surfaces them.
+         *
+         *     With `after`, the page is instead the delta the stream would have sent: every row whose `change_seq` is past the cursor, in `change_seq` order, discarded and tentative rows included so a client can apply them exactly as it applies stream frames. This is how a client behind a proxy that buffers `text/event-stream` keeps up — poll it with the newest `change_seq` held and merge, the same loop the stream runs on its own reconnect. `before` and `after` cannot be combined (400).
          */
         get: {
             parameters: {
                 query?: {
+                    /** @description Return events with `change_seq > after`, oldest change first — the stream's delta, as a page. Excludes `before`. */
+                    after?: number;
                     /** @description Return events with `seq < before`; omit for the most recent page. */
                     before?: number;
                     /** @description Page size; clamped to 1..=200, default 50. */
@@ -5023,6 +5027,12 @@ export interface paths {
                         "application/json": components["schemas"]["ConversationEvent"][];
                     };
                 };
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 401: {
                     headers: {
                         [name: string]: unknown;

package/dist/index.js

@@ -76,6 +76,17 @@ async function raiseForStatus(res, fallback) {
   const base = DEFAULT_MESSAGES[res.status] ?? fallback;
   throw new AgentApiError(detail ? `${base} (${detail.slice(0, 500)})` : base, res.status, res.headers.get("x-request-id"), detail);
 }
+function parseRetryAfter(header) {
+  if (!header)
+    return null;
+  const seconds = Number(header.trim());
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds * 1000);
+  const date = Date.parse(header);
+  if (Number.isNaN(date))
+    return null;
+  return Math.max(0, date - Date.now());
+}
 
 // src/sse.ts
 var MAX_BACKOFF_MS = 30000;
@@ -98,11 +109,12 @@ class SseIdleTimeout extends Error {
 async function readSse(opts) {
   const doFetch = opts.fetchImpl ?? globalThis.fetch;
   const idleMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-  let lastEventId = opts.lastEventId;
+  const cursor = opts.cursor ?? { lastEventId: opts.lastEventId };
   let attempt = 0;
   let refreshing = false;
   while (!opts.signal.aborted) {
     let madeProgress = false;
+    let retryAfterMs = null;
     const connection = new AbortController;
     const unlink = forward(opts.signal, connection);
     let idleTimer;
@@ -121,8 +133,8 @@ async function readSse(opts) {
         ...await opts.headers?.({ forceRefresh: refreshing }),
         Accept: "text/event-stream"
       };
-      if (lastEventId !== undefined)
-        headers["Last-Event-ID"] = lastEventId;
+      if (cursor.lastEventId !== undefined)
+        headers["Last-Event-ID"] = cursor.lastEventId;
       armIdle();
       const res = await doFetch(opts.url, { headers, signal: connection.signal });
       if (opts.signal.aborted)
@@ -136,6 +148,10 @@ async function readSse(opts) {
           refreshing = true;
           continue;
         }
+        if (res.status === 429) {
+          retryAfterMs = Math.min(MAX_BACKOFF_MS, parseRetryAfter(res.headers.get("retry-after")) ?? MAX_BACKOFF_MS);
+          await raiseForStatus(res, `Could not open ${opts.url}.`);
+        }
         if (res.status >= 400 && res.status < 500) {
           await raiseForStatus(res, `Could not open ${opts.url}.`).catch((err) => {
             throw new Fatal(err);
@@ -149,7 +165,7 @@ async function readSse(opts) {
         if (parsed === null)
           continue;
         if (parsed.id !== null)
-          lastEventId = parsed.id;
+          cursor.lastEventId = parsed.id;
         opts.onEvent(parsed.data, parsed.event);
         madeProgress = true;
       }
@@ -165,12 +181,13 @@ async function readSse(opts) {
       clearTimeout(idleTimer);
       unlink();
       connection.abort();
+      opts.onClose?.();
     }
     if (opts.signal.aborted)
       return;
     if (madeProgress)
       attempt = 0;
-    const delayMs = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt);
+    const delayMs = retryAfterMs ?? Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt);
     attempt += 1;
     await sleep(delayMs, opts.signal);
   }
@@ -250,17 +267,6 @@ function forward(outer, child) {
 var DEFAULT_TIMEOUT_MS = 30000;
 var DEFAULT_MAX_RETRIES = 2;
 var MAX_RETRY_WAIT_MS = 20000;
-function parseRetryAfter(header) {
-  if (!header)
-    return null;
-  const seconds = Number(header.trim());
-  if (Number.isFinite(seconds))
-    return Math.max(0, seconds * 1000);
-  const date = Date.parse(header);
-  if (Number.isNaN(date))
-    return null;
-  return Math.max(0, date - Date.now());
-}
 function sleep2(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -1406,6 +1412,12 @@ function fold(a, b) {
 
 // src/client.ts
 var MAX_IMAGES_PER_MESSAGE = 10;
+function hasEventsBefore(oldestSeq) {
+  return oldestSeq !== null && oldestSeq > 1;
+}
+var EVENTS_MAX_LIMIT = 200;
+var STREAM_POLL_GRACE_MS = 2000;
+var STREAM_POLL_INTERVAL_MS = 3000;
 
 class AgentClient {
   #transport;
@@ -1483,7 +1495,7 @@ class AgentClient {
       const page = await this.#messagePage(id, { limit, before, signal: opts.signal });
       for (let i = page.messages.length - 1;i >= 0; i--)
         yield page.messages[i];
-      if (page.eventCount < limit || page.oldestSeq === null)
+      if (page.oldestSeq === null || !hasEventsBefore(page.oldestSeq))
         return;
       before = page.oldestSeq;
     }
@@ -1641,7 +1653,7 @@ class AgentClient {
       events: page.events,
       oldestSeq: page.oldestSeq,
       latestChangeSeq: page.latestChangeSeq,
-      hasOlder: page.eventCount === limit
+      hasOlder: hasEventsBefore(page.oldestSeq)
     };
   }
   async listMessagesPage(id, opts = {}) {
@@ -1654,7 +1666,7 @@ class AgentClient {
       lastTurnDoneSeq: page.lastTurnDoneSeq,
       oldestSeq: page.oldestSeq,
       latestChangeSeq: page.latestChangeSeq,
-      hasOlder: page.eventCount >= limit
+      hasOlder: hasEventsBefore(page.oldestSeq)
     };
   }
   async sendMessage(id, content, signal) {
@@ -1772,66 +1784,154 @@ class AgentClient {
   }
   subscribe(id, handlers, opts = {}) {
     const controller = new AbortController;
+    const signal = controller.signal;
+    const graceMs = opts.pollGraceMs ?? STREAM_POLL_GRACE_MS;
+    const intervalMs = opts.pollIntervalMs ?? STREAM_POLL_INTERVAL_MS;
     const streamedArgs = new Map;
+    const cursor = { lastEventId: opts.since === undefined ? undefined : String(opts.since) };
+    let delivered = opts.since ?? 0;
+    const deliverEvent = (raw) => {
+      if (raw.change_seq <= delivered)
+        return;
+      delivered = raw.change_seq;
+      handlers.onEvent?.(raw);
+      const message = toMessage(raw);
+      if (message)
+        handlers.onMessage?.(message);
+      const todos = toTodos(raw);
+      if (todos)
+        handlers.onTodos?.(todos, raw.seq);
+      const turnDone = toTurnDone(raw);
+      if (turnDone !== null)
+        handlers.onTurnDone?.(turnDone);
+      const call = toClientToolCall(raw);
+      if (call)
+        handlers.onClientToolCall?.(call);
+      for (const call2 of toToolCallArguments(raw)) {
+        streamedArgs.set(call2.toolCallId, call2.arguments);
+      }
+      const activity = toToolActivity(raw);
+      if (activity)
+        handlers.onToolActivity?.(withToolArguments(activity, streamedArgs));
+      handlers.onCursor?.(raw.change_seq);
+    };
+    const wantsEvents = Boolean(handlers.onMessage || handlers.onEvent || handlers.onTodos || handlers.onClientToolCall || handlers.onToolActivity || handlers.onTurnDone || handlers.onActivity || handlers.onOpen);
+    const wantsMeta = Boolean(handlers.onConversation);
     this.#base().then((base) => {
-      if (controller.signal.aborted)
+      if (signal.aborted)
         return;
-      if (handlers.onMessage || handlers.onEvent || handlers.onTodos || handlers.onClientToolCall || handlers.onToolActivity || handlers.onTurnDone || handlers.onActivity || handlers.onOpen) {
+      let eventsProven = !wantsEvents;
+      let metaProven = !wantsMeta;
+      let ended = false;
+      let pollTimer;
+      let polling = false;
+      let polledStatus;
+      let polledRow;
+      const poll = async () => {
+        pollTimer = undefined;
+        if (signal.aborted || ended || polling)
+          return;
+        if (eventsProven && metaProven)
+          return;
+        polling = true;
+        try {
+          const row = await this.#transport.request("GET", `${base}/${id}`, {
+            signal
+          });
+          if (!eventsProven) {
+            for (;; ) {
+              const rows = await this.#transport.request("GET", `${base}/${id}/events`, { query: { after: delivered, limit: EVENTS_MAX_LIMIT }, signal });
+              if (signal.aborted)
+                return;
+              for (const raw of rows) {
+                deliverEvent(raw);
+                cursor.lastEventId = String(delivered);
+              }
+              if (rows.length < EVENTS_MAX_LIMIT)
+                break;
+            }
+            const status = `${row.is_processing}:${row.has_pending_turn}`;
+            if (status !== polledStatus) {
+              polledStatus = status;
+              handlers.onActivity?.(toTurnStatus(row));
+            }
+          }
+          if (!metaProven) {
+            const serialized = JSON.stringify(row);
+            if (serialized !== polledRow) {
+              polledRow = serialized;
+              handlers.onConversation?.(toConversation(row));
+            }
+          }
+        } catch (err) {
+          if (!signal.aborted)
+            handlers.onError?.(err);
+        } finally {
+          polling = false;
+          schedulePoll(intervalMs);
+        }
+      };
+      const schedulePoll = (delayMs) => {
+        if (signal.aborted || ended || pollTimer !== undefined)
+          return;
+        if (eventsProven && metaProven)
+          return;
+        pollTimer = setTimeout(() => void poll(), delayMs);
+      };
+      const stopPolling = () => {
+        clearTimeout(pollTimer);
+        pollTimer = undefined;
+      };
+      signal.addEventListener("abort", stopPolling, { once: true });
+      const fatal = (err) => {
+        ended = true;
+        stopPolling();
+        handlers.onError?.(err);
+        handlers.onFatal?.(err);
+      };
+      if (wantsEvents) {
         readSse({
           url: this.#transport.url(`${base}/${id}/events/stream`),
           event: ["conversation_event", "conversation_status"],
-          lastEventId: opts.since === undefined ? undefined : String(opts.since),
+          cursor,
           headers: ({ forceRefresh }) => this.#transport.streamHeaders(forceRefresh),
           fetchImpl: this.#transport.fetchImpl,
-          signal: controller.signal,
+          signal,
           onError: handlers.onError,
           onOpen: handlers.onOpen,
+          onClose: () => {
+            eventsProven = false;
+            schedulePoll(graceMs);
+          },
           onEvent: (frame, name) => {
+            eventsProven = true;
             if (name === "conversation_status") {
               handlers.onActivity?.(toTurnStatus(frame));
               return;
             }
-            const raw = frame;
-            handlers.onEvent?.(raw);
-            const message = toMessage(raw);
-            if (message)
-              handlers.onMessage?.(message);
-            const todos = toTodos(raw);
-            if (todos)
-              handlers.onTodos?.(todos, raw.seq);
-            const turnDone = toTurnDone(raw);
-            if (turnDone !== null)
-              handlers.onTurnDone?.(turnDone);
-            const call = toClientToolCall(raw);
-            if (call)
-              handlers.onClientToolCall?.(call);
-            for (const call2 of toToolCallArguments(raw)) {
-              streamedArgs.set(call2.toolCallId, call2.arguments);
-            }
-            const activity = toToolActivity(raw);
-            if (activity)
-              handlers.onToolActivity?.(withToolArguments(activity, streamedArgs));
-            handlers.onCursor?.(raw.change_seq);
+            deliverEvent(frame);
           }
-        }).catch((err) => {
-          handlers.onError?.(err);
-          handlers.onFatal?.(err);
-        });
+        }).catch(fatal);
       }
-      if (handlers.onConversation) {
+      if (wantsMeta) {
         readSse({
           url: this.#transport.url(`${base}/${id}/meta/stream`),
           event: "conversation_meta",
           headers: ({ forceRefresh }) => this.#transport.streamHeaders(forceRefresh),
           fetchImpl: this.#transport.fetchImpl,
-          signal: controller.signal,
+          signal,
           onError: handlers.onError,
-          onEvent: (raw) => handlers.onConversation?.(toConversation(raw))
-        }).catch((err) => {
-          handlers.onError?.(err);
-          handlers.onFatal?.(err);
-        });
+          onClose: () => {
+            metaProven = false;
+            schedulePoll(graceMs);
+          },
+          onEvent: (raw) => {
+            metaProven = true;
+            handlers.onConversation?.(toConversation(raw));
+          }
+        }).catch(fatal);
       }
+      schedulePoll(graceMs);
     });
     return { close: () => controller.abort() };
   }
@@ -1878,5 +1978,5 @@ export {
   AgentApiError
 };
 
-//# debugId=641C44370747442A64756E2164756E21
+//# debugId=F147527891A76CE064756E2164756E21
 //# sourceMappingURL=index.js.map