assistant-cloud 0.1.40 → 0.1.42

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { McpSamplingHandler, SamplingCallData, createSamplingCollector, wrapSamplingHandler } from "./instrumentMcpSampling.js";
+import { AssistantCloudRunReportToolCall, RunTelemetryToolCallInit, RunTelemetryUsage, RunTelemetryUsageInit, createRunTelemetryToolCall, normalizeRunTelemetryUsage, truncateRunTelemetryText } from "./runTelemetry.js";
 import { AssistantCloudRunReport } from "./AssistantCloudRuns.js";
 import { AssistantCloudTelemetryConfig, CloudAPIError } from "./AssistantCloudAPI.js";
 import { CloudMessage } from "./AssistantCloudThreadMessages.js";
@@ -6,4 +7,5 @@ import { AssistantCloud } from "./AssistantCloud.js";
 import { CloudMessagePersistence } from "./CloudMessagePersistence.js";
 import { MessageFormatAdapter, createFormattedPersistence } from "./FormattedCloudPersistence.js";
 import { CloudResponseError } from "./cloudResponse.js";
-export { AssistantCloud, type AssistantCloudRunReport, type AssistantCloudTelemetryConfig, CloudAPIError, type CloudMessage, CloudMessagePersistence, CloudResponseError, type McpSamplingHandler, type MessageFormatAdapter, type SamplingCallData, createFormattedPersistence, createSamplingCollector, wrapSamplingHandler };
+import { generateThreadTitle } from "./generateThreadTitle.js";
+export { AssistantCloud, type AssistantCloudRunReport, type AssistantCloudRunReportToolCall, type AssistantCloudTelemetryConfig, CloudAPIError, type CloudMessage, CloudMessagePersistence, CloudResponseError, type McpSamplingHandler, type MessageFormatAdapter, type RunTelemetryToolCallInit, type RunTelemetryUsage, type RunTelemetryUsageInit, type SamplingCallData, createFormattedPersistence, createRunTelemetryToolCall, createSamplingCollector, generateThreadTitle, normalizeRunTelemetryUsage, truncateRunTelemetryText, wrapSamplingHandler };

package/dist/index.js

@@ -3,5 +3,7 @@ import { CloudAPIError } from "./AssistantCloudAPI.js";
 import { AssistantCloud } from "./AssistantCloud.js";
 import { CloudMessagePersistence } from "./CloudMessagePersistence.js";
 import { createFormattedPersistence } from "./FormattedCloudPersistence.js";
+import { generateThreadTitle } from "./generateThreadTitle.js";
+import { createRunTelemetryToolCall, normalizeRunTelemetryUsage, truncateRunTelemetryText } from "./runTelemetry.js";
 import { createSamplingCollector, wrapSamplingHandler } from "./instrumentMcpSampling.js";
-export { AssistantCloud, CloudAPIError, CloudMessagePersistence, CloudResponseError, createFormattedPersistence, createSamplingCollector, wrapSamplingHandler };
+export { AssistantCloud, CloudAPIError, CloudMessagePersistence, CloudResponseError, createFormattedPersistence, createRunTelemetryToolCall, createSamplingCollector, generateThreadTitle, normalizeRunTelemetryUsage, truncateRunTelemetryText, wrapSamplingHandler };

package/dist/runTelemetry.d.ts

