@astralform/js 9.2.0 → 9.4.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";
@@ -494,6 +500,79 @@ var AstralformClient = class {
             `/v1/code/projects/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`
           );
         }
+      },
+      /**
+       * Code groups: a user-named container under one repository, for a feature
+       * whose work outlives a single session. Its sessions share one plan and one
+       * set of notes, so what one writes the others read.
+       *
+       * A group is a LABEL, not a binding — unlike a task's project, which is
+       * written once on the first turn. A task may join, move between, or leave
+       * groups at any time, and a deleted group's sessions survive as ungrouped.
+       *
+       * The server enforces three things worth knowing before you render a
+       * failure: a group that is not this user's answers `404` (never `403`, so a
+       * group id cannot be probed); filing a task into a group under a DIFFERENT
+       * repository than the task's answers `409`; and the group's plan and notes
+       * are deleted with the group, while each session keeps its own.
+       */
+      groups: {
+        /**
+         * This user's groups, oldest first. Pass a repository to narrow to one
+         * repository's — the composer's picker does; the sidebar asks once and
+         * nests them itself.
+         */
+        list: async (repository) => {
+          const query = repository ? `?repository=${encodeURIComponent(repository)}` : "";
+          const raw = await this.get(`/v1/code/groups${query}`);
+          return raw.map((g) => camelizeKeys(g));
+        },
+        /**
+         * Create a group under a repository. The repository goes through the same
+         * normaliser the Projects surface uses, so a pasted GitHub URL is accepted
+         * and anything that is not `owner/repo` is refused.
+         */
+        create: async (repository, title) => {
+          const raw = await this.post("/v1/code/groups", { repository, title });
+          return camelizeKeys(raw);
+        },
+        /** Rename a group. A group that is not this user's answers `404`. */
+        rename: async (groupId, title) => {
+          const raw = await this.patch(`/v1/code/groups/${encodeURIComponent(groupId)}`, { title });
+          return camelizeKeys(raw);
+        },
+        /**
+         * Delete a group. Its tasks survive and become ungrouped, each keeping its
+         * own plan and notes; the group's SHARED documents are deleted with it.
+         */
+        remove: async (groupId) => {
+          await this.del(`/v1/code/groups/${encodeURIComponent(groupId)}`);
+        },
+        /**
+         * File a task into a group. Idempotent — filing an already-filed task
+         * again is the same state, not an error. Refused with `409` when the task
+         * belongs to a different repository than the group, because it would
+         * render nowhere in the sidebar.
+         */
+        assign: async (groupId, conversationId) => {
+          const raw = await this.post(
+            `/v1/code/groups/${encodeURIComponent(groupId)}/tasks/${encodeURIComponent(conversationId)}`,
+            void 0
+          );
+          return camelizeKeys(raw);
+        },
+        /**
+         * Take a task out of its group. The task and its documents are untouched.
+         *
+         * Deliberately not strict about WHICH group the task is in: a task that is
+         * in a different one (or in none) already satisfies "this task should not
+         * be grouped", so the call clears it rather than refusing.
+         */
+        unassign: async (groupId, conversationId) => {
+          await this.del(
+            `/v1/code/groups/${encodeURIComponent(groupId)}/tasks/${encodeURIComponent(conversationId)}`
+          );
+        }
       }
     };
     if (isApiKeyConfig(config)) {
@@ -694,6 +773,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 +999,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 +1014,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 +2907,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 +2969,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 +3488,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 +3609,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 +3758,7 @@ function parseEmbeddedResource(value) {
   VOICE_POLISH_MODES,
   generateId,
   isEmbeddedResource,
+  isToolImageStub,
   isToolOutputStub,
   isVoiceLLMMode,
   isVoicePolishMode,