assistant-cloud 0.1.41 → 0.1.43

package/dist/runTelemetry.js

@@ -0,0 +1,82 @@
+//#region src/runTelemetry.ts
+const MAX_TELEMETRY_TEXT_LENGTH = 5e4;
+const BASE64_PATTERN = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+/**
+* Clamps a string to the size the runs endpoint accepts for a single span
+* field.
+*/
+function truncateRunTelemetryText(value) {
+	if (value.length <= MAX_TELEMETRY_TEXT_LENGTH) return value;
+	return value.slice(0, MAX_TELEMETRY_TEXT_LENGTH);
+}
+function safeStringify(value) {
+	if (value == null) return void 0;
+	try {
+		return truncateRunTelemetryText(JSON.stringify(value));
+	} catch {
+		return;
+	}
+}
+function summarizeMcpResult(value) {
+	if (value == null) return void 0;
+	try {
+		const parsed = typeof value === "string" ? JSON.parse(value) : value;
+		if (Array.isArray(parsed)) {
+			const summarized = parsed.map((item) => {
+				if (item && typeof item === "object" && item.type) {
+					if ((item.type === "image" || item.type === "audio") && typeof item.data === "string" && BASE64_PATTERN.test(item.data.slice(0, 200))) {
+						const sizeKB = (item.data.length * 3 / 4 / 1024).toFixed(1);
+						return {
+							...item,
+							data: `[${item.type}: ${sizeKB}KB]`
+						};
+					}
+				}
+				return item;
+			});
+			return truncateRunTelemetryText(JSON.stringify(summarized));
+		}
+	} catch {}
+	return safeStringify(value);
+}
+/**
+* Serializes one tool call into the shape the runs endpoint accepts. An `mcp`
+* source has its result summarized, because MCP content blocks carry inline
+* base64 image and audio payloads that would otherwise dominate the report.
+*/
+function createRunTelemetryToolCall(init) {
+	const { toolName, toolCallId, args, argsText, result, toolSource } = init;
+	const call = {
+		tool_name: toolName,
+		tool_call_id: toolCallId
+	};
+	const toolArgs = argsText != null ? truncateRunTelemetryText(argsText) : safeStringify(args);
+	if (toolArgs !== void 0) call.tool_args = toolArgs;
+	const toolResult = toolSource === "mcp" ? summarizeMcpResult(result) : safeStringify(result);
+	if (toolResult !== void 0) call.tool_result = toolResult;
+	if (toolSource) call.tool_source = toolSource;
+	return call;
+}
+/**
+* Resolves the token counts a provider reports under any of the names the AI
+* SDK has used: the current top-level ones, the legacy prompt/completion pair,
+* and the v7 token detail objects. Returns undefined when no count is present,
+* so callers can tell an empty usage object from a zeroed one.
+*/
+function normalizeRunTelemetryUsage(usage) {
+	const inputTokens = usage.inputTokens ?? usage.promptTokens;
+	const outputTokens = usage.outputTokens ?? usage.completionTokens;
+	const reasoningTokens = usage.reasoningTokens ?? usage.outputTokenDetails?.reasoningTokens;
+	const cachedInputTokens = usage.cachedInputTokens ?? usage.inputTokenDetails?.cacheReadTokens;
+	if (inputTokens == null && outputTokens == null && reasoningTokens == null && cachedInputTokens == null) return;
+	return {
+		...inputTokens != null ? { inputTokens } : void 0,
+		...outputTokens != null ? { outputTokens } : void 0,
+		...reasoningTokens != null ? { reasoningTokens } : void 0,
+		...cachedInputTokens != null ? { cachedInputTokens } : void 0
+	};
+}
+//#endregion
+export { createRunTelemetryToolCall, normalizeRunTelemetryUsage, truncateRunTelemetryText };
+
+//# sourceMappingURL=runTelemetry.js.map