@@ -0,0 +1,54 @@
+import { SamplingCallData } from "./instrumentMcpSampling.js";
+//#region src/runTelemetry.d.ts
+type AssistantCloudRunReportToolCall = {
+  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[];
+};
+/**
+ * Clamps a string to the size the runs endpoint accepts for a single span
+ * field.
+ */
+declare function truncateRunTelemetryText(value: string): string;
+type RunTelemetryToolCallInit = {
+  toolName: string;
+  toolCallId: string;
+  args?: unknown;
+  /**
+   * Pre-serialized arguments, used in place of serializing `args`. Values over
+   * the span size are clamped before they are included in the report.
+   */
+  argsText?: string | undefined;
+  result?: unknown;
+  toolSource?: "mcp" | "frontend" | "backend" | undefined;
+};
+/**
+ * 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.
+ */
+declare function createRunTelemetryToolCall(init: RunTelemetryToolCallInit): AssistantCloudRunReportToolCall;
+type RunTelemetryUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+};
+type RunTelemetryUsageInit = RunTelemetryUsage & {
+  promptTokens?: number;
+  completionTokens?: number;
+};
+/**
+ * Resolves the token counts a provider reports under either the current or the
+ * legacy prompt/completion names. Returns undefined when no count is present,
+ * so callers can tell an empty usage object from a zeroed one.
+ */
+declare function normalizeRunTelemetryUsage(usage: RunTelemetryUsageInit): RunTelemetryUsage | undefined;
+//#endregion
+export { AssistantCloudRunReportToolCall, RunTelemetryToolCallInit, RunTelemetryUsage, RunTelemetryUsageInit, createRunTelemetryToolCall, normalizeRunTelemetryUsage, truncateRunTelemetryText };
+//# sourceMappingURL=runTelemetry.d.ts.map

package/dist/runTelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTelemetry.d.ts","names":[],"sources":["../src/runTelemetry.ts"],"mappings":";;KAMY;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA,iBAAiB;;;;;;iBAOH,yBAAyB;KAwC7B;EACV;EACA;EACA;;;;;EAKA;EACA;EACA;;;;;;;iBAQc,2BACd,MAAM,2BACL;KAgBS;EACV;EACA;EACA;EACA;;KAGU,wBAAwB;EAClC;EACA;;;;;;;iBAQc,2BACd,OAAO,wBACN"}

package/dist/runTelemetry.js

