assistant-cloud 0.1.43 → 0.2.1

package/dist/runTelemetry.js

@@ -2,6 +2,54 @@
 const MAX_TELEMETRY_TEXT_LENGTH = 5e4;
 const BASE64_PATTERN = /^[A-Za-z0-9+/]{100,}={0,2}$/;
 /**
+* Maps a finish event to the report status and outcome. `fallbackStatus`
+* applies when the event carries neither a finish reason nor a failure flag.
+*/
+function deriveRunOutcome(input, fallbackStatus = "completed") {
+	if (input.isError) return { status: "error" };
+	if (input.isAbort) return {
+		status: "incomplete",
+		outcome: "aborted"
+	};
+	if (input.isDisconnect) return {
+		status: "incomplete",
+		outcome: "disconnected"
+	};
+	switch (input.finishReason) {
+		case "length": return {
+			status: "incomplete",
+			outcome: "length"
+		};
+		case "content-filter":
+		case "content_filter": return {
+			status: "incomplete",
+			outcome: "content_filter"
+		};
+		case "cancelled": return {
+			status: "incomplete",
+			outcome: "aborted"
+		};
+		case "error": return { status: "error" };
+		default: return { status: input.finishReason === void 0 ? fallbackStatus : "completed" };
+	}
+}
+const MAX_RUN_ERROR_CODE_LENGTH = 64;
+const MAX_RUN_ERROR_LENGTH = 2048;
+/**
+* Reads the message and code the runs endpoint stores for a failed run. The
+* code is the error's `code` when it has one, else its class name.
+*/
+function describeRunError(error) {
+	if (error == null) return {};
+	const record = typeof error === "object" ? error : void 0;
+	const message = typeof error === "string" ? error : typeof record?.message === "string" ? record.message : void 0;
+	const code = typeof record?.code === "string" ? record.code : typeof record?.name === "string" && record.name !== "Error" ? record.name : void 0;
+	return {
+		...message ? { error: message.slice(0, MAX_RUN_ERROR_LENGTH) } : void 0,
+		...code ? { errorCode: code.slice(0, MAX_RUN_ERROR_CODE_LENGTH) } : void 0
+	};
+}
+/**
 * Clamps a string to the size the runs endpoint accepts for a single span
 * field.
 */
