@astralform/js 4.8.0 → 4.9.1

package/dist/index.d.cts

@@ -297,6 +297,7 @@ interface WireMessageStop extends WireEnvelope {
         input_tokens?: number;
         output_tokens?: number;
         cached_tokens?: number;
+        cache_creation_tokens?: number;
     };
     ttfb_ms?: number | null;
     total_ms: number;
@@ -344,6 +345,8 @@ interface TurnUsage {
     inputTokens: number;
     outputTokens: number;
     cachedTokens: number;
+    /** Tokens written to the model's prompt cache (wire: `cache_creation_tokens`). */
+    cacheCreationTokens: number;
 }
 type BlockDeltaPayload = {
     channel: "text";
@@ -629,6 +632,8 @@ interface TeamAgentSummary {
     teamId: string;
     createdAt: string;
     updatedAt: string;
+    /** Agent avatar URL, when the team has set one (wire: `avatar_url`). */
+    avatarUrl?: string | null;
 }
 interface SkillInfo {
     name: string;
@@ -700,6 +705,7 @@ interface ChatStreamRequest {
     agent_name?: string;
     plan_mode?: boolean;
     image_mode?: boolean;
+    video_mode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode). The backend mints
      * an agent_goal from this text and drives the run under a budget until the
@@ -805,6 +811,22 @@ interface SendOptions$1 extends ModelChoiceOptions {
      * The `image_mode` field itself is accepted from Astralform ≥ 0.59.0.
      */
     imageMode?: boolean;
+    /**
+     * Put this turn in video mode, attaching the video-generation tool.
+     *
+     * Off by default and per-message, for a sharper reason than images: a clip
+     * occupies one shared GPU for minutes, during which image generation on the
+     * same host cannot run at all. The tool is not attached unless this is set.
+     *
+     * Mutually exclusive with `imageMode` at the composer level — which is why a
+     * video turn also gets the image tool server-side: the user cannot select
+     * both, so the agent must be able to produce its own first frame.
+     *
+     * `generate_video` animates an EXISTING image; it cannot start from text, and
+     * the clip is silent. Gate the affordance on `AgentStatus.capabilities`
+     * (`video`), the same way image mode does.
+     */
+    videoMode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode). The text becomes
      * the goal's objective; the backend keeps the agent working under a budget until
@@ -1158,6 +1180,11 @@ declare class ChatSession {
      * Consume a single SSE stream to exhaustion. Returns whether a terminal
      * event (``message_stop`` / ``error``) was seen, so the caller can decide
      * whether an ended stream means "turn done" vs "dropped, reconnect".
+     *
+     * ``onStall`` aborts the per-attempt connection: if no event arrives within
+     * SSE_STALL_TIMEOUT_MS (backend keepalives land every 15s), the stream is a
+     * zombie — ``reader.read()`` will never settle — so we kill the fetch and
+     * throw a ConnectionError, feeding the caller's reconnect-from-lastSeq loop.
      */
     private pumpStream;
     /** Sleep for ``ms``, resolving early if the turn is aborted mid-backoff. */
@@ -1334,6 +1361,13 @@ interface SendOptions extends ModelChoiceOptions {
      * provider. Gate the affordance on `AgentStatus.capabilities`.
      */
     imageMode?: boolean;
+    /**
+     * Attach the video-generation tool to this turn. Mutually exclusive with
+     * `imageMode` at the composer level. See `SendOptions.videoMode` in types.ts
+     * for the full rule — a clip animates an existing image, is silent, and holds
+     * one shared GPU for minutes, so it is per-message and off by default.
+     */
+    videoMode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode) — the text is the
      * goal objective the backend drives to completion. Omit for a normal turn.

package/dist/index.d.ts

@@ -297,6 +297,7 @@ interface WireMessageStop extends WireEnvelope {
         input_tokens?: number;
         output_tokens?: number;
         cached_tokens?: number;
+        cache_creation_tokens?: number;
     };
     ttfb_ms?: number | null;
     total_ms: number;
@@ -344,6 +345,8 @@ interface TurnUsage {
     inputTokens: number;
     outputTokens: number;
     cachedTokens: number;
+    /** Tokens written to the model's prompt cache (wire: `cache_creation_tokens`). */
+    cacheCreationTokens: number;
 }
 type BlockDeltaPayload = {
     channel: "text";
@@ -629,6 +632,8 @@ interface TeamAgentSummary {
     teamId: string;
     createdAt: string;
     updatedAt: string;
+    /** Agent avatar URL, when the team has set one (wire: `avatar_url`). */
+    avatarUrl?: string | null;
 }
 interface SkillInfo {
     name: string;
@@ -700,6 +705,7 @@ interface ChatStreamRequest {
     agent_name?: string;
     plan_mode?: boolean;
     image_mode?: boolean;
+    video_mode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode). The backend mints
      * an agent_goal from this text and drives the run under a budget until the
@@ -805,6 +811,22 @@ interface SendOptions$1 extends ModelChoiceOptions {
      * The `image_mode` field itself is accepted from Astralform ≥ 0.59.0.
      */
     imageMode?: boolean;
+    /**
+     * Put this turn in video mode, attaching the video-generation tool.
+     *
+     * Off by default and per-message, for a sharper reason than images: a clip
+     * occupies one shared GPU for minutes, during which image generation on the
+     * same host cannot run at all. The tool is not attached unless this is set.
+     *
+     * Mutually exclusive with `imageMode` at the composer level — which is why a
+     * video turn also gets the image tool server-side: the user cannot select
+     * both, so the agent must be able to produce its own first frame.
+     *
+     * `generate_video` animates an EXISTING image; it cannot start from text, and
+     * the clip is silent. Gate the affordance on `AgentStatus.capabilities`
+     * (`video`), the same way image mode does.
+     */
+    videoMode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode). The text becomes
      * the goal's objective; the backend keeps the agent working under a budget until
@@ -1158,6 +1180,11 @@ declare class ChatSession {
      * Consume a single SSE stream to exhaustion. Returns whether a terminal
      * event (``message_stop`` / ``error``) was seen, so the caller can decide
      * whether an ended stream means "turn done" vs "dropped, reconnect".
+     *
+     * ``onStall`` aborts the per-attempt connection: if no event arrives within
+     * SSE_STALL_TIMEOUT_MS (backend keepalives land every 15s), the stream is a
+     * zombie — ``reader.read()`` will never settle — so we kill the fetch and
+     * throw a ConnectionError, feeding the caller's reconnect-from-lastSeq loop.
      */
     private pumpStream;
     /** Sleep for ``ms``, resolving early if the turn is aborted mid-backoff. */
@@ -1334,6 +1361,13 @@ interface SendOptions extends ModelChoiceOptions {
      * provider. Gate the affordance on `AgentStatus.capabilities`.
      */
     imageMode?: boolean;
+    /**
+     * Attach the video-generation tool to this turn. Mutually exclusive with
+     * `imageMode` at the composer level. See `SendOptions.videoMode` in types.ts
+     * for the full rule — a clip animates an existing image, is silent, and holds
+     * one shared GPU for minutes, so it is per-message and off by default.
+     */
+    videoMode?: boolean;
     /**
      * Start a durable long-horizon goal for this run (goal mode) — the text is the
      * goal objective the backend drives to completion. Omit for a normal turn.

package/dist/index.js

@@ -737,7 +737,8 @@ var AstralformClient = class {
       name: a.name,
       teamId: a.team_id,
       createdAt: a.created_at,
-      updatedAt: a.updated_at
+      updatedAt: a.updated_at,
+      avatarUrl: a.avatar_url ?? null
     }));
   }
   // --- Jobs API ---
@@ -1019,6 +1020,19 @@ function translateAgentIdentity(raw) {
     description: raw.description ?? null
   };
 }
+function translateTodoItem(raw) {
+  return {
+    id: raw.id ?? 0,
+    subject: raw.subject ?? "",
+    status: raw.status ?? "pending",
+    description: raw.description ?? null,
+    activeForm: raw.active_form ?? null,
+    owner: raw.owner ?? null,
+    blockedBy: raw.blocked_by ?? null,
+    blocks: raw.blocks ?? null,
+    priority: raw.priority ?? null
+  };
+}
 function translateCustomEvent(name, data) {
   switch (name) {
     case "user_message":
@@ -1035,7 +1049,9 @@ function translateCustomEvent(name, data) {
     case "todo_update":
       return {
         type: "todo_update",
-        todos: data.todos ?? []
+        todos: (data.todos ?? []).map(
+          (t) => translateTodoItem(t)
+        )
       };
     case "plan_update":
       return {
@@ -1228,7 +1244,8 @@ function translateWireEvent(wire) {
         usage: {
           inputTokens: wire.usage.input_tokens ?? 0,
           outputTokens: wire.usage.output_tokens ?? 0,
-          cachedTokens: wire.usage.cached_tokens ?? 0
+          cachedTokens: wire.usage.cached_tokens ?? 0,
+          cacheCreationTokens: wire.usage.cache_creation_tokens ?? 0
         },
         ttfbMs: wire.ttfb_ms,
         totalMs: wire.total_ms,
@@ -1274,6 +1291,7 @@ function translateWireEvent(wire) {
 
 // src/session.ts
 var SSE_MAX_RECONNECTS = 6;
+var SSE_STALL_TIMEOUT_MS = 45e3;
 var TOOL_RESULT_MAX_RETRIES = 3;
 var CONVERSATION_PAGE_SIZE = 50;
 function sseReconnectDelayMs(attempt) {
@@ -1436,6 +1454,7 @@ var ChatSession = class {
       agent_name: options?.agentName,
       plan_mode: options?.planMode,
       image_mode: options?.imageMode,
+      video_mode: options?.videoMode,
       goal: options?.goal,
       // Per-request model choice (client-side model selection).
       provider: options?.provider,
@@ -1524,14 +1543,23 @@ var ChatSession = class {
   async consumeEventStream(jobId, conversationId, messageId, executeClientTools) {
     const signal = this.abortController?.signal;
     for (let attempt = 0; ; attempt++) {
-      const stream = this.client.streamJobEvents(jobId, this.lastSeq, signal);
+      if (signal?.aborted) return;
+      const attemptController = new AbortController();
+      const linkAbort = () => attemptController.abort();
+      signal?.addEventListener("abort", linkAbort);
       let sawTerminal;
       try {
+        const stream = this.client.streamJobEvents(
+          jobId,
+          this.lastSeq,
+          attemptController.signal
+        );
         sawTerminal = await this.pumpStream(
           stream,
           conversationId,
           messageId,
-          executeClientTools
+          executeClientTools,
+          () => attemptController.abort()
         );
       } catch (err) {
         if (signal?.aborted) return;
@@ -1541,6 +1569,8 @@ var ChatSession = class {
         if (attempt >= SSE_MAX_RECONNECTS) throw err;
         await this.sleepUnlessAborted(sseReconnectDelayMs(attempt + 1), signal);
         continue;
+      } finally {
+        signal?.removeEventListener("abort", linkAbort);
       }
       if (sawTerminal || signal?.aborted) return;
       if (attempt >= SSE_MAX_RECONNECTS) {
@@ -1553,35 +1583,66 @@ var ChatSession = class {
    * Consume a single SSE stream to exhaustion. Returns whether a terminal
    * event (``message_stop`` / ``error``) was seen, so the caller can decide
    * whether an ended stream means "turn done" vs "dropped, reconnect".
+   *
+   * ``onStall`` aborts the per-attempt connection: if no event arrives within
+   * SSE_STALL_TIMEOUT_MS (backend keepalives land every 15s), the stream is a
+   * zombie — ``reader.read()`` will never settle — so we kill the fetch and
+   * throw a ConnectionError, feeding the caller's reconnect-from-lastSeq loop.
    */
-  async pumpStream(stream, conversationId, messageId, executeClientTools) {
+  async pumpStream(stream, conversationId, messageId, executeClientTools, onStall) {
     let sawTerminal = false;
-    for await (const raw of stream) {
-      let parsed;
-      try {
-        const data = JSON.parse(raw.data);
-        if (typeof data !== "object" || data === null || typeof data.type !== "string") {
-          if (typeof data?.seq === "number") {
+    const iterator = stream[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        const next = iterator.next();
+        let stallTimer;
+        const stall = new Promise((_, reject) => {
+          stallTimer = setTimeout(() => {
+            reject(
+              new ConnectionError(
+                `Stream stalled: no events for ${SSE_STALL_TIMEOUT_MS}ms`
+              )
+            );
+            onStall?.();
+          }, SSE_STALL_TIMEOUT_MS);
+        });
+        let result;
+        try {
+          result = await Promise.race([next, stall]);
+        } finally {
+          clearTimeout(stallTimer);
+        }
+        if (result.done) break;
+        const raw = result.value;
+        let parsed;
+        try {
+          const data = JSON.parse(raw.data);
+          if (typeof data !== "object" || data === null || typeof data.type !== "string") {
+            if (typeof data?.seq === "number") {
+              this.lastSeq = data.seq;
+            }
+            continue;
+          }
+          parsed = data;
+          if (typeof data.seq === "number") {
             this.lastSeq = data.seq;
           }
+        } catch {
           continue;
         }
-        parsed = data;
-        if (typeof data.seq === "number") {
-          this.lastSeq = data.seq;
+        if (parsed.type === "message_stop" || parsed.type === "error") {
+          sawTerminal = true;
         }
-      } catch {
-        continue;
-      }
-      if (parsed.type === "message_stop" || parsed.type === "error") {
-        sawTerminal = true;
+        await this.dispatchWireEvent(
+          parsed,
+          conversationId,
+          messageId,
+          executeClientTools
+        );
       }
-      await this.dispatchWireEvent(
-        parsed,
-        conversationId,
-        messageId,
-        executeClientTools
-      );
+    } finally {
+      void iterator.return?.(void 0).catch(() => {
+      });
     }
     return sawTerminal;
   }
@@ -2143,6 +2204,7 @@ var StreamManager = class {
         uploadIds: options?.uploadIds,
         planMode: options?.planMode,
         imageMode: options?.imageMode,
+        videoMode: options?.videoMode,
         goal: options?.goal,
         provider: options?.provider,
         model: options?.model,