@astralform/js 3.2.0 → 4.0.0

package/README.md

@@ -283,11 +283,10 @@ session.toggleClientTool("mcp_get_current_time"); // returns true if now enabled
 session.enabledClientTools; // Set<string>
 ```
 
-Platform-level features (web search, plan mode) are enabled per-request via the `send` options:
+Platform-level features (e.g. plan mode) are enabled per-request via the `send` options. Web search needs no option: when the agent's search feature is enabled server-side, the agent decides per-task whether to search.
 
 ```ts
 await session.send("Research the latest on WebGPU", {
-  enableSearch: true,
   planMode: true,
 });
 ```

package/dist/index.cjs

@@ -638,6 +638,10 @@ var AstralformClient = class {
       workspacePath: raw.workspace_path,
       sourceMessageId: raw.source_message_id,
       agentName: raw.agent_name,
+      // The API serializes an unsigned asset as `url: null`; normalize to
+      // undefined so it matches the `url?: string` type and consumers that
+      // check `!== undefined` never receive a null.
+      url: raw.url ?? void 0,
       createdAt: raw.created_at
     };
   }
@@ -1343,7 +1347,6 @@ var ChatSession = class {
       ),
       upload_ids: options?.uploadIds,
       agent_name: options?.agentName,
-      enable_search: options?.enableSearch,
       plan_mode: options?.planMode,
       // Per-request model choice (client-side model selection).
       provider: options?.provider,
@@ -1353,15 +1356,14 @@ var ChatSession = class {
     };
     await this.processStream(request);
   }
-  async resendFromCheckpoint(messageId, newContent, options) {
+  async resendFromCheckpoint(messageId, newContent) {
     if (this.isStreaming) return;
     const request = {
       message: newContent,
       conversation_id: this.conversationId ?? void 0,
       resend_from: messageId,
       mcp_manifest: this.toolRegistry.getManifest(),
-      enabled_mcp: Array.from(this.enabledClientTools),
-      enable_search: options?.enableSearch
+      enabled_mcp: Array.from(this.enabledClientTools)
     };
     await this.processStream(request);
   }
@@ -1552,6 +1554,20 @@ var ChatSession = class {
       }
     }
   }
+  /**
+   * Synchronous replay of a single stored wire event — the side-effect +
+   * translate + emit core of ``dispatchWireEvent`` without the (live-only)
+   * client-tool round-trip. Called in a tight synchronous loop during history
+   * restore so the consumer's per-event store writes batch into ONE render
+   * instead of re-typing the whole conversation event by event.
+   */
+  replayWireEvent(wire, conversationId) {
+    this.applyWireSideEffects(wire, conversationId, "");
+    const event = translateWireEvent(wire);
+    if (event) {
+      this.emit(event);
+    }
+  }
   /**
    * State mutations driven by wire events. Kept separate from translation so
    * the pure wire → ChatEvent mapping can live in translate.ts and be reused
@@ -1698,34 +1714,57 @@ var ChatSession = class {
     this.messages = [];
     return id;
   }
-  async switchConversation(id, jobId, userMessageContent) {
+  /**
+   * Replay one completed turn's already-fetched events, synchronously.
+   *
+   * Fetching is the caller's job (``StreamManager.restore`` loads every turn's
+   * events in parallel and the message list once), so this is pure replay: no
+   * awaits, so the whole restore runs in a single synchronous pass and the
+   * consumer batches it into one render.
+   *
+   * ``userMessageContent`` is the prompt that triggered this turn. It's emitted
+   * as a synthetic ``user_message`` BEFORE any of the turn's events: user
+   * prompts aren't persisted in ``job_events``, and some events precede
+   * ``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) {
     this.conversationId = id;
     this.resetStreamingState();
+    if (userMessageContent) {
+      this.emit({ type: "user_message", content: userMessageContent });
+    }
+    for (const ev of events) {
+      const type = ev.data.type || ev.event;
+      if (!type || type === "done") continue;
+      const wire = { ...ev.data, type };
+      try {
+        this.replayWireEvent(wire, id);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Load a conversation's messages and replay its persisted history.
+   *
+   * Convenience for plain-``ChatSession`` consumers (the documented
+   * conversation-management API). ``StreamManager`` drives restore itself —
+   * loading messages once and replaying each turn in parallel — and does NOT
+   * call this; it's kept so direct-Session usage doesn't break.
+   *
+   * Without ``jobId`` it replays the whole conversation; with one, just that
+   * job's events.
+   */
+  async switchConversation(id, jobId) {
     const [messagesResult, eventsResult] = await Promise.allSettled([
       this.client.getMessages(id).catch(() => this.storage.fetchMessages(id)),
       this.client.getConversationEvents(id, jobId)
     ]);
     this.messages = messagesResult.status === "fulfilled" ? messagesResult.value : [];
-    if (eventsResult.status === "fulfilled") {
-      if (userMessageContent) {
-        this.emit({ type: "user_message", content: userMessageContent });
-      }
-      for (const ev of eventsResult.value) {
-        const type = ev.data.type || ev.event;
-        if (!type || type === "done") continue;
-        const wire = { ...ev.data, type };
-        try {
-          await this.dispatchWireEvent(
-            wire,
-            id,
-            "",
-            false
-            // don't execute client tools on replay
-          );
-        } catch {
-        }
-      }
-    }
+    this.replayTurn(
+      id,
+      eventsResult.status === "fulfilled" ? eventsResult.value : []
+    );
   }
   async deleteConversation(id) {
     try {
@@ -1869,7 +1908,6 @@ var StreamManager = class {
     this.setState("streaming");
     try {
       await this.session.send(content, {
-        enableSearch: options?.enableSearch,
         agentName: options?.agentName,
         uploadIds: options?.uploadIds,
         planMode: options?.planMode,
@@ -1901,8 +1939,26 @@ var StreamManager = class {
     this.finalizeStream();
   }
   // ── Switch conversation ───────────────────────────────────────
-  async switchTo(conversationId) {
+  /**
+   * Switch the active conversation.
+   *
+   * ``opts.skipHistoryReplay`` is a fast path for consumers that CACHE a
+   * restored conversation's rendered blocks: it moves the active pointer and
+   * loads the message list (needed for send / regenerate context) but skips
+   * the expensive event fetch + replay, and never enters the ``restoring``
+   * state, so a consumer that clears its block view on ``restoring`` keeps
+   * showing the cached history with no flash of a spinner.
+   *
+   * It still confirms there is no live job before skipping: the in-memory
+   * background-job map is empty on a fresh instance (page reload) and blind to
+   * jobs started in another tab/device, so the fast path always asks the server
+   * (``getActiveJob``) and falls through to a full reconnect if one is running.
+   * That one small request is the only cost it doesn't skip, so passing the
+   * flag whenever you hold cached blocks is safe.
+   */
+  async switchTo(conversationId, opts) {
     if (conversationId === this._activeConversationId) return;
+    const targetHadBackgroundJob = this._backgroundJobs.has(conversationId);
     if (this._state === "streaming") {
       const oldConvId = this._activeConversationId;
       const jobId = this.session.currentJobId;
@@ -1923,6 +1979,18 @@ var StreamManager = class {
       });
     }
     this.setActiveConversation(conversationId);
+    if (opts?.skipHistoryReplay && !targetHadBackgroundJob) {
+      let activeJobId = null;
+      try {
+        activeJobId = (await this.session.client.getActiveJob(conversationId)).jobId;
+      } catch {
+      }
+      if (!activeJobId) {
+        await this.session.loadConversation(conversationId);
+        this.setState("idle");
+        return;
+      }
+    }
     await this.restore(conversationId);
   }
   // ── Create / delete conversation ──────────────────────────────
@@ -1987,13 +2055,16 @@ var StreamManager = class {
         const userMessages = this.session.messages.filter(
           (m) => m.role === "user"
         );
+        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 job = completedJobs[i];
-          const userContent = userMessages[i]?.content;
-          await this.session.switchConversation(
+          this.session.replayTurn(
             conversationId,
-            job.job_id,
-            userContent
+            eventLists[i] ?? [],
+            userMessages[i]?.content
           );
         }
         if (completedJobs.length > 0) {