@@ -58,6 +106,101 @@ function createRunTelemetryToolCall(init) {
 	return call;
 }
 /**
+* Resolves the model ID a run reports, in the order an app can supply it: an
+* explicit `modelId`, the `custom` bag, then the per-step `response.modelId`
+* that a `messageMetadata` callback copies off the AI SDK's finish-step part.
+* The AI SDK puts no model ID on a UI message part, so message metadata is the
+* only channel one arrives on.
+*/
+function extractRunTelemetryModelId(metadata) {
+	if (!metadata) return void 0;
+	if (typeof metadata.modelId === "string") return metadata.modelId;
+	const custom = metadata.custom;
+	if (typeof custom?.modelId === "string") return custom.modelId;
+	const steps = metadata.steps;
+	if (!Array.isArray(steps)) return void 0;
+	for (const step of steps) {
+		if (!step || typeof step !== "object") continue;
+		const response = step.response;
+		if (!response || typeof response !== "object") continue;
+		const modelId = response.modelId;
+		if (typeof modelId === "string") return modelId;
+	}
+}
+function assignUsage(report, usage) {
+	if (!usage) return;
+	const normalized = normalizeRunTelemetryUsage(usage);
+	if (!normalized) return;
+	if (normalized.inputTokens !== void 0) report.input_tokens = normalized.inputTokens;
+	if (normalized.outputTokens !== void 0) report.output_tokens = normalized.outputTokens;
+	if (normalized.reasoningTokens !== void 0) report.reasoning_tokens = normalized.reasoningTokens;
+	if (normalized.cachedInputTokens !== void 0) report.cached_input_tokens = normalized.cachedInputTokens;
+}
+function createRunReportStep(init) {
+	const step = {};
+	const usage = init.usage ? normalizeRunTelemetryUsage(init.usage) : void 0;
+	if (usage?.inputTokens !== void 0) step.input_tokens = usage.inputTokens;
+	if (usage?.outputTokens !== void 0) step.output_tokens = usage.outputTokens;
+	if (usage?.reasoningTokens !== void 0) step.reasoning_tokens = usage.reasoningTokens;
+	if (usage?.cachedInputTokens !== void 0) step.cached_input_tokens = usage.cachedInputTokens;
+	if (init.toolCalls !== void 0) step.tool_calls = init.toolCalls;
+	if (init.startMs !== void 0) step.start_ms = init.startMs;
+	if (init.endMs !== void 0) step.end_ms = init.endMs;
+	if (init.finishReason !== void 0) step.finish_reason = init.finishReason.slice(0, 32);
+	return step;
+}
+function normalizeRunReportTags(tags) {
+	if (!tags) return void 0;
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const tag of tags) {
+		const normalized = tag.trim().slice(0, 64).trim();
+		if (!normalized || seen.has(normalized)) continue;
+		seen.add(normalized);
+		result.push(normalized);
+		if (result.length === 20) break;
+	}
+	return result.length > 0 ? result : void 0;
+}
+function normalizeRunReportMilliseconds(value) {
+	if (value === void 0 || !Number.isFinite(value)) return void 0;
+	return Math.max(0, Math.round(value));
+}
+function createRunReport(init) {
+	const report = {
+		thread_id: init.threadId,
+		status: init.status
+	};
+	const traceId = init.traceId?.toLowerCase();
+	if (traceId && /^[0-9a-f]{32}$/.test(traceId)) report.trace_id = traceId;
+	if (init.outcome !== void 0) report.outcome_type = init.outcome;
+	if (init.errorCode !== void 0) report.error_code = init.errorCode;
+	if (init.error !== void 0) report.error = init.error;
+	if (init.messageId !== void 0) report.message_id = init.messageId;
+	if (init.modelId !== void 0) report.model_id = init.modelId;
+	if (init.provider !== void 0) {
+		report.provider = init.provider;
+		report.provider_type = init.provider;
+	}
+	assignUsage(report, init.usage);
+	if (init.steps !== void 0) {
+		report.steps = init.steps.map(createRunReportStep);
+		report.total_steps = init.steps.length;
+	} else if (init.totalSteps !== void 0) report.total_steps = init.totalSteps;
+	if (init.toolCalls !== void 0) report.tool_calls = init.toolCalls;
+	const durationMs = normalizeRunReportMilliseconds(init.durationMs);
+	if (durationMs !== void 0) report.duration_ms = durationMs;
+	const firstTokenMs = normalizeRunReportMilliseconds(init.firstTokenMs);
+	if (firstTokenMs !== void 0) report.first_token_ms = firstTokenMs;
+	if (init.outputText !== void 0) report.output_text = truncateRunTelemetryText(init.outputText);
+	if (init.metadata !== void 0) report.metadata = init.metadata;
+	if (init.telemetry?.environment !== void 0) report.environment = init.telemetry.environment;
+	if (init.telemetry?.release !== void 0) report.release = init.telemetry.release;
+	const tags = normalizeRunReportTags(init.telemetry?.tags);
+	if (tags !== void 0) report.tags = tags;
+	return report;
+}
+/**
 * 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,
@@ -77,6 +220,6 @@ function normalizeRunTelemetryUsage(usage) {
 	};
 }
 //#endregion
-export { createRunTelemetryToolCall, normalizeRunTelemetryUsage, truncateRunTelemetryText };
+export { createRunReport, createRunTelemetryToolCall, deriveRunOutcome, describeRunError, extractRunTelemetryModelId, normalizeRunTelemetryUsage, truncateRunTelemetryText };
 
 //# sourceMappingURL=runTelemetry.js.map

package/dist/runTelemetry.js.map

@@ -1 +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"}
+{"version":3,"file":"runTelemetry.js","names":[],"sources":["../src/runTelemetry.ts"],"sourcesContent":["import type { SamplingCallData } from \"./instrumentMcpSampling\";\nimport type { AssistantCloudRunReport } from \"./AssistantCloudRuns\";\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\nexport type RunReportOutcome =\n  | \"aborted\"\n  | \"disconnected\"\n  | \"length\"\n  | \"content_filter\";\n\n/**\n * Maps a finish event to the report status and outcome. `fallbackStatus`\n * applies when the event carries neither a finish reason nor a failure flag.\n */\nexport function deriveRunOutcome(\n  input: {\n    finishReason?: string | undefined;\n    isAbort?: boolean | undefined;\n    isDisconnect?: boolean | undefined;\n    isError?: boolean | undefined;\n  },\n  fallbackStatus: \"completed\" | \"incomplete\" = \"completed\",\n): {\n  status: \"completed\" | \"incomplete\" | \"error\";\n  outcome?: RunReportOutcome;\n} {\n  if (input.isError) return { status: \"error\" };\n  if (input.isAbort) return { status: \"incomplete\", outcome: \"aborted\" };\n  if (input.isDisconnect) {\n    return { status: \"incomplete\", outcome: \"disconnected\" };\n  }\n  switch (input.finishReason) {\n    case \"length\":\n      return { status: \"incomplete\", outcome: \"length\" };\n    case \"content-filter\":\n    case \"content_filter\":\n      return { status: \"incomplete\", outcome: \"content_filter\" };\n    case \"cancelled\":\n      return { status: \"incomplete\", outcome: \"aborted\" };\n    case \"error\":\n      return { status: \"error\" };\n    default:\n      return {\n        status: input.finishReason === undefined ? fallbackStatus : \"completed\",\n      };\n  }\n}\n\nconst MAX_RUN_ERROR_CODE_LENGTH = 64;\nconst MAX_RUN_ERROR_LENGTH = 2048;\n\n/**\n * Reads the message and code the runs endpoint stores for a failed run. The\n * code is the error's `code` when it has one, else its class name.\n */\nexport function describeRunError(error: unknown): {\n  error?: string;\n  errorCode?: string;\n} {\n  if (error == null) return {};\n  const record =\n    typeof error === \"object\" ? (error as Record<string, unknown>) : undefined;\n  const message =\n    typeof error === \"string\"\n      ? error\n      : typeof record?.message === \"string\"\n        ? record.message\n        : undefined;\n  const code =\n    typeof record?.code === \"string\"\n      ? record.code\n      : typeof record?.name === \"string\" && record.name !== \"Error\"\n        ? record.name\n        : undefined;\n  return {\n    ...(message\n      ? { error: message.slice(0, MAX_RUN_ERROR_LENGTH) }\n      : undefined),\n    ...(code\n      ? { errorCode: code.slice(0, MAX_RUN_ERROR_CODE_LENGTH) }\n      : undefined),\n  };\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\n/**\n * Resolves the model ID a run reports, in the order an app can supply it: an\n * explicit `modelId`, the `custom` bag, then the per-step `response.modelId`\n * that a `messageMetadata` callback copies off the AI SDK's finish-step part.\n * The AI SDK puts no model ID on a UI message part, so message metadata is the\n * only channel one arrives on.\n */\nexport function extractRunTelemetryModelId(\n  metadata: Record<string, unknown> | undefined,\n): string | undefined {\n  if (!metadata) return undefined;\n  if (typeof metadata.modelId === \"string\") return metadata.modelId;\n  const custom = metadata.custom as Record<string, unknown> | undefined;\n  if (typeof custom?.modelId === \"string\") return custom.modelId;\n\n  const steps: unknown = metadata.steps;\n  if (!Array.isArray(steps)) return undefined;\n  for (const step of steps as unknown[]) {\n    if (!step || typeof step !== \"object\") continue;\n    const response = (step as Record<string, unknown>).response;\n    if (!response || typeof response !== \"object\") continue;\n    const modelId = (response as Record<string, unknown>).modelId;\n    if (typeof modelId === \"string\") return modelId;\n  }\n  return undefined;\n}\n\nexport type RunTelemetryUsage = {\n  inputTokens?: number | undefined;\n  outputTokens?: number | undefined;\n  reasoningTokens?: number | undefined;\n  cachedInputTokens?: number | undefined;\n};\n\nexport type RunTelemetryUsageInit = RunTelemetryUsage & {\n  promptTokens?: number | undefined;\n  completionTokens?: number | undefined;\n  inputTokenDetails?: { cacheReadTokens?: number };\n  outputTokenDetails?: { reasoningTokens?: number };\n};\n\nexport type RunReportStepInit = {\n  usage?: RunTelemetryUsageInit | undefined;\n  toolCalls?: AssistantCloudRunReportToolCall[] | undefined;\n  startMs?: number | undefined;\n  endMs?: number | undefined;\n  finishReason?: string | undefined;\n};\n\n/**\n * The run report fields read from the messages of one run, in whichever\n * format they were stored: the status the messages imply, the tool calls, the\n * steps, the text, the usage and the model.\n */\nexport type RunMessageTelemetry = {\n  assistantMessageId?: string;\n  status: \"completed\" | \"incomplete\";\n  toolCalls?: AssistantCloudRunReportToolCall[];\n  steps?: RunReportStepInit[];\n  totalSteps?: number;\n  outputText?: string;\n  usage?: RunTelemetryUsage;\n  modelId?: string;\n  metadata?: Record<string, unknown>;\n};\n\nexport type RunReportInit = {\n  threadId: string;\n  status: AssistantCloudRunReport[\"status\"];\n  outcome?: RunReportOutcome | undefined;\n  errorCode?: string | undefined;\n  error?: string | undefined;\n  messageId?: string | undefined;\n  traceId?: string | undefined;\n  modelId?: string | undefined;\n  provider?: string | undefined;\n  usage?: RunTelemetryUsageInit | undefined;\n  steps?: RunReportStepInit[] | undefined;\n  totalSteps?: number | undefined;\n  toolCalls?: AssistantCloudRunReportToolCall[] | undefined;\n  durationMs?: number | undefined;\n  firstTokenMs?: number | undefined;\n  outputText?: string | undefined;\n  metadata?: Record<string, unknown> | undefined;\n  telemetry?: {\n    environment?: string | undefined;\n    release?: string | undefined;\n    tags?: readonly string[] | undefined;\n  };\n};\n\nfunction assignUsage(\n  report: AssistantCloudRunReport,\n  usage: RunTelemetryUsageInit | undefined,\n): void {\n  if (!usage) return;\n  const normalized = normalizeRunTelemetryUsage(usage);\n  if (!normalized) return;\n  if (normalized.inputTokens !== undefined) {\n    report.input_tokens = normalized.inputTokens;\n  }\n  if (normalized.outputTokens !== undefined) {\n    report.output_tokens = normalized.outputTokens;\n  }\n  if (normalized.reasoningTokens !== undefined) {\n    report.reasoning_tokens = normalized.reasoningTokens;\n  }\n  if (normalized.cachedInputTokens !== undefined) {\n    report.cached_input_tokens = normalized.cachedInputTokens;\n  }\n}\n\nfunction createRunReportStep(\n  init: RunReportStepInit,\n): NonNullable<AssistantCloudRunReport[\"steps\"]>[number] {\n  const step: NonNullable<AssistantCloudRunReport[\"steps\"]>[number] = {};\n  const usage = init.usage ? normalizeRunTelemetryUsage(init.usage) : undefined;\n  if (usage?.inputTokens !== undefined) step.input_tokens = usage.inputTokens;\n  if (usage?.outputTokens !== undefined)\n    step.output_tokens = usage.outputTokens;\n  if (usage?.reasoningTokens !== undefined) {\n    step.reasoning_tokens = usage.reasoningTokens;\n  }\n  if (usage?.cachedInputTokens !== undefined) {\n    step.cached_input_tokens = usage.cachedInputTokens;\n  }\n  if (init.toolCalls !== undefined) step.tool_calls = init.toolCalls;\n  if (init.startMs !== undefined) step.start_ms = init.startMs;\n  if (init.endMs !== undefined) step.end_ms = init.endMs;\n  if (init.finishReason !== undefined) {\n    step.finish_reason = init.finishReason.slice(0, 32);\n  }\n  return step;\n}\n\nfunction normalizeRunReportTags(\n  tags: readonly string[] | undefined,\n): string[] | undefined {\n  if (!tags) return undefined;\n  const result: string[] = [];\n  const seen = new Set<string>();\n  for (const tag of tags) {\n    const normalized = tag.trim().slice(0, 64).trim();\n    if (!normalized || seen.has(normalized)) continue;\n    seen.add(normalized);\n    result.push(normalized);\n    if (result.length === 20) break;\n  }\n  return result.length > 0 ? result : undefined;\n}\n\nfunction normalizeRunReportMilliseconds(\n  value: number | undefined,\n): number | undefined {\n  if (value === undefined || !Number.isFinite(value)) return undefined;\n  return Math.max(0, Math.round(value));\n}\n\nexport function createRunReport(init: RunReportInit): AssistantCloudRunReport {\n  const report: AssistantCloudRunReport = {\n    thread_id: init.threadId,\n    status: init.status,\n  };\n  const traceId = init.traceId?.toLowerCase();\n  if (traceId && /^[0-9a-f]{32}$/.test(traceId)) report.trace_id = traceId;\n  if (init.outcome !== undefined) report.outcome_type = init.outcome;\n  if (init.errorCode !== undefined) report.error_code = init.errorCode;\n  if (init.error !== undefined) report.error = init.error;\n  if (init.messageId !== undefined) report.message_id = init.messageId;\n  if (init.modelId !== undefined) report.model_id = init.modelId;\n  if (init.provider !== undefined) {\n    report.provider = init.provider;\n    report.provider_type = init.provider;\n  }\n  assignUsage(report, init.usage);\n  if (init.steps !== undefined) {\n    report.steps = init.steps.map(createRunReportStep);\n    report.total_steps = init.steps.length;\n  } else if (init.totalSteps !== undefined) {\n    report.total_steps = init.totalSteps;\n  }\n  if (init.toolCalls !== undefined) report.tool_calls = init.toolCalls;\n  const durationMs = normalizeRunReportMilliseconds(init.durationMs);\n  if (durationMs !== undefined) report.duration_ms = durationMs;\n  const firstTokenMs = normalizeRunReportMilliseconds(init.firstTokenMs);\n  if (firstTokenMs !== undefined) report.first_token_ms = firstTokenMs;\n  if (init.outputText !== undefined) {\n    report.output_text = truncateRunTelemetryText(init.outputText);\n  }\n  if (init.metadata !== undefined) report.metadata = init.metadata;\n  if (init.telemetry?.environment !== undefined) {\n    report.environment = init.telemetry.environment;\n  }\n  if (init.telemetry?.release !== undefined) {\n    report.release = init.telemetry.release;\n  }\n  const tags = normalizeRunReportTags(init.telemetry?.tags);\n  if (tags !== undefined) report.tags = tags;\n  return report;\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":"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"}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,32 @@
+import { ReadableSpan, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/telemetry/index.d.ts
+type AssistantCloudTraceExportOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+};
+type AssistantCloudSpanProcessorOptions = {
+  filter?: (span: ReadableSpan) => boolean;
+};
+declare function assistantCloudTraceExportOptions({ apiKey, baseUrl, headers }: AssistantCloudTraceExportOptions): {
+  url: string;
+  headers: Record<string, string>;
+};
+declare function createAssistantCloudTraceExporter(options: AssistantCloudTraceExportOptions): SpanExporter;
+declare function isAssistantCloudSpan(span: ReadableSpan): boolean;
+declare function createAssistantCloudSpanProcessor(exporter: SpanExporter, options?: AssistantCloudSpanProcessorOptions): SpanProcessor;
+declare function assistantCloudTraceMetadata(): {
+  traceId?: string;
+};
+declare function withAssistantCloudTraceMetadata<Part extends {
+  type: string;
+} = {
+  type: string;
+}>(messageMetadata?: (options: {
+  part: Part;
+}) => Record<string, unknown> | undefined): (options: {
+  part: Part;
+}) => Record<string, unknown> | undefined;
+//#endregion
+export { AssistantCloudSpanProcessorOptions, AssistantCloudTraceExportOptions, assistantCloudTraceExportOptions, assistantCloudTraceMetadata, createAssistantCloudSpanProcessor, createAssistantCloudTraceExporter, isAssistantCloudSpan, withAssistantCloudTraceMetadata };
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/telemetry/index.ts"],"mappings":";;KAYY;EACV;EACA;EACA,UAAU;;KAGA;EACV,UAAU,MAAM;;iBAGF,mCACd,QACA,SACA,WACC;EACD;EACA,SAAS;;iBAmBK,kCACd,SAAS,mCACR;iBAIa,qBAAqB,MAAM;iBAO3B,kCACd,UAAU,cACV,UAAS,qCACR;iBAca;EAAiC;;iBAOjC,gCACd;EAAe;;EAAmB;GAElC,mBAAmB;EACjB,MAAM;MACF,uCACJ;EAAW,MAAM;MAAW"}

