assistant-cloud 0.2.2 → 0.2.3

package/src/AssistantCloudEvents.ts

@@ -30,11 +30,23 @@ export type AssistantCloudEvent = {
 const FLUSH_SIZE = 20;
 const MAX_BATCH_SIZE = 50;
 const FLUSH_DELAY_MS = 2_000;
+const RETRY_DELAYS_MS = [250, 1_000] as const;
+const pendingClearers = new WeakMap<AssistantCloudEvents, () => void>();
+
+export const clearPendingAssistantCloudEvents = (
+  events: AssistantCloudEvents,
+): void => {
+  pendingClearers.get(events)?.();
+};
 
 export class AssistantCloudEvents {
   private buffer: AssistantCloudEvent[] = [];
   private timer: ReturnType<typeof setTimeout> | undefined;
   private flushing: Promise<void> | undefined;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+  private resolveRetryDelay: (() => void) | undefined;
+  private bestEffortRequested = false;
+  private generation = 0;
 
   private readonly cloud: AssistantCloudAPI;
   private readonly isEnabled: () => boolean;
@@ -44,6 +56,7 @@ export class AssistantCloudEvents {
   constructor(cloud: AssistantCloudAPI, isEnabled: () => boolean) {
     this.cloud = cloud;
     this.isEnabled = isEnabled;
+    pendingClearers.set(this, () => this.clearPending());
   }
 
   public track(event: AssistantCloudEvent): void {
@@ -52,7 +65,7 @@ export class AssistantCloudEvents {
     this.listen();
     this.buffer.push(normalizeEvent(event));
     if (this.buffer.length >= FLUSH_SIZE) {
-      void this.flush();
+      void this.flush(true);
       return;
     }
 
@@ -68,55 +81,70 @@ export class AssistantCloudEvents {
       return;
     }
     this.listening = true;
-    window.addEventListener("pagehide", this.flush);
+    window.addEventListener("pagehide", this.flushBestEffort);
     document.addEventListener("visibilitychange", this.onVisibilityChange);
   }
 
   private unlisten(): void {
     if (!this.listening) return;
     this.listening = false;
-    window.removeEventListener("pagehide", this.flush);
+    window.removeEventListener("pagehide", this.flushBestEffort);
     document.removeEventListener("visibilitychange", this.onVisibilityChange);
   }
 
   public dispose(): void {
     this.unlisten();
     this.clearFlushTimer();
-    void this.flush();
+    void this.flushBestEffort();
+  }
+
+  private clearPending(): void {
+    this.generation++;
+    this.buffer = [];
+    this.clearFlushTimer();
+    this.interruptRetryDelay();
+    this.unlisten();
   }
 
   private onVisibilityChange = () => {
     if (document.visibilityState === "hidden") {
-      void this.flush();
+      void this.flushBestEffort();
     }
   };
 
-  private flush = async (): Promise<void> => {
+  private flushBestEffort = () => {
+    if (this.flushing) {
+      this.bestEffortRequested = true;
+      this.interruptRetryDelay();
+    }
+    return this.flush(false);
+  };
+
+  private flush = async (retryFailures: boolean): Promise<void> => {
     if (!this.isEnabled()) {
-      this.buffer = [];
-      this.clearFlushTimer();
-      this.unlisten();
+      this.clearPending();
       return;
     }
     if (this.flushing) return this.flushing;
 
     this.clearFlushTimer();
-    const task = this.flushPending();
+    const task = this.flushPending(retryFailures);
     this.flushing = task;
     void task.then(() => {
       if (this.flushing !== task) return;
       this.flushing = undefined;
+      this.bestEffortRequested = false;
       if (this.buffer.length === 0) {
         this.clearFlushTimer();
         this.unlisten();
       } else {
-        void this.flush();
+        void this.flush(true);
       }
     });
     return task;
   };
 
-  private async flushPending(): Promise<void> {
+  private async flushPending(retryFailures: boolean): Promise<void> {
     while (this.buffer.length > 0) {
       if (!this.isEnabled()) {
         this.buffer = [];
@@ -124,21 +152,54 @@ export class AssistantCloudEvents {
       }
 
       const events = this.buffer.splice(0, MAX_BATCH_SIZE);
-      try {
-        await this.cloud.makeRequest("/events", {
-          method: "POST",
-          body: { events },
-          keepalive: true,
-        });
-      } catch {}
+      const generation = this.generation;
+      for (let attempt = 0; ; attempt++) {
+        try {
+          await this.cloud.makeRequest("/events", {
+            method: "POST",
+            body: { events },
+            keepalive: true,
+          });
+          if (generation !== this.generation) return;
+          break;
+        } catch {
+          if (generation !== this.generation) return;
+          const delay =
+            retryFailures && !this.bestEffortRequested
+              ? RETRY_DELAYS_MS[attempt]
+              : undefined;
+          if (delay === undefined) break;
+          await this.waitForRetry(delay);
+          if (generation !== this.generation) return;
+          if (!this.isEnabled()) return this.clearPending();
+          if (this.bestEffortRequested) break;
+        }
+      }
     }
   }
 
+  private waitForRetry(delay: number): Promise<void> {
+    return new Promise((resolve) => {
+      const finish = () => {
+        this.retryTimer = undefined;
+        this.resolveRetryDelay = undefined;
+        resolve();
+      };
+      this.resolveRetryDelay = finish;
+      this.retryTimer = setTimeout(finish, delay);
+    });
+  }
+
+  private interruptRetryDelay(): void {
+    if (this.retryTimer !== undefined) clearTimeout(this.retryTimer);
+    this.resolveRetryDelay?.();
+  }
+
   private scheduleFlush() {
     if (this.timer !== undefined) return;
     this.timer = setTimeout(() => {
       this.timer = undefined;
-      void this.flush();
+      void this.flush(true);
     }, FLUSH_DELAY_MS);
   }
 

package/src/AssistantCloudRuns.ts

@@ -19,7 +19,18 @@ type AssistantCloudRunsStreamBody = {
 export type AssistantCloudRunReport = {
   thread_id: string;
   status: "completed" | "incomplete" | "error";
-  outcome_type?: "aborted" | "disconnected" | "length" | "content_filter";
+  outcome_type?:
+    | "rate_limited"
+    | "validation_failed"
+    | "provider_error"
+    | "server_error"
+    | "budget_denied"
+    | "persistence_error"
+    | "aborted"
+    | "timeout"
+    | "disconnected"
+    | "length"
+    | "content_filter";
   message_id?: string;
   first_token_ms?: number;
   release?: string;
@@ -27,6 +38,7 @@ export type AssistantCloudRunReport = {
   tags?: string[];
   provider?: string;
   trace_id?: string;
+  root_span_id?: string;
   error_code?: string;
   error?: string;
   total_steps?: number;
@@ -40,15 +52,24 @@ export type AssistantCloudRunReport = {
     start_ms?: number;
     end_ms?: number;
     finish_reason?: string;
+    input?: string;
   }[];
   input_tokens?: number;
   output_tokens?: number;
   reasoning_tokens?: number;
   cached_input_tokens?: number;
+  cost_usd?: number;
+  cost_details?: {
+    input?: number;
+    input_cached_tokens?: number;
+    output?: number;
+    total?: number;
+  };
   model_id?: string;
   provider_type?: string;
   duration_ms?: number;
   output_text?: string;
+  attributes?: Record<string, unknown>;
   metadata?: Record<string, unknown>;
 };
 
@@ -62,6 +83,7 @@ export class AssistantCloudRuns {
   public __internal_getAssistantOptions(assistantId: string) {
     return {
       api: `${this.cloud._baseUrl}/v1/runs/stream`,
+      protocol: "ui-message-stream" as const,
       headers: async () => {
         const headers = await this.cloud._auth.getAuthHeaders();
         if (!headers) throw new Error("Authorization failed");
@@ -71,10 +93,18 @@ export class AssistantCloudRuns {
           "Aui-Sdk": this.cloud.sdkHeader(),
         };
       },
-      body: {
-        assistant_id: assistantId,
-        response_format: "vercel-ai-data-stream/v1",
-        thread_id: "unstable_todo",
+      body: async (options?: { threadId?: string }) => {
+        const threadId = options?.threadId;
+        if (threadId === undefined) {
+          throw new Error(
+            "Assistant Cloud runs need a thread; the thread list adapter has not assigned a remote id to this thread yet.",
+          );
+        }
+        return {
+          assistant_id: assistantId,
+          response_format: "vercel-ai-data-stream/v1",
+          thread_id: threadId,
+        };
       },
     };
   }

package/src/AssistantCloudThreadMessages.ts

@@ -19,6 +19,7 @@ export type CloudMessage = {
   updated_at: Date;
   format: "aui/v0" | string;
   content: ReadonlyJSONObject;
+  external_id?: string | null | undefined;
 };
 
 type AssistantCloudThreadMessageListQuery = {
@@ -35,6 +36,8 @@ type AssistantCloudThreadMessageCreateBody = {
   parent_id: string | null;
   format: "aui/v0" | string;
   content: ReadonlyJSONObject;
+  external_id?: string | undefined;
+  parent_external_id?: string | undefined;
 };
 
 type AssistantCloudMessageCreateResponse = {
@@ -71,6 +74,10 @@ export const decodeCloudMessage = (
     updated_at: readCloudTimestamp(message.updated_at, `${field}.updated_at`),
     format: readCloudString(message.format, `${field}.format`),
     content: readCloudJSONObject(message.content, `${field}.content`),
+    external_id: readCloudNullableString(
+      message.external_id ?? null,
+      `${field}.external_id`,
+    ),
   };
 };
 
@@ -108,7 +115,20 @@ export class AssistantCloudThreadMessages {
     const response = readCloudRecord(
       await this.cloud.makeRequest(
         `/threads/${encodeURIComponent(threadId)}/messages`,
-        { method: "POST", body },
+        {
+          method: "POST",
+          body: {
+            parent_id: body.parent_id,
+            format: body.format,
+            content: body.content,
+            ...(body.external_id !== undefined
+              ? { external_id: body.external_id }
+              : undefined),
+            ...(body.parent_external_id !== undefined
+              ? { parent_external_id: body.parent_external_id }
+              : undefined),
+          },
+        },
       ),
       "thread message create response",
     );

package/src/BackendTranscriptCopy.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "./AssistantCloud";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import { CloudMessagePersistence } from "./CloudMessagePersistence";
+
+describe("backend transcript cloud client", () => {
+  it("sends external ids only when supplied", async () => {
+    const makeRequest = vi.fn().mockResolvedValue({ message_id: "cloud-1" });
+    const messages = new AssistantCloudThreadMessages({
+      makeRequest,
+    } as unknown as AssistantCloudAPI);
+    const body = { parent_id: null, format: "aui/v0", content: {} };
+
+    await messages.create("thread-1", body);
+    expect(makeRequest).toHaveBeenLastCalledWith("/threads/thread-1/messages", {
+      method: "POST",
+      body,
+    });
+
+    await messages.create("thread-1", {
+      ...body,
+      external_id: "backend-1",
+      parent_external_id: "backend-0",
+    });
+    expect(makeRequest).toHaveBeenLastCalledWith("/threads/thread-1/messages", {
+      method: "POST",
+      body: {
+        ...body,
+        external_id: "backend-1",
+        parent_external_id: "backend-0",
+      },
+    });
+  });
+
+  it("decodes external ids and treats an absent field as null", async () => {
+    const makeRequest = vi.fn().mockResolvedValue({
+      messages: [
+        {
+          id: "cloud-1",
+          parent_id: null,
+          height: 0,
+          created_at: "2026-01-01T00:00:00.000Z",
+          updated_at: "2026-01-01T00:00:00.000Z",
+          format: "aui/v0",
+          content: {},
+          external_id: "backend-1",
+        },
+        {
+          id: "cloud-2",
+          parent_id: "cloud-1",
+          height: 1,
+          created_at: "2026-01-01T00:00:00.000Z",
+          updated_at: "2026-01-01T00:00:00.000Z",
+          format: "aui/v0",
+          content: {},
+        },
+      ],
+    });
+    const messages = new AssistantCloudThreadMessages({
+      makeRequest,
+    } as unknown as AssistantCloudAPI);
+
+    const result = await messages.list("thread-1");
+    expect(result.messages.map((message) => message.external_id)).toEqual([
+      "backend-1",
+      null,
+    ]);
+  });
+
+  it("records a resolved local to cloud message mapping", async () => {
+    const persistence = new CloudMessagePersistence({} as AssistantCloud);
+    persistence.record("backend-1", "cloud-1");
+
+    expect(persistence.isPersisted("backend-1")).toBe(true);
+    expect(await persistence.getRemoteId("backend-1")).toBe("cloud-1");
+    expect(persistence.getResolvedRemoteId("backend-1")).toBe("cloud-1");
+  });
+});

package/src/CloudEngagementReporter.ts

@@ -13,13 +13,14 @@ export type EngagementEventIds = Pick<
  * Turns the ids an integration knows (its own thread and message ids) into the
  * ids the cloud stores. A send is the one event that may create the remote
  * thread, so it asks for `awaitThread`; every other event reads the ids that
- * already exist.
+ * already exist. Returning nothing declines the event: the thread is not one
+ * the integration knows, so there is nothing to attribute it to.
  */
 export type EngagementIdResolver = (
   threadId: string,
   messageId: string | undefined,
   options: { awaitThread: boolean },
-) => EngagementEventIds | Promise<EngagementEventIds>;
+) => EngagementEventIds | undefined | Promise<EngagementEventIds | undefined>;
 
 type EngagementEventInit = Pick<AssistantCloudEvent, "value" | "props">;
 
@@ -86,9 +87,13 @@ export class CloudEngagementReporter {
   public runStopped(threadId: string): void {
     const startedAt = this.runStartedAt.get(threadId);
     if (startedAt === undefined) return;
+    const stoppedAt = Date.now();
     this.runStartedAt.delete(threadId);
+    // A stopped run is a run that ended, so the next send measures its idle
+    // time from here rather than from the last run allowed to finish.
+    remember(this.runEndedAt, threadId, stoppedAt);
     this.track("run_stopped", threadId, undefined, {
-      value: Math.max(0, Date.now() - startedAt),
+      value: Math.max(0, stoppedAt - startedAt),
     });
   }
 
@@ -223,6 +228,7 @@ export class CloudEngagementReporter {
     void Promise.resolve()
       .then(() => this.resolveIds(threadId, messageId, options))
       .then((ids) => {
+        if (!ids) return;
         if (kind === "thread_switched" && !ids.thread_id) return;
         this.getCloud().events.track({ kind, ...init, ...ids });
       })

package/src/CloudMessagePersistence.ts

@@ -111,6 +111,10 @@ export class CloudMessagePersistence {
     return typeof entry === "string" ? entry : undefined;
   }
 
+  record(localId: string, remoteId: string): void {
+    this.idMapping.set(localId, remoteId);
+  }
+
   /**
    * Load messages from the cloud and populate the ID mapping.
    *

package/src/ai-sdk/index.test.ts

@@ -79,7 +79,7 @@ describe("extractAISDKRunTelemetry", () => {
           {},
         ],
         samplingCalls: { call_2: [{ duration_ms: 20 }] },
-        modelId: "gpt-5.6-luna",
+        modelId: "gpt-6-luna",
       },
     );
 
@@ -119,7 +119,7 @@ describe("extractAISDKRunTelemetry", () => {
       totalSteps: 3,
       outputText: "Cold.",
       usage: { inputTokens: 10, outputTokens: 5 },
-      modelId: "gpt-5.6-luna",
+      modelId: "gpt-6-luna",
       metadata: message.metadata,
     });
   });