package/dist/runTelemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTelemetry.js","names":[],"sources":["../src/runTelemetry.ts"],"sourcesContent":["import type { SamplingCallData } from \"./instrumentMcpSampling\";\n\nconst MAX_TELEMETRY_TEXT_LENGTH = 50_000;\n\nconst BASE64_PATTERN = /^[A-Za-z0-9+/]{100,}={0,2}$/;\n\nexport type AssistantCloudRunReportToolCall = {\n  tool_name: string;\n  tool_call_id: string;\n  tool_args?: string;\n  tool_result?: string;\n  tool_source?: \"mcp\" | \"frontend\" | \"backend\";\n  start_ms?: number;\n  end_ms?: number;\n  sampling_calls?: SamplingCallData[];\n};\n\n/**\n * Clamps a string to the size the runs endpoint accepts for a single span\n * field.\n */\nexport function truncateRunTelemetryText(value: string): string {\n  if (value.length <= MAX_TELEMETRY_TEXT_LENGTH) return value;\n  return value.slice(0, MAX_TELEMETRY_TEXT_LENGTH);\n}\n\nfunction safeStringify(value: unknown): string | undefined {\n  if (value == null) return undefined;\n  try {\n    return truncateRunTelemetryText(JSON.stringify(value));\n  } catch {\n    return undefined;\n  }\n}\n\nfunction summarizeMcpResult(value: unknown): string | undefined {\n  if (value == null) return undefined;\n  try {\n    const parsed = typeof value === \"string\" ? JSON.parse(value) : value;\n    if (Array.isArray(parsed)) {\n      const summarized = parsed.map((item) => {\n        if (item && typeof item === \"object\" && item.type) {\n          if (\n            (item.type === \"image\" || item.type === \"audio\") &&\n            typeof item.data === \"string\" &&\n            BASE64_PATTERN.test(item.data.slice(0, 200))\n          ) {\n            const sizeKB = ((item.data.length * 3) / 4 / 1024).toFixed(1);\n            return { ...item, data: `[${item.type}: ${sizeKB}KB]` };\n          }\n        }\n        return item;\n      });\n      return truncateRunTelemetryText(JSON.stringify(summarized));\n    }\n  } catch {\n    // not JSON array, fall through\n  }\n  return safeStringify(value);\n}\n\nexport type RunTelemetryToolCallInit = {\n  toolName: string;\n  toolCallId: string;\n  args?: unknown;\n  /**\n   * Pre-serialized arguments, used in place of serializing `args`. Values over\n   * the span size are clamped before they are included in the report.\n   */\n  argsText?: string | undefined;\n  result?: unknown;\n  toolSource?: \"mcp\" | \"frontend\" | \"backend\" | undefined;\n};\n\n/**\n * Serializes one tool call into the shape the runs endpoint accepts. An `mcp`\n * source has its result summarized, because MCP content blocks carry inline\n * base64 image and audio payloads that would otherwise dominate the report.\n */\nexport function createRunTelemetryToolCall(\n  init: RunTelemetryToolCallInit,\n): AssistantCloudRunReportToolCall {\n  const { toolName, toolCallId, args, argsText, result, toolSource } = init;\n  const call: AssistantCloudRunReportToolCall = {\n    tool_name: toolName,\n    tool_call_id: toolCallId,\n  };\n  const toolArgs =\n    argsText != null ? truncateRunTelemetryText(argsText) : safeStringify(args);\n  if (toolArgs !== undefined) call.tool_args = toolArgs;\n  const toolResult =\n    toolSource === \"mcp\" ? summarizeMcpResult(result) : safeStringify(result);\n  if (toolResult !== undefined) call.tool_result = toolResult;\n  if (toolSource) call.tool_source = toolSource;\n  return call;\n}\n\nexport type RunTelemetryUsage = {\n  inputTokens?: number;\n  outputTokens?: number;\n  reasoningTokens?: number;\n  cachedInputTokens?: number;\n};\n\nexport type RunTelemetryUsageInit = RunTelemetryUsage & {\n  promptTokens?: number;\n  completionTokens?: number;\n  inputTokenDetails?: { cacheReadTokens?: number };\n  outputTokenDetails?: { reasoningTokens?: number };\n};\n\n/**\n * Resolves the token counts a provider reports under any of the names the AI\n * SDK has used: the current top-level ones, the legacy prompt/completion pair,\n * and the v7 token detail objects. Returns undefined when no count is present,\n * so callers can tell an empty usage object from a zeroed one.\n */\nexport function normalizeRunTelemetryUsage(\n  usage: RunTelemetryUsageInit,\n): RunTelemetryUsage | undefined {\n  const inputTokens = usage.inputTokens ?? usage.promptTokens;\n  const outputTokens = usage.outputTokens ?? usage.completionTokens;\n  // AI SDK v7 moved these under token detail objects; v6 kept them top-level.\n  const reasoningTokens =\n    usage.reasoningTokens ?? usage.outputTokenDetails?.reasoningTokens;\n  const cachedInputTokens =\n    usage.cachedInputTokens ?? usage.inputTokenDetails?.cacheReadTokens;\n\n  if (\n    inputTokens == null &&\n    outputTokens == null &&\n    reasoningTokens == null &&\n    cachedInputTokens == null\n  ) {\n    return undefined;\n  }\n\n  return {\n    ...(inputTokens != null ? { inputTokens } : undefined),\n    ...(outputTokens != null ? { outputTokens } : undefined),\n    ...(reasoningTokens != null ? { reasoningTokens } : undefined),\n    ...(cachedInputTokens != null ? { cachedInputTokens } : undefined),\n  };\n}\n"],"mappings":";AAEA,MAAM,4BAA4B;AAElC,MAAM,iBAAiB;;;;;AAiBvB,SAAgB,yBAAyB,OAAuB;CAC9D,IAAI,MAAM,UAAU,2BAA2B,OAAO;CACtD,OAAO,MAAM,MAAM,GAAG,yBAAyB;AACjD;AAEA,SAAS,cAAc,OAAoC;CACzD,IAAI,SAAS,MAAM,OAAO,KAAA;CAC1B,IAAI;EACF,OAAO,yBAAyB,KAAK,UAAU,KAAK,CAAC;CACvD,QAAQ;EACN;CACF;AACF;AAEA,SAAS,mBAAmB,OAAoC;CAC9D,IAAI,SAAS,MAAM,OAAO,KAAA;CAC1B,IAAI;EACF,MAAM,SAAS,OAAO,UAAU,WAAW,KAAK,MAAM,KAAK,IAAI;EAC/D,IAAI,MAAM,QAAQ,MAAM,GAAG;GACzB,MAAM,aAAa,OAAO,KAAK,SAAS;IACtC,IAAI,QAAQ,OAAO,SAAS,YAAY,KAAK,MAExC;UAAA,KAAK,SAAS,WAAW,KAAK,SAAS,YACxC,OAAO,KAAK,SAAS,YACrB,eAAe,KAAK,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC,GAC3C;MACA,MAAM,UAAW,KAAK,KAAK,SAAS,IAAK,IAAI,KAAA,CAAM,QAAQ,CAAC;MAC5D,OAAO;OAAE,GAAG;OAAM,MAAM,IAAI,KAAK,KAAK,IAAI,OAAO;MAAK;KACxD;;IAEF,OAAO;GACT,CAAC;GACD,OAAO,yBAAyB,KAAK,UAAU,UAAU,CAAC;EAC5D;CACF,QAAQ,CAER;CACA,OAAO,cAAc,KAAK;AAC5B;;;;;;AAoBA,SAAgB,2BACd,MACiC;CACjC,MAAM,EAAE,UAAU,YAAY,MAAM,UAAU,QAAQ,eAAe;CACrE,MAAM,OAAwC;EAC5C,WAAW;EACX,cAAc;CAChB;CACA,MAAM,WACJ,YAAY,OAAO,yBAAyB,QAAQ,IAAI,cAAc,IAAI;CAC5E,IAAI,aAAa,KAAA,GAAW,KAAK,YAAY;CAC7C,MAAM,aACJ,eAAe,QAAQ,mBAAmB,MAAM,IAAI,cAAc,MAAM;CAC1E,IAAI,eAAe,KAAA,GAAW,KAAK,cAAc;CACjD,IAAI,YAAY,KAAK,cAAc;CACnC,OAAO;AACT;;;;;;;AAsBA,SAAgB,2BACd,OAC+B;CAC/B,MAAM,cAAc,MAAM,eAAe,MAAM;CAC/C,MAAM,eAAe,MAAM,gBAAgB,MAAM;CAEjD,MAAM,kBACJ,MAAM,mBAAmB,MAAM,oBAAoB;CACrD,MAAM,oBACJ,MAAM,qBAAqB,MAAM,mBAAmB;CAEtD,IACE,eAAe,QACf,gBAAgB,QAChB,mBAAmB,QACnB,qBAAqB,MAErB;CAGF,OAAO;EACL,GAAI,eAAe,OAAO,EAAE,YAAY,IAAI,KAAA;EAC5C,GAAI,gBAAgB,OAAO,EAAE,aAAa,IAAI,KAAA;EAC9C,GAAI,mBAAmB,OAAO,EAAE,gBAAgB,IAAI,KAAA;EACpD,GAAI,qBAAqB,OAAO,EAAE,kBAAkB,IAAI,KAAA;CAC1D;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-cloud",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "Cloud integration for assistant-ui",
   "keywords": [
     "assistant",
@@ -27,12 +27,12 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.38"
+    "assistant-stream": "^0.3.41"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "vitest": "^4.1.10",
-    "@assistant-ui/x-buildutils": "0.0.23"
+    "@assistant-ui/x-buildutils": "0.0.25",
+    "@types/node": "^26.4.0",
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public",

package/src/AssistantCloud.ts

@@ -33,6 +33,6 @@ export class AssistantCloud {
         ? { enabled: false }
         : t === true || t === undefined
           ? { enabled: true }
-          : { enabled: t.enabled !== false, ...t };
+          : { ...t, enabled: t.enabled !== false };
   }
 }

