@astralform/js 9.2.0 → 9.3.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   VOICE_POLISH_MODES: () => VOICE_POLISH_MODES,
   generateId: () => generateId,
   isEmbeddedResource: () => isEmbeddedResource,
+  isToolImageStub: () => isToolImageStub,
   isToolOutputStub: () => isToolOutputStub,
   isVoiceLLMMode: () => isVoiceLLMMode,
   isVoicePolishMode: () => isVoicePolishMode,
@@ -371,6 +372,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";
@@ -694,6 +700,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);
@@ -913,6 +926,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}` : ""}`
@@ -927,6 +941,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);
   }
@@ -2801,6 +2834,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();
@@ -2857,6 +2896,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 {
@@ -3357,9 +3415,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;
@@ -3480,9 +3536,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;
@@ -3631,6 +3685,7 @@ function parseEmbeddedResource(value) {
   VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isToolImageStub,
   isToolOutputStub,
   isVoiceLLMMode,
   isVoicePolishMode,