@astralform/js 9.1.0 → 9.3.0

package/dist/index.js

@@ -319,6 +319,11 @@ function isToolOutputStub(value) {
   const v = value;
   return v.__stub === "tool_output" && typeof v.call_id === "string" && v.call_id.length > 0;
 }
+function isToolImageStub(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.__stub === "tool_image" && typeof v.call_id === "string" && v.call_id.length > 0 && typeof v.index === "number" && Number.isInteger(v.index) && v.index >= 0;
+}
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
@@ -642,6 +647,13 @@ var AstralformClient = class {
       return await response.json();
     });
   }
+  /** A GET whose body is binary. Read inside the race, for the reason above. */
+  async getBlob(path) {
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("GET", path, void 0, signal);
+      return response.blob();
+    });
+  }
   async post(path, body) {
     return this.withDeadline(async (signal) => {
       const response = await this.send("POST", path, body, signal);
@@ -861,6 +873,7 @@ var AstralformClient = class {
     const params = new URLSearchParams();
     if (jobId) params.set("job_id", jobId);
     if (options?.toolOutputs === "stub") params.set("tool_outputs", "stub");
+    if (options?.toolImages === "stub") params.set("tool_images", "stub");
     const query = params.toString();
     return this.get(
       `/v1/conversations/${encodeURIComponent(conversationId)}/events${query ? `?${query}` : ""}`
@@ -875,6 +888,25 @@ var AstralformClient = class {
     );
     return res.output;
   }
+  /**
+   * The image behind a {@link ToolImageStub}, as a `Blob` of the preview's bytes.
+   *
+   * Takes the stub itself and nothing else — the `job_id` scoping that
+   * `getToolOutput`'s id form warns about cannot be dropped from a value that
+   * carries it. There is deliberately no by-ids form.
+   *
+   * A `Blob` rather than a URL because the route is authenticated: an `<img
+   * src>` cannot send the bearer token, so a browser consumer turns this into
+   * an object URL (`URL.createObjectURL`) and revokes it when the image
+   * unmounts. The response is `private, immutable`, so a repeat fetch of the
+   * same preview is served by the HTTP cache.
+   */
+  async getToolImage(conversationId, stub) {
+    const query = stub.job_id ? `?job_id=${encodeURIComponent(stub.job_id)}` : "";
+    return this.getBlob(
+      `/v1/conversations/${encodeURIComponent(conversationId)}/tool-output/${encodeURIComponent(stub.call_id)}/images/${stub.index}${query}`
+    );
+  }
   async submitToolResult(request) {
     await this.post("/v1/tool-result", request);
   }
@@ -977,7 +1009,11 @@ var AstralformClient = class {
       // `VoicePolishMode`; `structured` is the server's own default.
       defaultMode: isVoicePolishMode(raw.default_mode) ? raw.default_mode : "structured",
       silenceAutoStopSeconds: raw.silence_auto_stop_seconds ?? 2,
-      autoSend: raw.auto_send ?? true,
+      // Deliberately not read from the wire. Auto-send was removed from the
+      // platform (2026-09-14) and the server pins `auto_send` to false; an
+      // older server still sending `true` must not make a client auto-send, so
+      // an absent field and an explicit `true` both read as false.
+      autoSend: false,
       maxRecordingSeconds: raw.max_recording_seconds ?? 300,
       supportsStreaming: Boolean(raw.supports_streaming),
       hotwords: raw.hotwords ?? []
@@ -2745,6 +2781,12 @@ var StreamManager = class _StreamManager {
      * Defaults to inline, so this is inert until a consumer opts in.
      */
     this.toolOutputs = "inline";
+    /**
+     * Whether restore asks for tool image previews inline or as fetch handles.
+     * Separate from `toolOutputs` because the server keeps them separate — see
+     * `ToolImageStub` — and on the same one-setting-both-waves rule.
+     */
+    this.toolImages = "inline";
     this._state = "idle";
     this._activeConversationId = null;
     this._backgroundJobs = /* @__PURE__ */ new Map();
@@ -2801,6 +2843,25 @@ var StreamManager = class _StreamManager {
   setToolOutputMode(mode) {
     this.toolOutputs = mode;
   }
+  /**
+   * Ask restore for stubbed image previews, fetched on demand.
+   *
+   * The same caution as `setToolOutputMode`, sharper: a consumer that cannot
+   * resolve one (`isToolImageStub`, `client.getToolImage`) finds an `images`
+   * entry with no `url` and draws a broken image where the preview was.
+   */
+  setToolImageMode(mode) {
+    this.toolImages = mode;
+  }
+  /**
+   * The ONE options object both event waves fetch with — the newest page and
+   * every `loadEarlierTurns` page. Built in one place so an opt-in added here
+   * reaches both by construction: two literals at two call sites is how one
+   * wave would silently keep asking for inline payloads.
+   */
+  get eventFetchOptions() {
+    return { toolOutputs: this.toolOutputs, toolImages: this.toolImages };
+  }
   emit(event) {
     for (const handler of this.handlers) {
       try {
@@ -3301,9 +3362,7 @@ var StreamManager = class _StreamManager {
       const boundary = this.oldestDrawnMessageId;
       const eventLists = await Promise.all(
         page.jobs.map(
-          (job) => session.client.getConversationEvents(conversationId, job.job_id, {
-            toolOutputs: this.toolOutputs
-          }).catch(() => [])
+          (job) => session.client.getConversationEvents(conversationId, job.job_id, this.eventFetchOptions).catch(() => [])
         )
       );
       if (stop()) return 0;
@@ -3362,7 +3421,13 @@ var StreamManager = class _StreamManager {
         conversationId,
         position: "prepend",
         hasMore: completed ? page.hasMore : true,
-        complete: completed
+        complete: completed,
+        // Empty on the incomplete path, matching the blocks a consumer is
+        // required to discard there: that page's cursor did not advance, so
+        // these same turns replay from the start on the next request and
+        // rehydrating from them now would key state to turns about to be
+        // re-emitted.
+        jobs: completed ? page.jobs : []
       });
       return emitted;
     } finally {
@@ -3418,9 +3483,7 @@ var StreamManager = class _StreamManager {
       });
       const eventLists = await Promise.all(
         replayableJobs.map(
-          (job) => this.session.client.getConversationEvents(conversationId, job.job_id, {
-            toolOutputs: this.toolOutputs
-          }).catch(() => [])
+          (job) => this.session.client.getConversationEvents(conversationId, job.job_id, this.eventFetchOptions).catch(() => [])
         )
       );
       if (stopReplay()) return false;
@@ -3451,7 +3514,7 @@ var StreamManager = class _StreamManager {
       this.oldestDrawnMessageId = plan[0]?.messageId ?? null;
       complete = true;
       if (stopReplay()) return false;
-      this.emit({ type: "restoreSettled", conversationId });
+      this.emit({ type: "restoreSettled", conversationId, jobs });
       const versionCount = replayableJobs.filter(
         (j) => j.status === "completed"
       ).length;
@@ -3568,6 +3631,7 @@ export {
   VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isToolImageStub,
   isToolOutputStub,
   isVoiceLLMMode,
   isVoicePolishMode,