@@ -0,0 +1,79 @@
+//#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 either the current or the
+* legacy prompt/completion names. 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;
+	if (inputTokens == null && outputTokens == null && usage.reasoningTokens == null && usage.cachedInputTokens == null) return;
+	return {
+		...inputTokens != null ? { inputTokens } : void 0,
+		...outputTokens != null ? { outputTokens } : void 0,
+		...usage.reasoningTokens != null ? { reasoningTokens: usage.reasoningTokens } : void 0,
+		...usage.cachedInputTokens != null ? { cachedInputTokens: usage.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};\n\n/**\n * Resolves the token counts a provider reports under either the current or the\n * legacy prompt/completion names. 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\n  if (\n    inputTokens == null &&\n    outputTokens == null &&\n    usage.reasoningTokens == null &&\n    usage.cachedInputTokens == null\n  ) {\n    return undefined;\n  }\n\n  return {\n    ...(inputTokens != null ? { inputTokens } : undefined),\n    ...(outputTokens != null ? { outputTokens } : undefined),\n    ...(usage.reasoningTokens != null\n      ? { reasoningTokens: usage.reasoningTokens }\n      : undefined),\n    ...(usage.cachedInputTokens != null\n      ? { cachedInputTokens: usage.cachedInputTokens }\n      : 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;;;;;;AAmBA,SAAgB,2BACd,OAC+B;CAC/B,MAAM,cAAc,MAAM,eAAe,MAAM;CAC/C,MAAM,eAAe,MAAM,gBAAgB,MAAM;CAEjD,IACE,eAAe,QACf,gBAAgB,QAChB,MAAM,mBAAmB,QACzB,MAAM,qBAAqB,MAE3B;CAGF,OAAO;EACL,GAAI,eAAe,OAAO,EAAE,YAAY,IAAI,KAAA;EAC5C,GAAI,gBAAgB,OAAO,EAAE,aAAa,IAAI,KAAA;EAC9C,GAAI,MAAM,mBAAmB,OACzB,EAAE,iBAAiB,MAAM,gBAAgB,IACzC,KAAA;EACJ,GAAI,MAAM,qBAAqB,OAC3B,EAAE,mBAAmB,MAAM,kBAAkB,IAC7C,KAAA;CACN;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-cloud",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Cloud integration for assistant-ui",
   "keywords": [
     "assistant",
@@ -27,12 +27,12 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.36"
+    "assistant-stream": "^0.3.40"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "vitest": "^4.1.10",
-    "@assistant-ui/x-buildutils": "0.0.22"
+    "@assistant-ui/x-buildutils": "0.0.24",
+    "@types/node": "^26.2.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

@@ -178,7 +178,16 @@ export class AssistantCloudAPIKeyAuthStrategy implements AssistantCloudAuthStrat
   }
 }
 
-const AUI_REFRESH_TOKEN_NAME = "aui:refresh_token";
+const LEGACY_AUI_REFRESH_TOKEN_NAME = "aui:refresh_token";
+
+const getRefreshTokenName = (baseUrl: string): string =>
+  `${LEGACY_AUI_REFRESH_TOKEN_NAME}:${baseUrl}`;
+
+const removeLegacyRefreshToken = (storage: Storage): void => {
+  try {
+    storage.removeItem(LEGACY_AUI_REFRESH_TOKEN_NAME);
+  } catch {}
+};
 
 const getLocalStorage = (): Storage | null => {
   if (!("localStorage" in globalThis)) return null;
@@ -189,32 +198,52 @@ const getLocalStorage = (): Storage | null => {
   }
 };
 
-const readRefreshToken = (): RefreshToken | undefined => {
+const readRefreshToken = (baseUrl: string): RefreshToken | undefined => {
   const storage = getLocalStorage();
   if (!storage) return undefined;
   try {
-    const value = storage.getItem(AUI_REFRESH_TOKEN_NAME);
-    return value
-      ? (JSON.parse(value) as { token: string; expires_at: string })
-      : undefined;
+    const name = getRefreshTokenName(baseUrl);
+    const value = storage.getItem(name);
+    if (value) {
+      removeLegacyRefreshToken(storage);
+      return JSON.parse(value) as RefreshToken;
+    }
+
+    const legacyValue = storage.getItem(LEGACY_AUI_REFRESH_TOKEN_NAME);
+    if (!legacyValue) return undefined;
+
+    let refreshToken: RefreshToken;
+    try {
+      refreshToken = JSON.parse(legacyValue) as RefreshToken;
+    } catch {
+      removeLegacyRefreshToken(storage);
+      return undefined;
+    }
+
+    storage.setItem(name, legacyValue);
+    removeLegacyRefreshToken(storage);
+    return refreshToken;
   } catch {
     return undefined;
   }
 };
 
-const writeRefreshToken = (refreshToken: RefreshToken): void => {
+const writeRefreshToken = (
+  baseUrl: string,
+  refreshToken: RefreshToken,
+): void => {
   const storage = getLocalStorage();
   if (!storage) return;
   try {
-    storage.setItem(AUI_REFRESH_TOKEN_NAME, JSON.stringify(refreshToken));
+    storage.setItem(getRefreshTokenName(baseUrl), JSON.stringify(refreshToken));
   } catch {}
 };
 
-const removeRefreshToken = (): void => {
+const removeRefreshToken = (baseUrl: string): void => {
   const storage = getLocalStorage();
   if (!storage) return;
   try {
-    storage.removeItem(AUI_REFRESH_TOKEN_NAME);
+    storage.removeItem(getRefreshTokenName(baseUrl));
   } catch {}
 };
 
@@ -228,7 +257,7 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
     this.baseUrl = baseUrl;
     this.jwtStrategy = new AssistantCloudJWTAuthStrategy(async () => {
       const currentTime = Date.now();
-      const storedRefreshToken = readRefreshToken();
+      const storedRefreshToken = readRefreshToken(this.baseUrl);
 
       if (storedRefreshToken) {
         const refreshExpiry = new Date(storedRefreshToken.expires_at).getTime();
@@ -249,6 +278,7 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
             );
             if (data.refresh_token != null) {
               writeRefreshToken(
+                this.baseUrl,
                 readRefreshTokenResponse(
                   data.refresh_token,
                   "refresh auth token response.refresh_token",
@@ -257,8 +287,14 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
             }
             return accessToken;
           }
+
+          if (response.status === 429 || response.status >= 500) {
+            throw new Error(
+              `Assistant Cloud token refresh failed with status ${response.status}`,
+            );
+          }
         } else {
-          removeRefreshToken();
+          removeRefreshToken(this.baseUrl);
         }
       }
 
@@ -275,6 +311,7 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
       );
 
       writeRefreshToken(
+        this.baseUrl,
         readRefreshTokenResponse(
           data.refresh_token,
           "anonymous auth token response.refresh_token",

package/src/AssistantCloudAuthTokens.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudAuthTokens } from "./AssistantCloudAuthTokens";
+
+const createCloudAuthTokens = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return { tokens: new AssistantCloudAuthTokens(api), makeRequest };
+};
+
+describe("AssistantCloudAuthTokens responses", () => {
+  it("decodes a valid token response", async () => {
+    const { tokens, makeRequest } = createCloudAuthTokens();
+    makeRequest.mockResolvedValue({ token: "token-1" });
+
+    await expect(tokens.create()).resolves.toEqual({ token: "token-1" });
+    expect(makeRequest).toHaveBeenCalledWith("/auth/tokens", {
+      method: "POST",
+    });
+  });
+
+  it("rejects a response that is missing the token", async () => {
+    const { tokens, makeRequest } = createCloudAuthTokens();
+    makeRequest.mockResolvedValue({});
+
+    await expect(tokens.create()).rejects.toThrow(
+      'Invalid Assistant Cloud response for "token": expected a string',
+    );
+  });
+});

package/src/AssistantCloudAuthTokens.ts

@@ -1,4 +1,5 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { readCloudRecord, readCloudString } from "./cloudResponse";
 
 type AssistantCloudAuthTokensCreateResponse = {
   token: string;
@@ -12,6 +13,11 @@ export class AssistantCloudAuthTokens {
   }
 
   public async create(): Promise<AssistantCloudAuthTokensCreateResponse> {
-    return this.cloud.makeRequest("/auth/tokens", { method: "POST" });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/auth/tokens", { method: "POST" }),
+      "auth token response",
+    );
+
+    return { token: readCloudString(response.token, "token") };
   }
 }

package/src/AssistantCloudFiles.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudFiles } from "./AssistantCloudFiles";
+
+const createCloudFiles = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return { files: new AssistantCloudFiles(api), makeRequest };
+};
+
+describe("AssistantCloudFiles responses", () => {
+  it("decodes PDF conversion responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      urls: ["https://example.com/page-1.png"],
+      message: "converted",
+    });
+
+    await expect(
+      files.pdfToImages({ file_url: "https://example.com/file.pdf" }),
+    ).resolves.toEqual({
+      success: true,
+      urls: ["https://example.com/page-1.png"],
+      message: "converted",
+    });
+  });
+
+  it("rejects malformed PDF conversion responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      urls: [42],
+      message: "converted",
+    });
+
+    await expect(files.pdfToImages({ file_blob: "data" })).rejects.toThrow(
+      'Invalid Assistant Cloud response for "PDF conversion response.urls[0]": expected a string',
+    );
+  });
+
+  it("decodes presigned upload responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      signedUrl: "https://uploads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      publicUrl: "https://cdn.example.com/file",
+    });
+
+    await expect(
+      files.generatePresignedUploadUrl({ filename: "notes.txt" }),
+    ).resolves.toEqual({
+      success: true,
+      signedUrl: "https://uploads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      publicUrl: "https://cdn.example.com/file",
+    });
+  });
+
+  it("rejects malformed presigned upload responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({});
+
+    await expect(
+      files.generatePresignedUploadUrl({ filename: "notes.txt" }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "presigned upload response.success": expected a boolean',
+    );
+  });
+});

package/src/AssistantCloudFiles.ts

@@ -1,4 +1,10 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  readCloudArray,
+  readCloudBoolean,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
 
 type PdfToImagesRequestBody = {
   file_blob?: string | undefined;
@@ -32,21 +38,61 @@ export class AssistantCloudFiles {
   public async pdfToImages(
     body: PdfToImagesRequestBody,
   ): Promise<PdfToImagesResponse> {
-    return this.cloud.makeRequest("/files/pdf-to-images", {
-      method: "POST",
-      body,
-    });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/files/pdf-to-images", {
+        method: "POST",
+        body,
+      }),
+      "PDF conversion response",
+    );
+
+    return {
+      success: readCloudBoolean(
+        response.success,
+        "PDF conversion response.success",
+      ),
+      urls: readCloudArray(response.urls, "PDF conversion response.urls").map(
+        (url, index) =>
+          readCloudString(url, `PDF conversion response.urls[${index}]`),
+      ),
+      message: readCloudString(
+        response.message,
+        "PDF conversion response.message",
+      ),
+    };
   }
 
   public async generatePresignedUploadUrl(
     body: GeneratePresignedUploadUrlRequestBody,
   ): Promise<GeneratePresignedUploadUrlResponse> {
-    return this.cloud.makeRequest(
-      "/files/attachments/generate-presigned-upload-url",
-      {
-        method: "POST",
-        body,
-      },
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        "/files/attachments/generate-presigned-upload-url",
+        {
+          method: "POST",
+          body,
+        },
+      ),
+      "presigned upload response",
     );
+
+    return {
+      success: readCloudBoolean(
+        response.success,
+        "presigned upload response.success",
+      ),
+      signedUrl: readCloudString(
+        response.signedUrl,
+        "presigned upload response.signedUrl",
+      ),
+      expiresAt: readCloudString(
+        response.expiresAt,
+        "presigned upload response.expiresAt",
+      ),
+      publicUrl: readCloudString(
+        response.publicUrl,
+        "presigned upload response.publicUrl",
+      ),
+    };
   }
 }

package/src/AssistantCloudRuns.ts

@@ -1,6 +1,11 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
-import type { SamplingCallData } from "./instrumentMcpSampling";
+import type { AssistantCloudRunReportToolCall } from "./runTelemetry";
 import { AssistantStream, PlainTextDecoder } from "assistant-stream";
+import {
+  CloudResponseError,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
 
 type AssistantCloudRunsStreamBody = {
   thread_id: string;
@@ -8,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.
@@ -26,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;
   }[];
@@ -83,12 +77,40 @@ export class AssistantCloudRuns {
       },
       body,
     });
+
+    if (!response.body) {
+      throw new CloudResponseError(
+        'Invalid Assistant Cloud response for "run stream": expected a response body',
+      );
+    }
+
+    const receivedContentType = response.headers.get("content-type");
+    const contentType = receivedContentType
+      ?.split(";", 1)[0]
+      ?.trim()
+      .toLowerCase();
+    if (contentType !== "text/plain") {
+      await response.body.cancel().catch(() => undefined);
+      throw new CloudResponseError(
+        `Invalid Assistant Cloud response for "run stream": expected a "text/plain" content type, received ${
+          receivedContentType
+            ? `"${receivedContentType}"`
+            : "no Content-Type header"
+        }`,
+      );
+    }
+
     return AssistantStream.fromResponse(response, new PlainTextDecoder());
   }
 
   public async report(
     body: AssistantCloudRunReport,
   ): Promise<{ run_id: string }> {
-    return this.cloud.makeRequest("/runs", { method: "POST", body });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/runs", { method: "POST", body }),
+      "run report response",
+    );
+
+    return { run_id: readCloudString(response.run_id, "run_id") };
   }
 }