package/src/AssistantCloudAPI.ts

@@ -139,16 +139,17 @@ export class AssistantCloudAPI {
 
     if (!response.ok) {
       const text = await response.text();
+      let message: string | undefined;
       try {
         const body = JSON.parse(text);
-        throw new CloudAPIError(body.message, response.status);
-      } catch (error) {
-        if (error instanceof CloudAPIError) throw error;
-        throw new CloudAPIError(
-          `Request failed with status ${response.status}, ${text}`,
-          response.status,
-        );
-      }
+        if (typeof body?.message === "string" && body.message.length > 0) {
+          message = body.message;
+        }
+      } catch {}
+      throw new CloudAPIError(
+        message ?? `Request failed with status ${response.status}, ${text}`,
+        response.status,
+      );
     }
 
     return response;

package/src/AssistantCloudAuthStrategy.ts

@@ -4,6 +4,34 @@ import {
   readCloudString,
 } from "./cloudResponse";
 
+const AUTH_TOKEN_REQUEST_TIMEOUT_MS = 30_000;
+
+const withAuthTokenDeadline = async <T>(
+  operation: string,
+  run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> => {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, AUTH_TOKEN_REQUEST_TIMEOUT_MS);
+
+  try {
+    return await run(controller.signal);
+  } catch (error) {
+    if (timedOut) {
+      throw new Error(
+        `Assistant Cloud ${operation} timed out after ${AUTH_TOKEN_REQUEST_TIMEOUT_MS}ms`,
+        { cause: error },
+      );
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
 export type AssistantCloudAuthStrategy = {
   readonly strategy: "anon" | "jwt" | "api-key";
   getAuthHeaders(): Promise<Record<string, string> | false>;
@@ -247,6 +275,52 @@ const removeRefreshToken = (baseUrl: string): void => {
   } catch {}
 };
 
+// In-flight sharing follows refresh-token storage scope to isolate server requests.
+const anonymousAuthTokenRequests = new WeakMap<
+  Storage,
+  Map<string, Promise<string | null>>
+>();
+
+const getWebLockManager = (): LockManager | null => {
+  if (!("navigator" in globalThis)) return null;
+  return (
+    (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks ??
+    null
+  );
+};
+
+const getAnonymousAuthLockName = (baseUrl: string): string =>
+  `assistant-cloud:anonymous-auth:${baseUrl}`;
+
+const getSharedAnonymousAuthToken = (
+  baseUrl: string,
+  requestToken: () => Promise<string | null>,
+): Promise<string | null> => {
+  const storage = getLocalStorage();
+  if (!storage) return requestToken();
+
+  let storageRequests = anonymousAuthTokenRequests.get(storage);
+  if (!storageRequests) {
+    storageRequests = new Map();
+    anonymousAuthTokenRequests.set(storage, storageRequests);
+  }
+
+  const activeRequest = storageRequests.get(baseUrl);
+  if (activeRequest) return activeRequest;
+
+  const locks = getWebLockManager();
+  const request = locks
+    ? locks.request(getAnonymousAuthLockName(baseUrl), requestToken)
+    : requestToken();
+  const sharedRequest = request.finally(() => {
+    if (storageRequests.get(baseUrl) === sharedRequest) {
+      storageRequests.delete(baseUrl);
+    }
+  });
+  storageRequests.set(baseUrl, sharedRequest);
+  return sharedRequest;
+};
+
 export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthStrategy {
   public readonly strategy = "anon";
 
@@ -255,70 +329,90 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
 
   constructor(baseUrl: string) {
     this.baseUrl = baseUrl;
-    this.jwtStrategy = new AssistantCloudJWTAuthStrategy(async () => {
+    const requestAuthToken = async (): Promise<string | null> => {
       const currentTime = Date.now();
       const storedRefreshToken = readRefreshToken(this.baseUrl);
 
       if (storedRefreshToken) {
         const refreshExpiry = new Date(storedRefreshToken.expires_at).getTime();
         if (refreshExpiry - currentTime > 30 * 1000) {
-          const response = await fetch(
-            `${this.baseUrl}/v1/auth/tokens/refresh`,
-            {
-              method: "POST",
-              headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ refresh_token: storedRefreshToken.token }),
+          const refreshedAccessToken = await withAuthTokenDeadline(
+            "refresh token request",
+            async (signal) => {
+              const response = await fetch(
+                `${this.baseUrl}/v1/auth/tokens/refresh`,
+                {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify({
+                    refresh_token: storedRefreshToken.token,
+                  }),
+                  signal,
+                },
+              );
+
+              if (response.ok) {
+                const { data, accessToken } = await readAuthTokenResponse(
+                  response,
+                  "refresh auth token response",
+                );
+                if (data.refresh_token != null) {
+                  writeRefreshToken(
+                    this.baseUrl,
+                    readRefreshTokenResponse(
+                      data.refresh_token,
+                      "refresh auth token response.refresh_token",
+                    ),
+                  );
+                }
+                return accessToken;
+              }
+
+              if (response.status === 429 || response.status >= 500) {
+                throw new Error(
+                  `Assistant Cloud token refresh failed with status ${response.status}`,
+                );
+              }
+
+              return null;
             },
           );
-
-          if (response.ok) {
-            const { data, accessToken } = await readAuthTokenResponse(
-              response,
-              "refresh auth token response",
-            );
-            if (data.refresh_token != null) {
-              writeRefreshToken(
-                this.baseUrl,
-                readRefreshTokenResponse(
-                  data.refresh_token,
-                  "refresh auth token response.refresh_token",
-                ),
-              );
-            }
-            return accessToken;
-          }
-
-          if (response.status === 429 || response.status >= 500) {
-            throw new Error(
-              `Assistant Cloud token refresh failed with status ${response.status}`,
-            );
-          }
+          if (refreshedAccessToken !== null) return refreshedAccessToken;
         } else {
           removeRefreshToken(this.baseUrl);
         }
       }
 
       // No valid refresh token; request a new anonymous token
-      const response = await fetch(`${this.baseUrl}/v1/auth/tokens/anonymous`, {
-        method: "POST",
-      });
+      return withAuthTokenDeadline(
+        "anonymous token request",
+        async (signal) => {
+          const response = await fetch(
+            `${this.baseUrl}/v1/auth/tokens/anonymous`,
+            { method: "POST", signal },
+          );
 
-      if (!response.ok) return null;
+          if (!response.ok) return null;
 
-      const { data, accessToken } = await readAuthTokenResponse(
-        response,
-        "anonymous auth token response",
-      );
+          const { data, accessToken } = await readAuthTokenResponse(
+            response,
+            "anonymous auth token response",
+          );
 
-      writeRefreshToken(
-        this.baseUrl,
-        readRefreshTokenResponse(
-          data.refresh_token,
-          "anonymous auth token response.refresh_token",
-        ),
+          writeRefreshToken(
+            this.baseUrl,
+            readRefreshTokenResponse(
+              data.refresh_token,
+              "anonymous auth token response.refresh_token",
+            ),
+          );
+          return accessToken;
+        },
       );
-      return accessToken;
-    });
+    };
+    this.jwtStrategy = new AssistantCloudJWTAuthStrategy(() =>
+      getSharedAnonymousAuthToken(this.baseUrl, requestAuthToken),
+    );
   }
 
   public async getAuthHeaders(): Promise<Record<string, string> | false> {

package/src/AssistantCloudRuns.ts

@@ -1,5 +1,5 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
-import type { SamplingCallData } from "./instrumentMcpSampling";
+import type { AssistantCloudRunReportToolCall } from "./runTelemetry";
 import { AssistantStream, PlainTextDecoder } from "assistant-stream";
 import {
   CloudResponseError,
@@ -13,17 +13,6 @@ type AssistantCloudRunsStreamBody = {
   messages: readonly unknown[]; // TODO type
 };
 
-type ReportToolCall = {
-  tool_name: string;
-  tool_call_id: string;
-  tool_args?: string;
-  tool_result?: string;
-  tool_source?: "mcp" | "frontend" | "backend";
-  start_ms?: number;
-  end_ms?: number;
-  sampling_calls?: SamplingCallData[];
-};
-
 // NOTE: Keep this payload shape aligned with the strict runtime validator in
 // assistant-cloud: apps/aui-cloud-api/src/endpoints/runs/create.ts
 // (createRunSchema). New telemetry fields must be added in both repos together.
@@ -31,13 +20,13 @@ export type AssistantCloudRunReport = {
   thread_id: string;
   status: "completed" | "incomplete" | "error";
   total_steps?: number;
-  tool_calls?: ReportToolCall[];
+  tool_calls?: AssistantCloudRunReportToolCall[];
   steps?: {
     input_tokens?: number;
     output_tokens?: number;
     reasoning_tokens?: number;
     cached_input_tokens?: number;
-    tool_calls?: ReportToolCall[];
+    tool_calls?: AssistantCloudRunReportToolCall[];
     start_ms?: number;
     end_ms?: number;
   }[];

package/src/CloudMessagePersistence.ts

@@ -39,32 +39,36 @@ export class CloudMessagePersistence {
     content: ReadonlyJSONObject,
   ): Promise<void> {
     const cloud = this.getCloud();
-    // Resolve parent's remote ID if it exists (may be a promise if concurrent)
-    const resolvedParentId = parentId
-      ? ((await this.idMapping[parentId]) ?? parentId)
-      : null;
+    const existing = this.idMapping[messageId];
+    if (existing instanceof Promise) {
+      await existing;
+      return;
+    }
 
-    const task = cloud.threads.messages
-      .create(threadId, {
+    const task = (async () => {
+      const resolvedParentId = parentId
+        ? ((await this.idMapping[parentId]) ?? parentId)
+        : null;
+      const { message_id } = await cloud.threads.messages.create(threadId, {
         parent_id: resolvedParentId,
         format,
         content,
-      })
-      .then(({ message_id }) => {
-        this.idMapping[messageId] = message_id;
-        return message_id;
-      })
-      .catch((err) => {
-        // Only delete if we're still the active task (avoids clobbering a retry)
-        if (this.idMapping[messageId] === task) {
-          delete this.idMapping[messageId];
-        }
-        throw err;
       });
+      return message_id;
+    })();
 
-    // Store the promise immediately so concurrent appends can await it
     this.idMapping[messageId] = task;
-    return task.then(() => {});
+    try {
+      const remoteId = await task;
+      if (this.idMapping[messageId] === task) {
+        this.idMapping[messageId] = remoteId;
+      }
+    } catch (err) {
+      if (this.idMapping[messageId] === task) {
+        delete this.idMapping[messageId];
+      }
+      throw err;
+    }
   }
 
   /**

package/src/generateThreadTitle.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "./AssistantCloud";
+import { generateThreadTitle } from "./generateThreadTitle";
+
+const titleStream = (...chunks: { type: string; textDelta?: string }[]) =>
+  new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  });
+
+const createCloud = (stream: ReadableStream<unknown>) => {
+  const update = vi.fn().mockResolvedValue(undefined);
+  const run = vi.fn().mockResolvedValue(stream);
+  const cloud = {
+    threads: { update },
+    runs: { stream: run },
+  } as unknown as AssistantCloud;
+  return { cloud, update, run };
+};
+
+describe("generateThreadTitle", () => {
+  it("accumulates text deltas and updates the thread title", async () => {
+    const { cloud, run, update } = createCloud(
+      titleStream(
+        { type: "text-delta", textDelta: "Weather " },
+        { type: "text-delta", textDelta: "chat" },
+      ),
+    );
+
+    await expect(
+      generateThreadTitle(cloud, {
+        threadId: "thread-1",
+        messages: [
+          {
+            role: "user",
+            content: [{ type: "text", text: "What is the weather today?" }],
+          },
+        ],
+      }),
+    ).resolves.toBe("Weather chat");
+
+    expect(run).toHaveBeenCalledExactlyOnceWith({
+      thread_id: "thread-1",
+      assistant_id: "system/thread_title",
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: "What is the weather today?" }],
+        },
+      ],
+    });
+    expect(update).toHaveBeenCalledExactlyOnceWith("thread-1", {
+      title: "Weather chat",
+    });
+  });
+
+  it("returns null without updating when the stream has no text", async () => {
+    const { cloud, update } = createCloud(titleStream());
+
+    await expect(
+      generateThreadTitle(cloud, {
+        threadId: "thread-1",
+        messages: [],
+      }),
+    ).resolves.toBeNull();
+
+    expect(update).not.toHaveBeenCalled();
+  });
+});

package/src/generateThreadTitle.ts

@@ -0,0 +1,38 @@
+import type { AssistantCloud } from "./AssistantCloud";
+
+export async function generateThreadTitle(
+  cloud: AssistantCloud,
+  options: {
+    threadId: string;
+    messages: readonly {
+      role: string;
+      content: readonly { type: "text"; text: string }[];
+    }[];
+  },
+): Promise<string | null> {
+  const stream = await cloud.runs.stream({
+    thread_id: options.threadId,
+    assistant_id: "system/thread_title",
+    messages: options.messages,
+  });
+
+  let title = "";
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value: chunk } = await reader.read();
+      if (done) break;
+      if (chunk.type === "text-delta") {
+        title += chunk.textDelta;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  if (title) {
+    await cloud.threads.update(options.threadId, { title });
+  }
+
+  return title || null;
+}

package/src/index.ts

@@ -2,7 +2,17 @@ export type { CloudMessage } from "./AssistantCloudThreadMessages";
 export type { AssistantCloudTelemetryConfig } from "./AssistantCloudAPI";
 export { CloudAPIError } from "./AssistantCloudAPI";
 export { CloudResponseError } from "./cloudResponse";
+export { generateThreadTitle } from "./generateThreadTitle";
 export type { AssistantCloudRunReport } from "./AssistantCloudRuns";
+export {
+  createRunTelemetryToolCall,
+  normalizeRunTelemetryUsage,
+  truncateRunTelemetryText,
+  type AssistantCloudRunReportToolCall,
+  type RunTelemetryToolCallInit,
+  type RunTelemetryUsage,
+  type RunTelemetryUsageInit,
+} from "./runTelemetry";
 export { AssistantCloud } from "./AssistantCloud";
 export { CloudMessagePersistence } from "./CloudMessagePersistence";
 export {