@cubos/agent-sdk 0.0.1140467 → 0.0.1140658

package/README.md

@@ -437,7 +437,20 @@ api_keys are exempt from all of this.
 
 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. A 4xx on a stream is final and closes it.
+"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.
+
+What remains final — a 4xx that survived the refresh, a deleted conversation —
+closes the subscription for good and fires **`onFatal`** (`onError` sees it too).
+That is the one a UI has to surface: everything still renders, and nothing will
+ever arrive again.
 
 ## Also in the package
 

package/dist/client.d.ts

@@ -81,9 +81,20 @@ export interface ConversationHandlers {
      * as `since` on the next connect — that is what lets a cache pick up where it
      * left off instead of replaying. */
     onCursor?: (changeSeq: number) => void;
-    /** Transient stream failures. The SDK is already reconnecting; this is for
-     * logging or a "reconnecting…" hint, not for recovery. */
+    /** Every stream failure, including the one that ends the subscription. The
+     * SDK is already reconnecting for all but that one, so this is for logging or
+     * a "reconnecting…" hint — watch `onFatal` for the end. */
     onError?: (err: unknown) => void;
+    /**
+     * The subscription has stopped and will not come back: the credential was
+     * rejected twice (once after a forced refresh), the conversation is gone, or
+     * the server refused the stream outright. Fires at most once.
+     *
+     * Separate from `onError` because the two need opposite treatment — a failed
+     * reconnect is normal and shows at most a hint, while this is a dead view
+     * that has to tell the user, and only a fresh `subscribe` revives it.
+     */
+    onFatal?: (err: unknown) => void;
 }
 /** What `loadHistory` resolves to: a `MessagePage` plus where it came from. */
 export interface HistoryStart {
@@ -105,6 +116,8 @@ export interface HistoryStart {
 export interface ListHandlers {
     onConversation: (conversation: Conversation) => void;
     onError?: (err: unknown) => void;
+    /** As on `ConversationHandlers`: the stream is gone for good. */
+    onFatal?: (err: unknown) => void;
 }
 export declare class AgentClient {
     #private;

package/dist/http.d.ts

@@ -27,8 +27,10 @@ interface RequestOptions {
 export interface Transport {
     request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
     fetchRaw(method: string, path: string, opts?: RequestOptions): Promise<Response>;
-    /** Headers for a stream connect, refreshed per (re)connect attempt. */
-    streamHeaders(): Promise<Record<string, string>>;
+    /** Headers for a stream connect, refreshed per (re)connect attempt.
+     * `forceRefresh` is the stream's counterpart to the 401 retry `request` does
+     * on its own: a `getToken` that caches must mint a new one when it is set. */
+    streamHeaders(forceRefresh?: boolean): Promise<Record<string, string>>;
     url(path: string, query?: RequestOptions["query"]): string;
     fetchImpl: FetchLike;
 }

package/dist/index.d.ts

@@ -11,6 +11,6 @@ export type { Auth, TokenSource, Transport } from "./http.js";
 export { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS } from "./http.js";
 export { mergeToolActivities, mergeVoiceMessages } from "./mapping.js";
 export type { Schemas } from "./schemas.js";
-export type { FetchLike } from "./sse.js";
-export { readSse } from "./sse.js";
+export type { FetchLike, SseOptions } from "./sse.js";
+export { DEFAULT_IDLE_TIMEOUT_MS, readSse, SseIdleTimeout } from "./sse.js";
 export type { Activity, Attachment, AttachmentKind, Block, ClientToolCall, Conversation, ConversationEvent, CreateConversationOptions, EnabledComponents, EventPage, Identity, ListConversationsOptions, Message, MessagePage, MessageRole, Page, PlanSnapshot, Todo, TodoStatus, ToolActivity, WorkspaceDir, WorkspaceEntry, } from "./types.js";

package/dist/index.js

@@ -79,6 +79,7 @@ async function raiseForStatus(res, fallback) {
 
 // src/sse.ts
 var MAX_BACKOFF_MS = 30000;
+var DEFAULT_IDLE_TIMEOUT_MS = 30000;
 
 class Fatal extends Error {
   cause;
@@ -87,25 +88,54 @@ class Fatal extends Error {
     this.cause = cause;
   }
 }
+
+class SseIdleTimeout extends Error {
+  constructor(url, ms) {
+    super(`Stream ${url} sent nothing for ${ms}ms — reconnecting.`);
+    this.name = "SseIdleTimeout";
+  }
+}
 async function readSse(opts) {
   const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const idleMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   let lastEventId = opts.lastEventId;
   let attempt = 0;
+  let refreshing = false;
   while (!opts.signal.aborted) {
     let madeProgress = false;
+    const connection = new AbortController;
+    const unlink = forward(opts.signal, connection);
+    let idleTimer;
+    let wentIdle = false;
+    const armIdle = () => {
+      if (idleMs <= 0)
+        return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        wentIdle = true;
+        connection.abort();
+      }, idleMs);
+    };
     try {
       const headers = {
-        ...await opts.headers?.(),
+        ...await opts.headers?.({ forceRefresh: refreshing }),
         Accept: "text/event-stream"
       };
       if (lastEventId !== undefined)
         headers["Last-Event-ID"] = lastEventId;
-      const res = await doFetch(opts.url, { headers, signal: opts.signal });
+      armIdle();
+      const res = await doFetch(opts.url, { headers, signal: connection.signal });
       if (opts.signal.aborted)
         return;
-      if (res.ok && res.body)
+      if (res.ok && res.body) {
+        refreshing = false;
         opts.onOpen?.();
+      }
       if (!res.ok || !res.body) {
+        if (res.status === 401 && opts.headers && !refreshing) {
+          refreshing = true;
+          continue;
+        }
         if (res.status >= 400 && res.status < 500) {
           await raiseForStatus(res, `Could not open ${opts.url}.`).catch((err) => {
             throw new Fatal(err);
@@ -114,7 +144,7 @@ async function readSse(opts) {
         }
         throw new Error(`stream open failed with HTTP ${res.status}`);
       }
-      for await (const frame of frames(res.body, opts.signal)) {
+      for await (const frame of frames(res.body, connection.signal, armIdle)) {
         const parsed = parseFrame(frame, opts.event);
         if (parsed === null)
           continue;
@@ -123,12 +153,18 @@ async function readSse(opts) {
         opts.onEvent(parsed.data, parsed.event);
         madeProgress = true;
       }
+      if (wentIdle)
+        throw new SseIdleTimeout(opts.url, idleMs);
     } catch (err) {
       if (opts.signal.aborted)
         return;
       if (err instanceof Fatal)
         throw err.cause;
-      opts.onError?.(err);
+      opts.onError?.(wentIdle ? new SseIdleTimeout(opts.url, idleMs) : err);
+    } finally {
+      clearTimeout(idleTimer);
+      unlink();
+      connection.abort();
     }
     if (opts.signal.aborted)
       return;
@@ -139,7 +175,7 @@ async function readSse(opts) {
     await sleep(delayMs, opts.signal);
   }
 }
-async function* frames(body, signal) {
+async function* frames(body, signal, onRead) {
   const reader = body.getReader();
   const decoder = new TextDecoder;
   let buffer = "";
@@ -148,6 +184,7 @@ async function* frames(body, signal) {
       const { value, done } = await reader.read();
       if (done)
         return;
+      onRead();
       buffer += decoder.decode(value, { stream: true });
       for (;; ) {
         const sep = buffer.indexOf(`
@@ -200,6 +237,14 @@ function sleep(ms, signal) {
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
+function forward(outer, child) {
+  const onAbort = () => child.abort();
+  if (outer.aborted)
+    child.abort();
+  else
+    outer.addEventListener("abort", onAbort, { once: true });
+  return () => outer.removeEventListener("abort", onAbort);
+}
 
 // src/http.ts
 var DEFAULT_TIMEOUT_MS = 30000;
@@ -326,8 +371,8 @@ function createTransport(baseUrl, auth, fetchImpl = globalThis.fetch, timeoutMs
   return {
     fetchImpl,
     url: (path, query) => `${root}${path}${buildQuery(query)}`,
-    async streamHeaders() {
-      return { Authorization: await authHeader(false) };
+    async streamHeaders(forceRefresh = false) {
+      return { Authorization: await authHeader(forceRefresh) };
     },
     fetchRaw: once,
     async request(method, path, opts = {}) {
@@ -508,7 +553,7 @@ function serveClientTools(t, conversationPath, conversationId, options) {
     await readSse({
       url: t.url(`${base}/events/stream`),
       event: "conversation_event",
-      headers: () => t.streamHeaders(),
+      headers: ({ forceRefresh }) => t.streamHeaders(forceRefresh),
       fetchImpl: t.fetchImpl,
       signal: controller.signal,
       onError: options.onError,
@@ -1736,7 +1781,7 @@ class AgentClient {
           url: this.#transport.url(`${base}/${id}/events/stream`),
           event: ["conversation_event", "conversation_status"],
           lastEventId: opts.since === undefined ? undefined : String(opts.since),
-          headers: () => this.#transport.streamHeaders(),
+          headers: ({ forceRefresh }) => this.#transport.streamHeaders(forceRefresh),
           fetchImpl: this.#transport.fetchImpl,
           signal: controller.signal,
           onError: handlers.onError,
@@ -1768,18 +1813,24 @@ class AgentClient {
               handlers.onToolActivity?.(withToolArguments(activity, streamedArgs));
             handlers.onCursor?.(raw.change_seq);
           }
-        }).catch((err) => handlers.onError?.(err));
+        }).catch((err) => {
+          handlers.onError?.(err);
+          handlers.onFatal?.(err);
+        });
       }
       if (handlers.onConversation) {
         readSse({
           url: this.#transport.url(`${base}/${id}/meta/stream`),
           event: "conversation_meta",
-          headers: () => this.#transport.streamHeaders(),
+          headers: ({ forceRefresh }) => this.#transport.streamHeaders(forceRefresh),
           fetchImpl: this.#transport.fetchImpl,
           signal: controller.signal,
           onError: handlers.onError,
           onEvent: (raw) => handlers.onConversation?.(toConversation(raw))
-        }).catch((err) => handlers.onError?.(err));
+        }).catch((err) => {
+          handlers.onError?.(err);
+          handlers.onFatal?.(err);
+        });
       }
     });
     return { close: () => controller.abort() };
@@ -1792,12 +1843,15 @@ class AgentClient {
       readSse({
         url: this.#transport.url(`${base}/stream`, { origin: "interactive" }),
         event: "conversation",
-        headers: () => this.#transport.streamHeaders(),
+        headers: ({ forceRefresh }) => this.#transport.streamHeaders(forceRefresh),
         fetchImpl: this.#transport.fetchImpl,
         signal: controller.signal,
         onError: handlers.onError,
         onEvent: (raw) => handlers.onConversation(toConversation(raw))
-      }).catch((err) => handlers.onError?.(err));
+      }).catch((err) => {
+        handlers.onError?.(err);
+        handlers.onFatal?.(err);
+      });
     });
     return { close: () => controller.abort() };
   }
@@ -1812,9 +1866,11 @@ export {
   mergeToolActivities,
   createUserClient,
   createAdminClient,
+  SseIdleTimeout,
   MemoryConversationCache,
   DEFAULT_TIMEOUT_MS,
   DEFAULT_MAX_RETRIES,
+  DEFAULT_IDLE_TIMEOUT_MS,
   AgentNetworkError,
   AgentError,
   AgentConfigError,
@@ -1822,5 +1878,5 @@ export {
   AgentApiError
 };
 
-//# debugId=135CEC176CA70F7564756E2164756E21
+//# debugId=609F372BC6CA145264756E2164756E21
 //# sourceMappingURL=index.js.map