package/dist/telemetry/index.js

@@ -0,0 +1,62 @@
+import { trace } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/telemetry/index.ts
+const DEFAULT_BACKEND_BASE_URL = "https://backend.assistant-api.com";
+const AI_SPAN_PREFIXES = [
+	"gen_ai.",
+	"ai.",
+	"llm."
+];
+function assistantCloudTraceExportOptions({ apiKey, baseUrl = DEFAULT_BACKEND_BASE_URL, headers }) {
+	if (!apiKey) throw new Error("An Assistant Cloud API key is required");
+	return {
+		url: `${trimTrailingSlashes(baseUrl)}/v1/traces`,
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			...headers
+		}
+	};
+}
+function trimTrailingSlashes(url) {
+	let end = url.length;
+	while (end > 0 && url[end - 1] === "/") end--;
+	return url.slice(0, end);
+}
+function createAssistantCloudTraceExporter(options) {
+	return new OTLPTraceExporter(assistantCloudTraceExportOptions(options));
+}
+function isAssistantCloudSpan(span) {
+	return typeof span.attributes["gen_ai.operation.name"] === "string" || AI_SPAN_PREFIXES.some((prefix) => span.name.startsWith(prefix));
+}
+function createAssistantCloudSpanProcessor(exporter, options = {}) {
+	const processor = new BatchSpanProcessor(exporter);
+	const filter = options.filter ?? isAssistantCloudSpan;
+	return {
+		onStart: (span, parentContext) => processor.onStart(span, parentContext),
+		onEnd: (span) => {
+			if (filter(span)) processor.onEnd(span);
+		},
+		forceFlush: () => processor.forceFlush(),
+		shutdown: () => processor.shutdown()
+	};
+}
+function assistantCloudTraceMetadata() {
+	const spanContext = trace.getActiveSpan()?.spanContext();
+	return spanContext && trace.isSpanContextValid(spanContext) ? { traceId: spanContext.traceId } : {};
+}
+function withAssistantCloudTraceMetadata(messageMetadata) {
+	return (options) => {
+		const metadata = messageMetadata?.(options);
+		if (options.part.type !== "start") return metadata;
+		const trace = assistantCloudTraceMetadata();
+		return trace.traceId === void 0 ? metadata : {
+			...metadata,
+			...trace
+		};
+	};
+}
+//#endregion
+export { assistantCloudTraceExportOptions, assistantCloudTraceMetadata, createAssistantCloudSpanProcessor, createAssistantCloudTraceExporter, isAssistantCloudSpan, withAssistantCloudTraceMetadata };
+
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/telemetry/index.ts"],"sourcesContent":["import { trace } from \"@opentelemetry/api\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-http\";\nimport {\n  BatchSpanProcessor,\n  type ReadableSpan,\n  type SpanExporter,\n  type SpanProcessor,\n} from \"@opentelemetry/sdk-trace-base\";\n\nconst DEFAULT_BACKEND_BASE_URL = \"https://backend.assistant-api.com\";\nconst AI_SPAN_PREFIXES = [\"gen_ai.\", \"ai.\", \"llm.\"];\n\nexport type AssistantCloudTraceExportOptions = {\n  apiKey: string;\n  baseUrl?: string;\n  headers?: Record<string, string>;\n};\n\nexport type AssistantCloudSpanProcessorOptions = {\n  filter?: (span: ReadableSpan) => boolean;\n};\n\nexport function assistantCloudTraceExportOptions({\n  apiKey,\n  baseUrl = DEFAULT_BACKEND_BASE_URL,\n  headers,\n}: AssistantCloudTraceExportOptions): {\n  url: string;\n  headers: Record<string, string>;\n} {\n  if (!apiKey) throw new Error(\"An Assistant Cloud API key is required\");\n\n  return {\n    url: `${trimTrailingSlashes(baseUrl)}/v1/traces`,\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n      ...headers,\n    },\n  };\n}\n\nfunction trimTrailingSlashes(url: string): string {\n  let end = url.length;\n  while (end > 0 && url[end - 1] === \"/\") end--;\n  return url.slice(0, end);\n}\n\nexport function createAssistantCloudTraceExporter(\n  options: AssistantCloudTraceExportOptions,\n): SpanExporter {\n  return new OTLPTraceExporter(assistantCloudTraceExportOptions(options));\n}\n\nexport function isAssistantCloudSpan(span: ReadableSpan): boolean {\n  return (\n    typeof span.attributes[\"gen_ai.operation.name\"] === \"string\" ||\n    AI_SPAN_PREFIXES.some((prefix) => span.name.startsWith(prefix))\n  );\n}\n\nexport function createAssistantCloudSpanProcessor(\n  exporter: SpanExporter,\n  options: AssistantCloudSpanProcessorOptions = {},\n): SpanProcessor {\n  const processor = new BatchSpanProcessor(exporter);\n  const filter = options.filter ?? isAssistantCloudSpan;\n\n  return {\n    onStart: (span, parentContext) => processor.onStart(span, parentContext),\n    onEnd: (span) => {\n      if (filter(span)) processor.onEnd(span);\n    },\n    forceFlush: () => processor.forceFlush(),\n    shutdown: () => processor.shutdown(),\n  };\n}\n\nexport function assistantCloudTraceMetadata(): { traceId?: string } {\n  const spanContext = trace.getActiveSpan()?.spanContext();\n  return spanContext && trace.isSpanContextValid(spanContext)\n    ? { traceId: spanContext.traceId }\n    : {};\n}\n\nexport function withAssistantCloudTraceMetadata<\n  Part extends { type: string } = { type: string },\n>(\n  messageMetadata?: (options: {\n    part: Part;\n  }) => Record<string, unknown> | undefined,\n): (options: { part: Part }) => Record<string, unknown> | undefined {\n  return (options) => {\n    const metadata = messageMetadata?.(options);\n    if (options.part.type !== \"start\") return metadata;\n    const trace = assistantCloudTraceMetadata();\n    return trace.traceId === undefined ? metadata : { ...metadata, ...trace };\n  };\n}\n"],"mappings":";;;;AASA,MAAM,2BAA2B;AACjC,MAAM,mBAAmB;CAAC;CAAW;CAAO;AAAM;AAYlD,SAAgB,iCAAiC,EAC/C,QACA,UAAU,0BACV,WAIA;CACA,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,wCAAwC;CAErE,OAAO;EACL,KAAK,GAAG,oBAAoB,OAAO,EAAE;EACrC,SAAS;GACP,eAAe,UAAU;GACzB,GAAG;EACL;CACF;AACF;AAEA,SAAS,oBAAoB,KAAqB;CAChD,IAAI,MAAM,IAAI;CACd,OAAO,MAAM,KAAK,IAAI,MAAM,OAAO,KAAK;CACxC,OAAO,IAAI,MAAM,GAAG,GAAG;AACzB;AAEA,SAAgB,kCACd,SACc;CACd,OAAO,IAAI,kBAAkB,iCAAiC,OAAO,CAAC;AACxE;AAEA,SAAgB,qBAAqB,MAA6B;CAChE,OACE,OAAO,KAAK,WAAW,6BAA6B,YACpD,iBAAiB,MAAM,WAAW,KAAK,KAAK,WAAW,MAAM,CAAC;AAElE;AAEA,SAAgB,kCACd,UACA,UAA8C,CAAC,GAChC;CACf,MAAM,YAAY,IAAI,mBAAmB,QAAQ;CACjD,MAAM,SAAS,QAAQ,UAAU;CAEjC,OAAO;EACL,UAAU,MAAM,kBAAkB,UAAU,QAAQ,MAAM,aAAa;EACvE,QAAQ,SAAS;GACf,IAAI,OAAO,IAAI,GAAG,UAAU,MAAM,IAAI;EACxC;EACA,kBAAkB,UAAU,WAAW;EACvC,gBAAgB,UAAU,SAAS;CACrC;AACF;AAEA,SAAgB,8BAAoD;CAClE,MAAM,cAAc,MAAM,cAAc,CAAC,EAAE,YAAY;CACvD,OAAO,eAAe,MAAM,mBAAmB,WAAW,IACtD,EAAE,SAAS,YAAY,QAAQ,IAC/B,CAAC;AACP;AAEA,SAAgB,gCAGd,iBAGkE;CAClE,QAAQ,YAAY;EAClB,MAAM,WAAW,kBAAkB,OAAO;EAC1C,IAAI,QAAQ,KAAK,SAAS,SAAS,OAAO;EAC1C,MAAM,QAAQ,4BAA4B;EAC1C,OAAO,MAAM,YAAY,KAAA,IAAY,WAAW;GAAE,GAAG;GAAU,GAAG;EAAM;CAC1E;AACF"}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+//#region src/version.d.ts
+declare const ASSISTANT_CLOUD_VERSION: string;
+//#endregion
+export { ASSISTANT_CLOUD_VERSION };
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","names":[],"sources":["../src/version.ts"],"mappings":";cAAa"}

