@astralform/js 4.1.0 → 4.3.0

package/README.md

@@ -61,9 +61,15 @@ const session = new ChatSession({
   userId: "user-123",       // Required — identifies the end user
   baseURL: "http://localhost:8000", // Optional — defaults to https://api.astralform.ai
   fetch: customFetch,       // Optional — custom fetch implementation
+  timeoutMs: 30_000,        // Optional — REST request deadline, defaults to 30s
 });
 ```
 
+`timeoutMs` bounds each REST request end to end — connect, headers, and the
+body read — rejecting with `ConnectionError` when it expires. File uploads and
+the SSE stream are exempt: both are long-running by design, and the stream
+carries its own `AbortSignal`.
+
 ## Events
 
 Subscribe to events with `.on()`, which returns an unsubscribe function. The SDK forwards a typed `ChatEvent` for every wire event — consumers build their own block / message state from the stream.

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   AstralformClient: () => AstralformClient,
   AstralformError: () => AstralformError,
   AuthenticationError: () => AuthenticationError,
+  CONVERSATION_PAGE_SIZE: () => CONVERSATION_PAGE_SIZE,
   ChatEventType: () => ChatEventType,
   ChatSession: () => ChatSession,
   ConnectionError: () => ConnectionError,
@@ -298,6 +299,7 @@ async function* streamJobSSE(options) {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
+var DEFAULT_TIMEOUT_MS = 3e4;
 function validateBaseURL(url) {
   const cleaned = url.replace(/\/+$/, "");
   try {
@@ -348,10 +350,11 @@ var AstralformClient = class {
     }
     this.baseURL = validateBaseURL(config.baseURL ?? DEFAULT_BASE_URL);
     this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
   }
   /**
    * Replace the current OIDC access token without reconstructing the client.
-   * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+   * Use after refreshing via the host app's own token manager.
    * Throws if the client was created in API-key mode.
    */
   updateAccessToken(accessToken) {
@@ -438,11 +441,48 @@ var AstralformClient = class {
       "Content-Type": "application/json"
     };
   }
+  /**
+   * Run one REST exchange under a single deadline covering connect, headers,
+   * AND the body read. The body read is the part that matters: `json()` used
+   * to sit outside every guard, so a response whose headers arrived but whose
+   * body stalled hung forever — silently stranding callers that await it
+   * (a stalled `getMessages` used to leave `StreamManager.restore()` parked
+   * before it ever fetched the events it renders from).
+   *
+   * The controller is created per request and is deliberately NOT the
+   * session's — that one means "the user cancelled this turn" and is null
+   * outside a live turn. Aborting frees the socket; the race guarantees a
+   * rejection even when an injected `fetch` ignores the signal.
+   */
+  async withDeadline(run) {
+    const controller = new AbortController();
+    const timedOut = () => new ConnectionError(`Request timed out after ${this.timeoutMs}ms`);
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(timedOut());
+      }, this.timeoutMs);
+    });
+    try {
+      return await Promise.race([run(controller.signal), deadline]);
+    } catch (err) {
+      if (controller.signal.aborted) throw timedOut();
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   async request(method, path, body) {
+    return this.withDeadline((signal) => this.send(method, path, body, signal));
+  }
+  /** Fetch + status handling. Always called inside `withDeadline`. */
+  async send(method, path, body, signal) {
     const response = await this.fetchFn(`${this.baseURL}${path}`, {
       method,
       headers: this.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal
     }).catch((err) => {
       throw new ConnectionError(
         err instanceof Error ? err.message : "Failed to connect"
@@ -451,13 +491,21 @@ var AstralformClient = class {
     await this.handleError(response);
     return response;
   }
+  // DO NOT refactor these back into `request()` + `.json()`. Parsing the body
+  // INSIDE the raced callback is the entire fix: `json()` outside the deadline
+  // is the original bug (headers arrive, body stalls, caller hangs forever).
+  // `request()` survives for `del()`, which never reads the body.
   async get(path) {
-    const response = await this.request("GET", path);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("GET", path, void 0, signal);
+      return await response.json();
+    });
   }
   async post(path, body) {
-    const response = await this.request("POST", path, body);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("POST", path, body, signal);
+      return await response.json();
+    });
   }
   async del(path) {
     await this.request("DELETE", path);
@@ -1231,6 +1279,7 @@ function translateWireEvent(wire) {
 // src/session.ts
 var SSE_MAX_RECONNECTS = 6;
 var TOOL_RESULT_MAX_RETRIES = 3;
+var CONVERSATION_PAGE_SIZE = 50;
 function sseReconnectDelayMs(attempt) {
   return Math.min(500 * 2 ** (attempt - 1), 5e3);
 }
@@ -1254,6 +1303,17 @@ var ChatSession = class {
     // State
     this.conversationId = null;
     this.conversations = [];
+    /**
+     * Whether another page of conversations may exist on the server.
+     *
+     * Inferred from the last page being full, since the list endpoint returns a
+     * bare array with no total. A total that happens to be an exact multiple of
+     * the page size therefore costs one extra empty request before this flips —
+     * cheaper than adding a count query to every list call.
+     */
+    this.hasMoreConversations = false;
+    /** True while ``loadMoreConversations`` is in flight. */
+    this.isLoadingConversations = false;
     this.messages = [];
     this.isStreaming = false;
     this.agentStatus = null;
@@ -1261,6 +1321,32 @@ var ChatSession = class {
     this.skills = [];
     this.enabledClientTools = /* @__PURE__ */ new Set();
     this.modelDisplayName = null;
+    /**
+     * Ids of conversations the SERVER has handed us, which is the paging offset.
+     *
+     * Deliberately not ``conversations.length``. That array also holds
+     * conversations created locally and unshifted on top (``createNewConversation``,
+     * and the auto-created conversation in ``consumeJobStream``), so using its
+     * length as the offset would over-count and silently skip a row of real
+     * history on the next page. Tracking ids rather than a counter also makes
+     * deletion self-correcting: removing a server-sourced conversation shifts
+     * every later page up by one, and dropping its id from this set is exactly
+     * that shift — while deleting a purely local one correctly changes nothing.
+     */
+    this.serverConversationIds = /* @__PURE__ */ new Set();
+    /**
+     * Bumped every time ``connect()`` re-seeds the conversation list.
+     *
+     * A ``loadMoreConversations`` request issued before a re-seed describes the
+     * OLD paging state, so applying its response afterwards both appends the
+     * wrong rows and corrupts the offset. Concretely: with 100 rows held, an
+     * offset-100 response landing after a reconnect has reset to rows 0-49 would
+     * append rows 100-149 — a 50-row hole — and leave the id set at 100, so every
+     * later page re-requests offset 100 and never advances again. The generation
+     * is captured before the await and rechecked after, so a superseded response
+     * is discarded instead.
+     */
+    this.conversationsGeneration = 0;
     // Minimal in-session accumulation for the assistant message record.
     // Only top-level ``text`` blocks contribute; subagent / tool output
     // is tracked by the consumer's own block store.
@@ -1300,7 +1386,7 @@ var ChatSession = class {
   async connect() {
     const [status, conversations, agents, skills] = await Promise.allSettled([
       this.client.getAgentStatus(),
-      this.client.getConversations(),
+      this.client.getConversations(CONVERSATION_PAGE_SIZE),
       this.client.getAgents().catch(() => []),
       this.client.getSkills().catch(() => [])
     ]);
@@ -1308,7 +1394,12 @@ var ChatSession = class {
       this.agentStatus = status.value;
     }
     if (conversations.status === "fulfilled") {
+      this.conversationsGeneration++;
       this.conversations = conversations.value;
+      this.serverConversationIds = new Set(
+        conversations.value.map((c) => c.id)
+      );
+      this.hasMoreConversations = conversations.value.length === CONVERSATION_PAGE_SIZE;
     }
     if (agents.status === "fulfilled") {
       this.agents = agents.value;
@@ -1767,12 +1858,69 @@ var ChatSession = class {
       eventsResult.status === "fulfilled" ? eventsResult.value : []
     );
   }
+  /**
+   * Append the next page of conversation history to ``conversations``.
+   *
+   * The list is ordered ``updated_at DESC`` and paged by offset, so a
+   * conversation bumped to the top mid-scroll can surface again in a later
+   * page; ids already held are dropped rather than duplicated. Returns only
+   * the conversations actually appended, which may be empty even on a full
+   * page. Rejects on network failure with ``hasMoreConversations`` still true,
+   * so the caller can retry.
+   *
+   * KNOWN LIMITATION — offset paging is only stable while the prefix already
+   * consumed stays put. The offset tracking here corrects for perturbations
+   * THIS session causes (local unshifts, ``deleteConversation``), but not for
+   * ones it never sees:
+   *
+   * - a conversation this session hasn't loaded yet is bumped to the top (a
+   *   headless routine or another device posting to it), pushing the whole
+   *   list down — it lands inside the consumed prefix, which no later offset
+   *   revisits;
+   * - a conversation is deleted from another tab/device, shrinking the list so
+   *   the next offset lands one row too far in.
+   *
+   * Each perturbation costs at most one conversation off the sidebar, and only
+   * until the next ``connect()`` — that re-seeds page 1 and resets the paging
+   * state, so a reload or reconnect always recovers it. Nothing is lost
+   * server-side. Both cases are pinned by tests in
+   * ``tests/conversation-paging.test.ts``.
+   *
+   * Closing the gap properly needs a stable server cursor (keyset paging on
+   * ``(updated_at, id)``) rather than a raw offset, which is a backend change —
+   * tracking ids client-side cannot discover a row that moved into a region
+   * already scanned.
+   */
+  async loadMoreConversations() {
+    if (this.isLoadingConversations || !this.hasMoreConversations) return [];
+    this.isLoadingConversations = true;
+    const generation = this.conversationsGeneration;
+    try {
+      const page = await this.client.getConversations(
+        CONVERSATION_PAGE_SIZE,
+        this.serverConversationIds.size
+      );
+      if (generation !== this.conversationsGeneration) return [];
+      this.hasMoreConversations = page.length === CONVERSATION_PAGE_SIZE;
+      const fresh = page.filter((c) => !this.serverConversationIds.has(c.id));
+      for (const c of page) this.serverConversationIds.add(c.id);
+      const known = new Set(this.conversations.map((c) => c.id));
+      const appended = fresh.filter((c) => !known.has(c.id));
+      this.conversations.push(...appended);
+      return appended;
+    } finally {
+      this.isLoadingConversations = false;
+    }
+  }
   async deleteConversation(id) {
     try {
       await this.client.deleteConversation(id);
     } catch {
     }
     await this.storage.deleteConversation(id);
+    if (this.serverConversationIds.delete(id)) {
+      this.conversationsGeneration++;
+    }
     this.conversations = this.conversations.filter((c) => c.id !== id);
     if (this.conversationId === id) {
       this.conversationId = null;
@@ -2158,6 +2306,7 @@ function parseEmbeddedResource(value) {
   AstralformClient,
   AstralformError,
   AuthenticationError,
+  CONVERSATION_PAGE_SIZE,
   ChatEventType,
   ChatSession,
   ConnectionError,