@astralform/js 4.2.0 → 4.4.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;
@@ -1776,11 +1820,16 @@ var ChatSession = class {
    * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
    * so leading with the prompt keeps the turn in order.
    */
-  replayTurn(id, events, userMessageContent) {
+  replayTurn(id, events, userMessageContent, userMessageId, isSteer = false) {
     this.conversationId = id;
     this.resetStreamingState();
     if (userMessageContent) {
-      this.emit({ type: "user_message", content: userMessageContent });
+      this.emit({
+        type: "user_message",
+        content: userMessageContent,
+        ...userMessageId ? { id: userMessageId } : {},
+        ...isSteer ? { steer: true } : {}
+      });
     }
     for (const ev of events) {
       const type = ev.data.type || ev.event;
@@ -1814,12 +1863,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;
@@ -1836,6 +1942,64 @@ var ChatSession = class {
   }
 };
 
+// src/restore-plan.ts
+function planRestore(args) {
+  const { completedJobs, userMessages } = args;
+  const byId = /* @__PURE__ */ new Map();
+  userMessages.forEach((m, i) => {
+    if (m.id) byId.set(m.id, i);
+  });
+  const linkOf = (j) => j.message_id ? byId.get(j.message_id) : void 0;
+  const positional = (jobs, msgs) => jobs.map((job, i) => ({
+    kind: "turn",
+    jobId: job.job_id,
+    content: msgs[i]?.content,
+    messageId: msgs[i]?.id
+  }));
+  const firstLinked = completedJobs.findIndex((j) => linkOf(j) !== void 0);
+  if (firstLinked === -1) {
+    return positional(completedJobs, userMessages);
+  }
+  const cutover = linkOf(completedJobs[firstLinked]);
+  const steps = positional(
+    completedJobs.slice(0, firstLinked),
+    userMessages.slice(0, cutover)
+  );
+  let cursor = cutover;
+  const isSteer = (m) => !!m?.id && !completedJobs.some((j) => j.message_id === m.id);
+  const drainTo = (stopAt) => {
+    while (cursor < stopAt) {
+      const m = userMessages[cursor++];
+      if (isSteer(m)) {
+        steps.push({ kind: "steer", content: m.content, messageId: m.id });
+      }
+    }
+    cursor = stopAt + 1;
+  };
+  for (const job of completedJobs.slice(firstLinked)) {
+    const at = linkOf(job);
+    if (at !== void 0) {
+      drainTo(at);
+      const prompt = userMessages[at];
+      steps.push({
+        kind: "turn",
+        jobId: job.job_id,
+        content: prompt.content,
+        messageId: prompt.id
+      });
+      continue;
+    }
+    steps.push({ kind: "turn", jobId: job.job_id });
+  }
+  for (let i = cursor; i < userMessages.length; i++) {
+    const m = userMessages[i];
+    if (isSteer(m)) {
+      steps.push({ kind: "steer", content: m.content, messageId: m.id });
+    }
+  }
+  return steps;
+}
+
 // src/types.ts
 var ChatEventType = {
   // Connection lifecycle (SDK-local, not wire)
@@ -2104,16 +2268,40 @@ var StreamManager = class {
         const userMessages = this.session.messages.filter(
           (m) => m.role === "user"
         );
+        const plan = planRestore({
+          completedJobs: completedJobs.map((j) => ({
+            job_id: j.job_id,
+            message_id: j.message_id
+          })),
+          userMessages: userMessages.map((m) => ({
+            id: m.id,
+            content: m.content
+          }))
+        });
         const eventLists = await Promise.all(
           completedJobs.map(
             (job) => this.session.client.getConversationEvents(conversationId, job.job_id).catch(() => [])
           )
         );
-        for (let i = 0; i < completedJobs.length; i++) {
+        const eventsByJobId = new Map(
+          completedJobs.map((job, i) => [job.job_id, eventLists[i] ?? []])
+        );
+        for (const step of plan) {
+          if (step.kind === "steer") {
+            this.session.replayTurn(
+              conversationId,
+              [],
+              step.content,
+              step.messageId,
+              true
+            );
+            continue;
+          }
           this.session.replayTurn(
             conversationId,
-            eventLists[i] ?? [],
-            userMessages[i]?.content
+            eventsByJobId.get(step.jobId) ?? [],
+            step.content,
+            step.messageId
           );
         }
         if (completedJobs.length > 0) {
@@ -2205,6 +2393,7 @@ function parseEmbeddedResource(value) {
   AstralformClient,
   AstralformError,
   AuthenticationError,
+  CONVERSATION_PAGE_SIZE,
   ChatEventType,
   ChatSession,
   ConnectionError,