assistant-cloud 0.1.42 → 0.2.0

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};\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"}
+{"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\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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assistant-cloud",
-  "version": "0.1.42",
+  "version": "0.2.0",
   "description": "Cloud integration for assistant-ui",
   "keywords": [
     "assistant",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.ts",
+      "default": "./dist/telemetry/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -27,11 +31,31 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.40"
+    "assistant-stream": "^0.3.42"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
+    "@opentelemetry/sdk-trace-base": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@assistant-ui/x-buildutils": "0.0.24",
-    "@types/node": "^26.2.0",
+    "@assistant-ui/x-buildutils": "0.0.26",
+    "@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",
+    "jsdom": "^30.0.1",
     "vitest": "^4.1.11"
   },
   "publishConfig": {

package/src/AssistantCloud.ts

@@ -8,6 +8,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 +17,23 @@ export class AssistantCloud {
   public readonly auth;
   public readonly runs;
   public readonly files;
+  public readonly events;
+  public readonly scores;
   public readonly telemetry: AssistantCloudTelemetryConfig;
 
   constructor(config: AssistantCloudConfig) {
     const api = new AssistantCloudAPI(config);
+    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 +41,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,25 @@ import {
   AssistantCloudJWTAuthStrategy,
   AssistantCloudAPIKeyAuthStrategy,
   AssistantCloudAnonymousAuthStrategy,
+  normalizeBaseUrl,
 } from "./AssistantCloudAuthStrategy";
 import type { AssistantCloudRunReport } from "./AssistantCloudRuns";
 
 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`),
@@ -50,10 +64,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,11 +86,7 @@ type MakeRequestOptions = {
   headers?: Record<string, string> | undefined;
   query?: Record<string, string | number | boolean> | undefined;
   body?: object | undefined;
-};
-
-const normalizeBaseUrl = (baseUrl: string) => {
-  if (!baseUrl || !baseUrl.endsWith("/")) return baseUrl;
-  return baseUrl.slice(0, -1);
+  keepalive?: boolean | undefined;
 };
 
 export class AssistantCloudAPI {
@@ -133,6 +152,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 +160,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,
       );
     }
 

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>;
@@ -228,6 +256,19 @@ const readRefreshToken = (baseUrl: string): RefreshToken | undefined => {
   }
 };
 
+export const normalizeBaseUrl = (baseUrl: string): string => {
+  if (!baseUrl || !baseUrl.endsWith("/")) return baseUrl;
+  return baseUrl.slice(0, -1);
+};
+
+/** The refresh token of the anonymous identity this browser holds for `baseUrl`, or null when it has none. */
+export const readAnonymousRefreshToken = (baseUrl: string): string | null => {
+  const refreshToken = readRefreshToken(normalizeBaseUrl(baseUrl));
+  if (!refreshToken) return null;
+  const refreshExpiry = new Date(refreshToken.expires_at).getTime();
+  return refreshExpiry - Date.now() > 30 * 1000 ? refreshToken.token : null;
+};
+
 const writeRefreshToken = (
   baseUrl: string,
   refreshToken: RefreshToken,
@@ -247,6 +288,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 +342,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> {