@astralform/js 4.2.0 → 4.3.0

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,
@@ -353,7 +354,7 @@ var AstralformClient = class {
   }
   /**
    * 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) {
@@ -1278,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);
 }
@@ -1301,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;
@@ -1308,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.
@@ -1347,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(() => [])
     ]);
@@ -1355,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;
@@ -1814,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;
@@ -2205,6 +2306,7 @@ function parseEmbeddedResource(value) {
   AstralformClient,
   AstralformError,
   AuthenticationError,
+  CONVERSATION_PAGE_SIZE,
   ChatEventType,
   ChatSession,
   ConnectionError,