@astralform/js 8.0.0 → 8.3.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   VOICE_POLISH_MODES: () => VOICE_POLISH_MODES,
   generateId: () => generateId,
   isEmbeddedResource: () => isEmbeddedResource,
+  isToolOutputStub: () => isToolOutputStub,
   isVoiceLLMMode: () => isVoiceLLMMode,
   isVoicePolishMode: () => isVoicePolishMode,
   mapSseToChat: () => mapSseToChat,
@@ -342,6 +343,7 @@ var ChatEventType = {
   ContextWarning: "context_warning",
   MemoryRecall: "memory_recall",
   MemoryUpdate: "memory_update",
+  MemoryProviderError: "memory_provider_error",
   DesktopStream: "desktop_stream",
   AttachmentStaged: "attachment_staged",
   WorkspaceReady: "workspace_ready",
@@ -350,6 +352,8 @@ var ChatEventType = {
   ToolApprovalGranted: "tool_approval_granted",
   ToolPermissionDenied: "tool_permission_denied",
   ToolHarnessWarning: "tool_harness_warning",
+  ToolProgress: "tool_progress",
+  NestedLlmUsage: "nested_llm_usage",
   UserUnavailable: "user_unavailable",
   PromptSuggestion: "prompt_suggestion",
   StateChanged: "state_changed",
@@ -363,6 +367,11 @@ function isVoicePolishMode(value) {
 function isVoiceLLMMode(mode) {
   return mode !== "raw";
 }
+function isToolOutputStub(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.__stub === "tool_output" && typeof v.call_id === "string" && v.call_id.length > 0;
+}
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
@@ -387,6 +396,17 @@ function validateBaseURL(url) {
 function isApiKeyConfig(config) {
   return "apiKey" in config;
 }
+function toMessage(m) {
+  return {
+    id: m.id,
+    conversationId: m.conversation_id,
+    role: m.role,
+    content: m.content,
+    parentId: m.parent_id,
+    status: "complete",
+    createdAt: m.created_at
+  };
+}
 var AstralformClient = class {
   constructor(config) {
     // --- Projects: the repositories this app user works with ---
@@ -626,6 +646,25 @@ var AstralformClient = class {
   // 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.
+  /**
+   * A GET whose response HEADERS the caller needs, not only its body.
+   *
+   * Paging metadata rides on headers (`X-Has-More`, `X-Next-Before`) because
+   * the bodies are bare lists that installed clients already parse as such.
+   * Reading them needs the `Response`, which `get<T>` discards.
+   *
+   * Note the shape: the body is parsed INSIDE the raced callback, exactly as
+   * `get`/`post`/`patch` do. See the comment above them — doing the parse
+   * outside the deadline is the original hang, and this method is not an
+   * exception to it.
+   */
+  async getWithHeaders(path) {
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("GET", path, void 0, signal);
+      const data = await response.json();
+      return { data, headers: response.headers };
+    });
+  }
   async get(path) {
     return this.withDeadline(async (signal) => {
       const response = await this.send("GET", path, void 0, signal);
@@ -708,17 +747,64 @@ var AstralformClient = class {
     const raw = await this.get(`/v1/conversations?limit=${safeLimit}&offset=${safeOffset}${filter}`);
     return raw.map((c) => camelizeKeys(c));
   }
+  /**
+   * One page of a conversation's turns, newest-first window returned oldest-first.
+   *
+   * `hasMore` asks "are there OLDER turns beyond this page" — the only
+   * direction a restore pages in, since it starts at the tail.
+   *
+   * **Degrades on an old backend.** A server without the cursor ignores the
+   * unknown `limit` query param and returns the whole list, and its response
+   * carries neither header — which reads here as one page with nothing older,
+   * i.e. exactly today's behaviour. That is why absent headers must mean
+   * `hasMore: false` rather than an error: the fallback has to be "everything
+   * arrived", not "paging is broken".
+   */
+  async getConversationJobsPage(conversationId, options) {
+    const params = new URLSearchParams();
+    if (options?.limit != null) params.set("limit", String(options.limit));
+    if (options?.before) params.set("before", options.before);
+    const query = params.toString();
+    const { data, headers } = await this.getWithHeaders(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/jobs${query ? `?${query}` : ""}`
+    );
+    return {
+      jobs: data,
+      hasMore: headers.get("X-Has-More") === "true",
+      nextBefore: headers.get("X-Next-Before")
+    };
+  }
+  /**
+   * One page of a conversation's messages, oldest-first within the page.
+   *
+   * Deliberately NOT folded into `getMessages`: that method is public surface
+   * whose `Message[]` return type callers depend on, and the server keeps its
+   * unbounded branch for exactly the same reason.
+   *
+   * Degrades like `getConversationJobsPage` — an old server ignores `limit`
+   * and returns the whole branch with no headers, which reads as a single
+   * complete page.
+   */
+  async getMessagesPage(conversationId, options) {
+    const params = new URLSearchParams({ limit: String(options.limit) });
+    if (options.beforeSeq != null) {
+      params.set("before_seq", String(options.beforeSeq));
+    }
+    const { data, headers } = await this.getWithHeaders(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/messages?${params}`
+    );
+    const next = headers.get("X-Next-Before-Seq");
+    return {
+      messages: data.map(toMessage),
+      hasMore: headers.get("X-Has-More") === "true",
+      nextBeforeSeq: next == null ? null : Number(next)
+    };
+  }
   async getMessages(conversationId) {
-    const raw = await this.get(`/v1/conversations/${encodeURIComponent(conversationId)}/messages`);
-    return raw.map((m) => ({
-      id: m.id,
-      conversationId: m.conversation_id,
-      role: m.role,
-      content: m.content,
-      parentId: m.parent_id,
-      status: "complete",
-      createdAt: m.created_at
-    }));
+    const raw = await this.get(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/messages`
+    );
+    return raw.map(toMessage);
   }
   /**
    * Replace the title the server generated from the conversation's first turn.
@@ -769,10 +855,23 @@ var AstralformClient = class {
     const raw = await this.get("/v1/skills");
     return raw.map((s) => camelizeKeys(s));
   }
-  async getConversationEvents(conversationId, jobId) {
-    let url = `/v1/conversations/${encodeURIComponent(conversationId)}/events`;
-    if (jobId) url += `?job_id=${encodeURIComponent(jobId)}`;
-    return this.get(url);
+  async getConversationEvents(conversationId, jobId, options) {
+    const params = new URLSearchParams();
+    if (jobId) params.set("job_id", jobId);
+    if (options?.toolOutputs === "stub") params.set("tool_outputs", "stub");
+    const query = params.toString();
+    return this.get(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/events${query ? `?${query}` : ""}`
+    );
+  }
+  async getToolOutput(conversationId, callIdOrStub, jobId) {
+    const callId = typeof callIdOrStub === "string" ? callIdOrStub : callIdOrStub.call_id;
+    const job = typeof callIdOrStub === "string" ? jobId : callIdOrStub.job_id;
+    const query = job ? `?job_id=${encodeURIComponent(job)}` : "";
+    const res = await this.get(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/tool-output/${encodeURIComponent(callId)}${query}`
+    );
+    return res.output;
   }
   async submitToolResult(request) {
     await this.post("/v1/tool-result", request);
@@ -1374,6 +1473,13 @@ function translateCustomEvent(name, data) {
         key: data.key ?? null,
         namespace: data.namespace ?? null
       };
+    case "memory_provider_error":
+      return {
+        type: "memory_provider_error",
+        provider: data.provider ?? "",
+        op: data.op ?? "",
+        error: data.error ?? ""
+      };
     case "desktop_stream":
       return {
         type: "desktop_stream",
@@ -1433,6 +1539,35 @@ function translateCustomEvent(name, data) {
         message: data.message ?? null,
         details: data.details ?? null
       };
+    case "tool_progress":
+      return {
+        type: "tool_progress",
+        callId: data.call_id ?? "",
+        stream: data.stream ?? "progress",
+        chunk: data.chunk ?? "",
+        toolName: data.tool ?? null,
+        item: data.item ?? null,
+        index: data.index ?? null,
+        total: data.total ?? null,
+        // Every producer sends keys beyond the named ones, and one of them
+        // (`video_tool._emit_progress`) splats `**extra`, so no fixed list can
+        // be complete. Before this case existed the event fell through to
+        // `{type:"custom", name, data}` and consumers read the whole dict;
+        // keeping `data` verbatim is what makes the typed variant an addition
+        // rather than a narrowing.
+        data
+      };
+    case "nested_llm_usage":
+      return {
+        type: "nested_llm_usage",
+        source: data.source ?? "",
+        callId: data.call_id ?? "",
+        inputTokens: data.input_tokens ?? 0,
+        outputTokens: data.output_tokens ?? 0,
+        cachedTokens: data.cached_tokens ?? 0,
+        cacheCreationTokens: data.cache_creation_tokens ?? 0,
+        llmCalls: data.llm_calls ?? 0
+      };
     case "user_unavailable":
       return {
         type: "user_unavailable",
@@ -1591,6 +1726,19 @@ var ChatSession = class {
      * cheaper than adding a count query to every list call.
      */
     this.hasMoreConversations = false;
+    /** True when the loaded window has OLDER turns behind it — the transcript's
+     *  analogue of `hasMoreConversations`, and what a scroll-to-top sentinel
+     *  gates on. False until a windowed load says otherwise, so a consumer that
+     *  never asks for a window never offers to page. */
+    this.hasMoreTurns = false;
+    /** Cursor for the next older MESSAGE page (`before_seq`), or null. */
+    this.oldestMessageSeq = null;
+    /** Cursor for the next older TURN page (`before`), or null. Set by the
+     *  restore that loaded the newest page; consumed by `loadEarlierTurns`. */
+    this.oldestTurnCursor = null;
+    /** Guards against a sentinel that re-fires while a page is still in flight
+     *  and stacks duplicate turns — the same guard `loadMoreConversations` uses. */
+    this.isLoadingEarlierTurns = false;
     /** True while ``loadMoreConversations`` is in flight. */
     this.isLoadingConversations = false;
     this.messages = [];
@@ -2202,12 +2350,22 @@ var ChatSession = class {
    * Load conversation context (messages) without replaying events.
    * Used before reconnectToJob — SSE replay handles event replay.
    */
-  async loadConversation(id) {
+  async loadConversation(id, options) {
     const load = ++this.loadGeneration;
+    this.hasMoreTurns = false;
+    this.oldestTurnCursor = null;
+    this.oldestMessageSeq = null;
     this.conversationId = id;
     if (!this.isStreaming) this.resetStreamingState();
     const rowsKnownAtIssue = this.serverRowsKnown;
-    const messages = await this.client.getMessages(id).catch(() => this.storage.fetchMessages(id));
+    let page = null;
+    let messages;
+    if (options?.limit == null) {
+      messages = await this.client.getMessages(id).catch(() => this.storage.fetchMessages(id));
+    } else {
+      page = await this.client.getMessagesPage(id, { limit: options.limit }).catch(() => null);
+      messages = page ? page.messages : await this.storage.fetchMessages(id);
+    }
     if (load !== this.loadGeneration) return;
     const pending = this.messages.filter(
       (m) => this.pendingUserMessages.has(m.id) && m.conversationId === id
@@ -2220,6 +2378,7 @@ var ChatSession = class {
     for (const m of pending) {
       if (!stillPending.includes(m)) this.pendingUserMessages.delete(m.id);
     }
+    this.oldestMessageSeq = page?.nextBeforeSeq ?? null;
     this.setMessages(
       stillPending.length ? [...messages, ...stillPending] : messages
     );
@@ -2414,6 +2573,25 @@ var ChatSession = class {
    * tracking ids client-side cannot discover a row that moved into a region
    * already scanned.
    */
+  /**
+   * Put an older page of messages in FRONT of the loaded window.
+   *
+   * Pending optimistic sends stay at the tail. They are the newest thing in
+   * the session by construction — a message this browser has posted and the
+   * server has not confirmed — so sorting them in with a page of history
+   * would move an unsent bubble into the middle of the transcript.
+   *
+   * Ids already present are dropped rather than duplicated: pages are cut on a
+   * row sequence, but a turn landing mid-walk can still put one message in two
+   * pages, and a doubled prompt is more visible than a missing one.
+   */
+  prependMessages(older) {
+    if (!older.length) return;
+    const known = new Set(this.messages.map((m) => m.id));
+    const fresh = older.filter((m) => !known.has(m.id));
+    if (!fresh.length) return;
+    this.setMessages([...fresh, ...this.messages]);
+  }
   async loadMoreConversations() {
     if (this.isLoadingConversations || !this.hasMoreConversations) return [];
     this.isLoadingConversations = true;
@@ -2556,8 +2734,23 @@ function planRestore(args) {
 }
 
 // src/stream-manager.ts
-var StreamManager = class {
+var RESTORE_TURN_PAGE_SIZE = 10;
+var RESTORE_MESSAGE_PAGE_SIZE = 40;
+var StreamManager = class _StreamManager {
   constructor(session) {
+    /** The oldest prompt drawn so far — where a prepended page's span ends. */
+    this.oldestDrawnMessageId = null;
+    /**
+     * Whether restore asks for tool outputs inline or as fetch handles.
+     *
+     * ONE setting, applied to both event waves — the newest page and every
+     * `loadEarlierTurns` page. A consumer that got stubs only on scroll-up would
+     * be worse off than one that got them nowhere: the pill would resolve itself
+     * in the visible tail and need a fetch above the fold, for no stated reason.
+     *
+     * Defaults to inline, so this is inert until a consumer opts in.
+     */
+    this.toolOutputs = "inline";
     this._state = "idle";
     this._activeConversationId = null;
     this._backgroundJobs = /* @__PURE__ */ new Map();
@@ -2603,6 +2796,17 @@ var StreamManager = class {
       this.handlers = this.handlers.filter((h) => h !== handler);
     };
   }
+  /**
+   * Ask restore for stubbed tool outputs, resolved on demand.
+   *
+   * Only worth turning on by a consumer that can actually resolve a stub —
+   * see `isToolOutputStub` and `client.getToolOutput`. One that cannot does
+   * not render an empty result: it renders the stub OBJECT where the output
+   * belongs, because that is what arrives in `final.output`.
+   */
+  setToolOutputMode(mode) {
+    this.toolOutputs = mode;
+  }
   emit(event) {
     for (const handler of this.handlers) {
       try {
@@ -2945,10 +3149,11 @@ var StreamManager = class {
    * probe and the message list while ``replayHistory``, which consumes it,
    * keeps owning the shape it reads.
    */
-  jobList(conversationId) {
-    return this.session.client.get(
-      `/v1/conversations/${encodeURIComponent(conversationId)}/jobs`
-    );
+  jobList(conversationId, before) {
+    return this.session.client.getConversationJobsPage(conversationId, {
+      limit: RESTORE_TURN_PAGE_SIZE,
+      ...before ? { before } : {}
+    });
   }
   async restore(conversationId, gen) {
     const superseded = () => gen !== this.generation;
@@ -2958,14 +3163,20 @@ var StreamManager = class {
     if (announcedRestoring) this.setState("restoring");
     if (superseded()) return;
     const probeRequest = this.session.client.getActiveJob(conversationId).catch(() => null);
-    const loadRequest = this.session.loadConversation(conversationId);
+    const loadRequest = this.session.loadConversation(
+      conversationId,
+      announcedRestoring ? { limit: RESTORE_MESSAGE_PAGE_SIZE } : void 0
+    );
     const jobsRequest = announcedRestoring ? this.jobList(conversationId) : null;
     void jobsRequest?.catch(() => {
     });
     const [probe] = await Promise.all([probeRequest, loadRequest]);
     const activeJobId = probe?.jobId ?? null;
     if (superseded()) return;
-    if (announcedRestoring && this.viewTakenOverByLiveTurn()) return;
+    if (announcedRestoring && this.viewTakenOverByLiveTurn()) {
+      this.reloadUnwindowed(conversationId);
+      return;
+    }
     if (jobsRequest && !await this.replayHistory(
       conversationId,
       gen,
@@ -3017,6 +3228,26 @@ var StreamManager = class {
   turnStarted(since) {
     return this.turnCounter !== since;
   }
+  /**
+   * Re-issue the message load UNWINDOWED after a restore stopped before it
+   * could write a turn cursor.
+   *
+   * The window is decided synchronously at restore entry, but "this restore
+   * will page" is only settled once `replayHistory` clears its first abort
+   * check. A send landing in between — nothing gates one during a restore —
+   * stops the replay with the window already installed and the cursor never
+   * written: a transcript truncated to one page that no pager can extend,
+   * which is worse than the unbounded load this path did before windowing.
+   * Reloading whole is that behaviour restored. Fire-and-forget: the load
+   * token still makes a later switch win, and the pending-send reconciliation
+   * inside `loadConversation` is what keeps the interrupting send's prompt.
+   * Only called when the conversation has NOT moved — a superseding switch
+   * announces and loads its own.
+   */
+  reloadUnwindowed(conversationId) {
+    void this.session.loadConversation(conversationId).catch(() => {
+    });
+  }
   /**
    * Replay a conversation's persisted history into the consumer's block view.
    *
@@ -3037,10 +3268,119 @@ var StreamManager = class {
    * what keeps a failed job list non-blocking exactly as it was when the fetch
    * lived here.
    */
+  /**
+   * Fetch and replay the next OLDER page of turns.
+   *
+   * The scroll-up half of tail-first restore: `restore` renders the newest
+   * page and clears `restoring`, and this brings back what precedes it, on
+   * demand. Full fidelity — the same per-job events wave the newest page uses,
+   * just later — so a turn paged in here is byte-identical to the same turn
+   * rendered live. That is the whole reason this defers the fetch rather than
+   * rebuilding older turns from the message list, which persists no thinking
+   * blocks and no custom events.
+   *
+   * Resolves to the number of turns emitted; 0 when there is nothing older,
+   * a page is already in flight, or the view was taken over mid-fetch.
+   */
+  /** User prompts from a slice of the message window, in plan input shape. */
+  static userMessagesOf(messages) {
+    return messages.filter((m) => m.role === "user").map((m) => ({ id: m.id, content: m.content }));
+  }
+  async loadEarlierTurns(conversationId) {
+    const session = this.session;
+    if (session.isLoadingEarlierTurns || !session.hasMoreTurns || !session.oldestTurnCursor) {
+      return 0;
+    }
+    const gen = this.generation;
+    const turn = this.turnCounter;
+    const cursor = session.oldestTurnCursor;
+    const stop = () => gen !== this.generation || conversationId !== session.conversationId || this.viewTakenOverByLiveTurn() || this.turnStarted(turn);
+    session.isLoadingEarlierTurns = true;
+    try {
+      const page = await this.jobList(conversationId, cursor);
+      if (stop()) return 0;
+      const messages = session.oldestMessageSeq ? await session.client.getMessagesPage(conversationId, {
+        limit: RESTORE_MESSAGE_PAGE_SIZE,
+        beforeSeq: session.oldestMessageSeq
+      }).catch(() => null) : null;
+      if (stop()) return 0;
+      const boundary = this.oldestDrawnMessageId;
+      const eventLists = await Promise.all(
+        page.jobs.map(
+          (job) => session.client.getConversationEvents(conversationId, job.job_id, {
+            toolOutputs: this.toolOutputs
+          }).catch(() => [])
+        )
+      );
+      if (stop()) return 0;
+      if (messages) session.prependMessages(messages.messages);
+      const plan = planRestore({
+        completedJobs: page.jobs.map((j) => ({
+          job_id: j.job_id,
+          message_id: j.message_id
+        })),
+        // Same array feeds the walk and the claim set, for the reason the
+        // newest-page path documents: derived apart, they drift, and the
+        // prompts of any turn dropped from one surface as steers in the other.
+        claimedMessageIds: page.jobs.map((j) => j.message_id),
+        userMessages: (() => {
+          const all = session.messages;
+          if (!boundary) return _StreamManager.userMessagesOf(all);
+          const cut = all.findIndex((m) => m.id === boundary);
+          return cut < 0 ? [] : _StreamManager.userMessagesOf(all.slice(0, cut));
+        })()
+      });
+      this.emit({
+        type: "historyPageStart",
+        conversationId,
+        position: "prepend"
+      });
+      let emitted = 0;
+      const byJob = new Map(
+        page.jobs.map((job, i) => [job.job_id, eventLists[i] ?? []])
+      );
+      let completed = true;
+      for (const step of plan) {
+        if (stop()) {
+          completed = false;
+          break;
+        }
+        if (step.kind === "steer") {
+          session.replayTurn(conversationId, [], step.content, step.messageId, true);
+        } else {
+          session.replayTurn(
+            conversationId,
+            byJob.get(step.jobId) ?? [],
+            step.content,
+            step.messageId
+          );
+        }
+        emitted++;
+      }
+      if (completed) {
+        session.hasMoreTurns = page.hasMore;
+        session.oldestTurnCursor = page.nextBefore;
+        if (messages) session.oldestMessageSeq = messages.nextBeforeSeq;
+        this.oldestDrawnMessageId = plan[0]?.messageId ?? boundary;
+      }
+      this.emit({
+        type: "historyPageEnd",
+        conversationId,
+        position: "prepend",
+        hasMore: completed ? page.hasMore : true,
+        complete: completed
+      });
+      return emitted;
+    } finally {
+      session.isLoadingEarlierTurns = false;
+    }
+  }
   async replayHistory(conversationId, gen, activeJobId, turn, jobsRequest) {
     const stopReplay = () => gen !== this.generation || this.viewTakenOverByLiveTurn() || this.turnStarted(turn);
+    let complete = false;
     try {
-      const jobs = await jobsRequest;
+      const page = await jobsRequest;
+      const jobs = page.jobs;
       if (stopReplay()) return false;
       const replayableJobs = jobs.filter(
         (j) => j.job_id !== activeJobId
@@ -3084,7 +3424,9 @@ var StreamManager = class {
       });
       const eventLists = await Promise.all(
         replayableJobs.map(
-          (job) => this.session.client.getConversationEvents(conversationId, job.job_id).catch(() => [])
+          (job) => this.session.client.getConversationEvents(conversationId, job.job_id, {
+            toolOutputs: this.toolOutputs
+          }).catch(() => [])
         )
       );
       if (stopReplay()) return false;
@@ -3110,6 +3452,10 @@ var StreamManager = class {
           step.messageId
         );
       }
+      this.session.hasMoreTurns = page.hasMore;
+      this.session.oldestTurnCursor = page.nextBefore;
+      this.oldestDrawnMessageId = plan[0]?.messageId ?? null;
+      complete = true;
       if (stopReplay()) return false;
       this.emit({ type: "restoreSettled", conversationId });
       const versionCount = replayableJobs.filter(
@@ -3123,6 +3469,10 @@ var StreamManager = class {
         });
       }
     } catch {
+    } finally {
+      if (!complete && gen === this.generation) {
+        this.reloadUnwindowed(conversationId);
+      }
     }
     return !stopReplay();
   }
@@ -3131,6 +3481,10 @@ var StreamManager = class {
     this._activeConversationId = id;
     this.session.invalidateLoadsInFlight();
     const claimed = ++this.generation;
+    this.session.hasMoreTurns = false;
+    this.session.oldestTurnCursor = null;
+    this.session.oldestMessageSeq = null;
+    this.oldestDrawnMessageId = null;
     this.emit({ type: "conversationChanged", conversationId: id });
     return claimed;
   }
@@ -3221,6 +3575,7 @@ function parseEmbeddedResource(value) {
   VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isToolOutputStub,
   isVoiceLLMMode,
   isVoicePolishMode,
   mapSseToChat,