@astralform/js 9.1.0 → 9.3.0

package/README.md

@@ -35,10 +35,24 @@ session.on((event) => {
 });
 
 await session.connect();
-await session.send("What is the capital of France?");
+
+// A conversation's first message names its model — one the agent's team has
+// connected. Later messages in the same conversation may omit it and reuse the
+// conversation's model.
+const models = await session.client.getModels(); // the list backs a model picker
+const model = models[0];
+if (!model) throw new Error("Connect a model provider for this agent first.");
+await session.send("What is the capital of France?", {
+  provider: model.provider,
+  model: model.model,
+});
 session.disconnect();
 ```
 
+The examples below omit `provider` and `model` for brevity. On a conversation's first
+message, pass them as above: newer Astralform servers reject a new conversation that
+names no model, and every server accepts one that does.
+
 ## Features
 
 - **SSE Streaming** — Real-time token-by-token responses via Server-Sent Events
@@ -323,7 +337,11 @@ const skills = await client.getSkills();
 const commands = await client.listSkillCommands();
 
 // Job-based streaming
-const job = await client.createJob({ message: "Hello" });
+const job = await client.createJob({
+  message: "Hello",
+  provider: "anthropic", // a new conversation names its model
+  model: "claude-sonnet-5",
+});
 for await (const event of client.streamJobEvents(job.job_id)) {
   const data = JSON.parse(event.data);
   if (data.type === "block_delta" && data.delta.channel === "text") {

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);
   }
@@ -1029,7 +1062,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 ?? []
@@ -2797,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();
@@ -2853,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 {
@@ -3353,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;
@@ -3414,7 +3474,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 {
@@ -3470,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;
@@ -3503,7 +3567,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;
@@ -3621,6 +3685,7 @@ function parseEmbeddedResource(value) {
   VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isToolImageStub,
   isToolOutputStub,
   isVoiceLLMMode,
   isVoicePolishMode,