package/dist/version.js

@@ -0,0 +1,6 @@
+//#region src/version.ts
+const ASSISTANT_CLOUD_VERSION = "0.2.1";
+//#endregion
+export { ASSISTANT_CLOUD_VERSION };
+
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["export const ASSISTANT_CLOUD_VERSION: string =\n  typeof __AUI_PACKAGE_VERSION__ === \"string\"\n    ? __AUI_PACKAGE_VERSION__\n    : \"0.0.0\";\n"],"mappings":";AAAA,MAAa,0BAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-cloud",
-  "version": "0.1.43",
+  "version": "0.2.1",
   "description": "Cloud integration for assistant-ui",
   "keywords": [
     "assistant",
@@ -16,6 +16,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "default": "./dist/telemetry/index.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk/index.d.ts",
+      "default": "./dist/ai-sdk/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -27,12 +35,38 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.41"
+    "assistant-stream": "^0.3.43"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
+    "@opentelemetry/sdk-trace-base": "^2.1.0",
+    "ai": "^6.0.0 || ^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@assistant-ui/x-buildutils": "0.0.25",
-    "@types/node": "^26.4.0",
-    "vitest": "^4.1.11"
+    "@assistant-ui/x-buildutils": "0.0.27",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.205.0",
+    "@opentelemetry/sdk-trace-base": "^2.1.0",
+    "@types/node": "^26.4.1",
+    "ai": "^7.0.93",
+    "ai-v6": "npm:ai@^6.0.277",
+    "jsdom": "^30.0.1",
+    "vitest": "^5.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -49,7 +83,10 @@
   },
   "scripts": {
     "build": "aui-build",
-    "test": "vitest run",
+    "test": "pnpm run test:v7 && pnpm run test:peer-v6 && pnpm run test:types:peer-v6",
+    "test:v7": "vitest run",
+    "test:peer-v6": "vitest run --config vitest.peer-v6.config.ts",
+    "test:types:peer-v6": "tsc --noEmit --project tsconfig.peer-v6.json",
     "test:watch": "vitest"
   }
 }

package/src/AssistantCloud.ts

@@ -1,6 +1,7 @@
 import {
   AssistantCloudAPI,
   type AssistantCloudConfig,
+  type SdkIdentity,
   type AssistantCloudTelemetryConfig,
 } from "./AssistantCloudAPI";
 import { AssistantCloudAuthTokens } from "./AssistantCloudAuthTokens";
@@ -8,6 +9,8 @@ import { AssistantCloudProjects } from "./AssistantCloudProjects";
 import { AssistantCloudRuns } from "./AssistantCloudRuns";
 import { AssistantCloudThreads } from "./AssistantCloudThreads";
 import { AssistantCloudFiles } from "./AssistantCloudFiles";
+import { AssistantCloudEvents } from "./AssistantCloudEvents";
+import { AssistantCloudScores } from "./AssistantCloudScores";
 
 export class AssistantCloud {
   public readonly threads;
@@ -15,10 +18,25 @@ export class AssistantCloud {
   public readonly auth;
   public readonly runs;
   public readonly files;
+  public readonly events;
+  public readonly scores;
   public readonly telemetry: AssistantCloudTelemetryConfig;
+  public readonly registerSdk: (sdk: SdkIdentity) => void;
 
   constructor(config: AssistantCloudConfig) {
     const api = new AssistantCloudAPI(config);
+    this.registerSdk = api.registerSdk;
+    const t = config.telemetry;
+    this.telemetry =
+      t === false
+        ? { enabled: false }
+        : t === true || t === undefined
+          ? { enabled: true }
+          : {
+              ...t,
+              enabled: t.enabled !== false,
+            };
+
     this.threads = new AssistantCloudThreads(api);
     this.projects = new AssistantCloudProjects(api);
     this.auth = {
@@ -26,13 +44,10 @@ export class AssistantCloud {
     };
     this.runs = new AssistantCloudRuns(api);
     this.files = new AssistantCloudFiles(api);
-
-    const t = config.telemetry;
-    this.telemetry =
-      t === false
-        ? { enabled: false }
-        : t === true || t === undefined
-          ? { enabled: true }
-          : { ...t, enabled: t.enabled !== false };
+    this.events = new AssistantCloudEvents(
+      api,
+      () => this.telemetry.enabled !== false && this.telemetry.events !== false,
+    );
+    this.scores = new AssistantCloudScores(api);
   }
 }

package/src/AssistantCloudAPI.ts

@@ -3,11 +3,31 @@ import {
   AssistantCloudJWTAuthStrategy,
   AssistantCloudAPIKeyAuthStrategy,
   AssistantCloudAnonymousAuthStrategy,
+  normalizeBaseUrl,
 } from "./AssistantCloudAuthStrategy";
 import type { AssistantCloudRunReport } from "./AssistantCloudRuns";
+import { ASSISTANT_CLOUD_VERSION } from "./version";
+
+export type SdkIdentity = {
+  name: string;
+  version: string;
+};
 
 export type AssistantCloudTelemetryConfig = {
+  /**
+   * Enables Assistant Cloud telemetry. Defaults to `true`. Set to `false` to
+   * disable both run reports and engagement events.
+   */
   enabled?: boolean;
+  /**
+   * Enables Assistant Cloud engagement events. Defaults to `true` when
+   * telemetry is enabled. Set to `false` to keep run reports while disabling
+   * engagement events.
+   */
+  events?: boolean;
+  release?: string;
+  environment?: string;
+  tags?: string[];
   /**
    * Called before each telemetry report is sent.
    * Return a modified report to enrich it (e.g. add `model_id`),
@@ -39,7 +59,10 @@ export type AssistantCloudConfig = (
    *
    * When enabled, the SDK automatically reports run metadata (status, step
    * count, tool calls, and token usage) to Assistant Cloud after each
-   * assistant message is saved. No message content is sent.
+   * assistant message is saved. Reports can also include assistant output,
+   * tool arguments and results, errors, and metadata, which may contain
+   * sensitive content. Use `beforeReport` to redact or drop reports, or
+   * `telemetry: false` to disable reporting.
    *
    * - `true` / `undefined` — enabled with defaults
    * - `false` — disabled
@@ -50,10 +73,19 @@ export type AssistantCloudConfig = (
 
 export class CloudAPIError extends Error {
   public readonly status: number;
-
-  constructor(message: string, status: number) {
+  public readonly code?: string;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    status: number,
+    code?: string,
+    details?: Record<string, unknown>,
+  ) {
     super(message);
     this.status = status;
+    if (code !== undefined) this.code = code;
+    if (details !== undefined) this.details = details;
     this.name = "CloudAPIError";
   }
 }
@@ -63,18 +95,34 @@ type MakeRequestOptions = {
   headers?: Record<string, string> | undefined;
   query?: Record<string, string | number | boolean> | undefined;
   body?: object | undefined;
+  keepalive?: boolean | undefined;
 };
 
-const normalizeBaseUrl = (baseUrl: string) => {
-  if (!baseUrl || !baseUrl.endsWith("/")) return baseUrl;
-  return baseUrl.slice(0, -1);
-};
+const HEADER_TOKEN = /^[\x21-\x7e]+$/;
 
 export class AssistantCloudAPI {
   public _auth: AssistantCloudAuthStrategy;
   public _baseUrl;
+  public readonly registerSdk: (sdk: SdkIdentity) => void;
+  public readonly sdkHeader: () => string;
 
   constructor(config: AssistantCloudConfig) {
+    const sdks = new Map<string, SdkIdentity>();
+    this.registerSdk = (sdk) => {
+      const name = sdk.name.trim();
+      const version = sdk.version.trim();
+      if (!HEADER_TOKEN.test(name) || !HEADER_TOKEN.test(version)) return;
+      sdks.set(`${name}/${version}`, { name, version });
+    };
+    this.sdkHeader = () =>
+      [
+        `assistant-cloud/${ASSISTANT_CLOUD_VERSION}`,
+        ...Array.from(
+          sdks.values(),
+          ({ name, version }) => `${name}/${version}`,
+        ),
+      ].join(" ");
+
     if ("authToken" in config) {
       this._baseUrl = normalizeBaseUrl(config.baseUrl);
       this._auth = new AssistantCloudJWTAuthStrategy(config.authToken);
@@ -112,6 +160,7 @@ export class AssistantCloudAPI {
       ...authHeaders,
       ...options.headers,
       "Content-Type": "application/json",
+      "Aui-Sdk": this.sdkHeader(),
     };
 
     const queryParams = new URLSearchParams();
@@ -133,6 +182,7 @@ export class AssistantCloudAPI {
       method: options.method ?? "GET",
       headers,
       body: options.body ? JSON.stringify(options.body) : null,
+      ...(options.keepalive ? { keepalive: true } : {}),
     });
 
     this._auth.readAuthHeaders(response.headers);
@@ -140,15 +190,27 @@ export class AssistantCloudAPI {
     if (!response.ok) {
       const text = await response.text();
       let message: string | undefined;
+      let code: string | undefined;
+      let details: Record<string, unknown> | undefined;
       try {
-        const body = JSON.parse(text);
-        if (typeof body?.message === "string" && body.message.length > 0) {
-          message = body.message;
+        const body = JSON.parse(text) as unknown;
+        if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+          const record = body as Record<string, unknown>;
+          if (typeof record.message === "string" && record.message.length > 0) {
+            message = record.message;
+          }
+          if (typeof record.error === "string") {
+            code = record.error;
+            details = { ...record };
+            delete details.error;
+          }
         }
       } catch {}
       throw new CloudAPIError(
         message ?? `Request failed with status ${response.status}, ${text}`,
         response.status,
+        code,
+        details,
       );
     }