@assistant-ui/core 0.3.16 → 0.3.18

package/src/react/runtimes/cloud/AssistantCloudThreadHistoryAdapter.ts

@@ -9,17 +9,26 @@ import type {
 import type { ExportedMessageRepositoryItem } from "../../../runtime/utils/message-repository";
 import {
   type AssistantCloud,
+  type AssistantCloudEvent,
   type AssistantCloudRunReportToolCall,
   CloudMessagePersistence,
   createFormattedPersistence,
+  createRunReport,
   createRunTelemetryToolCall,
+  deriveRunOutcome,
+  describeRunError,
+  extractRunTelemetryModelId,
   normalizeRunTelemetryUsage,
+  type RunReportOutcome,
+  type RunReportStepInit,
+  type RunTelemetryUsage,
   type RunTelemetryUsageInit,
   truncateRunTelemetryText,
 } from "assistant-cloud";
 import { auiV0Decode, auiV0Encode } from "./auiV0";
 import { type AssistantClient, getClientId, useAui } from "@assistant-ui/store";
 import type { ThreadListItemMethods } from "../../../store/scopes/thread-list-item";
+import type { FeedbackAdapter } from "../../../adapters/feedback";
 
 type CloudThreadListItem = Pick<
   ThreadListItemMethods,
@@ -64,12 +73,98 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     return this.getPersistence();
   }
 
+  /**
+   * A send is the moment the runtime creates the remote thread, so that one
+   * event waits for the id; every other event reads the id that already
+   * exists, because initializing a thread nobody has written to would create
+   * an empty remote thread just to attribute an event.
+   */
+  public async resolveEngagementEventIds(
+    threadId: string,
+    messageId?: string,
+    options?: { awaitThread?: boolean },
+  ): Promise<Pick<AssistantCloudEvent, "thread_id" | "message_id">> {
+    const threadListItem = this.getThreadListItem(threadId);
+    if (!threadListItem) return {};
+
+    let remoteThreadId = threadListItem.getState().remoteId;
+    if (!remoteThreadId && options?.awaitThread) {
+      remoteThreadId = await threadListItem
+        .initialize()
+        .then((result) => result.remoteId)
+        .catch(() => undefined);
+    }
+    const remoteMessageId = messageId
+      ? this.getPersistence(threadListItem).getResolvedRemoteId(messageId)
+      : undefined;
+    return {
+      ...(remoteThreadId ? { thread_id: remoteThreadId } : undefined),
+      ...(remoteMessageId ? { message_id: remoteMessageId } : undefined),
+    };
+  }
+
+  public readonly feedback: FeedbackAdapter = {
+    submit: ({ message, type }) => {
+      void (async () => {
+        const threadListItem = this.tryGetKeyedThreadListItem();
+        const remoteThreadId = threadListItem?.getState().remoteId;
+        if (!threadListItem || !remoteThreadId) {
+          console.warn(
+            `[assistant-ui] Skipping feedback for message ${message.id}: the thread has no remote id.`,
+          );
+          return;
+        }
+
+        const cloudMessageId = await this.getPersistence(
+          threadListItem,
+        ).getRemoteId(message.id);
+        if (!cloudMessageId) {
+          console.warn(
+            `[assistant-ui] Skipping feedback for message ${message.id}: no cloud message id is mapped.`,
+          );
+          return;
+        }
+
+        await this.cloudRef.current.threads.messages.feedback(
+          remoteThreadId,
+          cloudMessageId,
+          { type },
+        );
+      })().catch((error: unknown) => {
+        console.error(
+          "[assistant-ui] Cloud feedback submission failed:",
+          error,
+        );
+      });
+    },
+  };
+
   private tryGetKeyedThreadListItem(): CloudThreadListItem | undefined {
     const live = this.aui.threadListItem;
     if (!live.source) return undefined;
     const id = live.getState().id;
     if (id === undefined) return undefined;
-    return this.aui.threads.item({ id });
+    // A body can resolve before the list's committed items include its
+    // thread; the live item is already the per-thread anchor in that window.
+    const listed = this.aui.threads
+      .getState()
+      .threadItems.some((item) => item.id === id || item.remoteId === id);
+    return listed ? this.aui.threads.item({ id }) : live;
+  }
+
+  private getThreadListItem(threadId: string): CloudThreadListItem | undefined {
+    const current = this.aui.threadListItem;
+    const currentState = current.getState();
+    if (currentState.id === threadId || currentState.remoteId === threadId) {
+      return current;
+    }
+
+    const listed = this.aui.threads
+      .getState()
+      .threadItems.find(
+        (item) => item.id === threadId || item.remoteId === threadId,
+      );
+    return listed ? this.aui.threads.item({ id: listed.id }) : undefined;
   }
 
   withFormat<TMessage, TStorageFormat extends Record<string, unknown>>(
@@ -83,8 +178,6 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
       return threadListItem;
     };
     const resolvePinned = () => threadListItem ?? pinCurrent();
-    const getFormatted = () =>
-      createFormattedPersistence(adapter._persistence, formatAdapter);
     const getTargetFormatted = (item: CloudThreadListItem) =>
       createFormattedPersistence(adapter.getPersistence(item), formatAdapter);
     return {
@@ -132,14 +225,18 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
           encodedRunMessages,
           options,
           resolvePinned(),
+          extractLastRunMessageInfo(items, formatAdapter),
         );
       },
       async load(): Promise<MessageFormatRepository<TMessage>> {
-        pinCurrent();
+        // Loads re-pin and resolve through the pinned item, so the id mapping
+        // they populate lives on the same persistence instance later writes
+        // resolve, whichever of the list item or the live graft won the pin.
+        const pinned = pinCurrent();
         const live = adapter.aui.threadListItem;
         const remoteId = live.source ? live.getState().remoteId : undefined;
         if (!remoteId) return { messages: [] };
-        return getFormatted().load(remoteId);
+        return getTargetFormatted(pinned ?? live).load(remoteId);
       },
     };
   }
@@ -156,7 +253,12 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     );
 
     if (this.cloudRef.current.telemetry.enabled) {
-      this._maybeReportRun(remoteId, "aui/v0", encoded);
+      this._maybeReportRun(
+        remoteId,
+        "aui/v0",
+        encoded,
+        extractRunMessageInfo(message, "aui/v0"),
+      );
     }
   }
 
@@ -171,7 +273,12 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     await this._persistence.update(remoteId, message.id, "aui/v0", encoded);
 
     if (this.cloudRef.current.telemetry.enabled) {
-      this._maybeReportRun(remoteId, "aui/v0", encoded);
+      this._maybeReportRun(
+        remoteId,
+        "aui/v0",
+        encoded,
+        extractRunMessageInfo(message, "aui/v0"),
+      );
     }
   }
 
@@ -203,11 +310,12 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
       stepTimestamps?: StepTimestamp[];
     },
     threadListItem?: CloudThreadListItem,
+    messageInfo?: RunMessageInfo,
   ) {
     if (!this.cloudRef.current.telemetry.enabled) return;
 
-    const remoteId = (threadListItem ?? this.aui.threadListItem).getState()
-      .remoteId;
+    const item = threadListItem ?? this.aui.threadListItem;
+    const remoteId = item.getState().remoteId;
     if (!remoteId) return;
 
     const extracted = extractRunTelemetry(format, runMessages);
@@ -218,14 +326,21 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
       extracted,
       options?.durationMs,
       options?.stepTimestamps,
+      messageInfo,
+      this.getPersistence(item),
     );
   }
 
-  private _maybeReportRun<T>(remoteId: string, format: string, content: T) {
+  private _maybeReportRun<T>(
+    remoteId: string,
+    format: string,
+    content: T,
+    messageInfo?: RunMessageInfo,
+  ) {
     const extracted = extractTelemetry(format, content);
     if (!extracted) return;
 
-    this._sendReport(remoteId, extracted);
+    this._sendReport(remoteId, extracted, undefined, undefined, messageInfo);
   }
 
   private _sendReport(
@@ -233,37 +348,38 @@ class AssistantCloudThreadHistoryAdapter implements ThreadHistoryAdapter {
     data: TelemetryData,
     durationMs?: number,
     stepTimestamps?: StepTimestamp[],
+    messageInfo?: RunMessageInfo,
+    persistence = this._persistence,
   ) {
     const mergedSteps = mergeStepTimestamps(data.steps, stepTimestamps);
-    // Keep in sync with assistant-cloud createRunSchema
-    // (apps/aui-cloud-api/src/endpoints/runs/create.ts).
-    const initial: Parameters<typeof this.cloudRef.current.runs.report>[0] = {
-      thread_id: remoteId,
-      status: data.status,
-      ...(data.totalSteps != null
-        ? { total_steps: data.totalSteps }
-        : undefined),
-      ...(data.toolCalls ? { tool_calls: data.toolCalls } : undefined),
-      ...(mergedSteps ? { steps: mergedSteps } : undefined),
-      ...(data.inputTokens != null
-        ? { input_tokens: data.inputTokens }
-        : undefined),
-      ...(data.outputTokens != null
-        ? { output_tokens: data.outputTokens }
-        : undefined),
-      ...(data.reasoningTokens != null
-        ? { reasoning_tokens: data.reasoningTokens }
-        : undefined),
-      ...(data.cachedInputTokens != null
-        ? { cached_input_tokens: data.cachedInputTokens }
-        : undefined),
-      ...(durationMs != null ? { duration_ms: durationMs } : undefined),
-      ...(data.outputText != null
-        ? { output_text: data.outputText }
-        : undefined),
-      ...(data.metadata ? { metadata: data.metadata } : undefined),
-      ...(data.modelId ? { model_id: data.modelId } : undefined),
-    };
+    const messageId = messageInfo?.localMessageId
+      ? persistence.getResolvedRemoteId(messageInfo.localMessageId)
+      : undefined;
+    const initial = createRunReport({
+      threadId: remoteId,
+      status: messageInfo?.status ?? data.status,
+      outcome: messageInfo?.outcomeType,
+      error: messageInfo?.error,
+      errorCode: messageInfo?.errorCode,
+      messageId,
+      traceId: messageInfo?.traceId,
+      modelId: data.modelId,
+      provider: messageInfo?.provider,
+      usage: {
+        inputTokens: data.inputTokens,
+        outputTokens: data.outputTokens,
+        reasoningTokens: data.reasoningTokens,
+        cachedInputTokens: data.cachedInputTokens,
+      },
+      steps: toRunReportSteps(mergedSteps),
+      totalSteps: data.totalSteps,
+      toolCalls: data.toolCalls,
+      durationMs,
+      firstTokenMs: messageInfo?.firstTokenMs,
+      outputText: data.outputText,
+      metadata: data.metadata,
+      telemetry: this.cloudRef.current.telemetry,
+    });
 
     const { beforeReport } = this.cloudRef.current.telemetry;
     const report = beforeReport ? beforeReport(initial) : initial;
@@ -285,6 +401,23 @@ type TelemetryStepData = {
 
 type StepTimestamp = { start_ms: number; end_ms: number };
 
+function toRunReportSteps(
+  steps: TelemetryStepData[] | undefined,
+): RunReportStepInit[] | undefined {
+  if (!steps) return undefined;
+  return steps.map((step) => ({
+    usage: {
+      inputTokens: step.input_tokens,
+      outputTokens: step.output_tokens,
+      reasoningTokens: step.reasoning_tokens,
+      cachedInputTokens: step.cached_input_tokens,
+    },
+    toolCalls: step.tool_calls,
+    startMs: step.start_ms,
+    endMs: step.end_ms,
+  }));
+}
+
 function mergeStepTimestamps(
   steps: TelemetryStepData[] | undefined,
   timestamps: StepTimestamp[] | undefined,
@@ -313,6 +446,101 @@ type TelemetryData = {
   modelId?: string;
 };
 
+type RunMessageInfo = {
+  localMessageId?: string;
+  status?: "error";
+  outcomeType?: RunReportOutcome;
+  error?: string;
+  errorCode?: string;
+  firstTokenMs?: number;
+  traceId?: string;
+  provider?: string;
+};
+
+function extractLastRunMessageInfo<
+  TMessage,
+  TStorageFormat extends Record<string, unknown>,
+>(
+  items: MessageFormatItem<TMessage>[],
+  formatAdapter: MessageFormatAdapter<TMessage, TStorageFormat>,
+): RunMessageInfo | undefined {
+  for (let i = items.length - 1; i >= 0; i--) {
+    const item = items[i]!;
+    const info = extractRunMessageInfo(
+      item.message,
+      formatAdapter.format,
+      formatAdapter.getId(item.message),
+    );
+    if (info) return info;
+  }
+  return undefined;
+}
+
+function extractRunMessageInfo(
+  message: unknown,
+  format: string,
+  localMessageId?: string,
+): RunMessageInfo | undefined {
+  if (!isRecord(message) || message.role !== "assistant") return undefined;
+
+  const status = isRecord(message.status) ? message.status : undefined;
+  const metadata = isRecord(message.metadata) ? message.metadata : undefined;
+  const custom = isRecord(metadata?.custom) ? metadata.custom : undefined;
+  const timing = isRecord(metadata?.timing) ? metadata.timing : undefined;
+  const streamStartTime = timing?.streamStartTime;
+  const firstTokenTime = timing?.firstTokenTime;
+  const firstTokenMs =
+    typeof streamStartTime === "number" &&
+    Number.isFinite(streamStartTime) &&
+    typeof firstTokenTime === "number" &&
+    Number.isFinite(firstTokenTime)
+      ? Math.round(firstTokenTime - streamStartTime)
+      : undefined;
+  const finishReason =
+    status?.type === "incomplete"
+      ? status.reason
+      : typeof metadata?.finishReason === "string"
+        ? metadata.finishReason
+        : undefined;
+  const failed = status?.type === "incomplete" && status.reason === "error";
+  const outcome = deriveRunOutcome({
+    finishReason: typeof finishReason === "string" ? finishReason : undefined,
+    isError: failed,
+  });
+  const outcomeType = outcome.outcome;
+  const failure = failed ? describeRunError(status.error) : {};
+  const messageId =
+    localMessageId ?? (typeof message.id === "string" ? message.id : undefined);
+  const traceId =
+    format === "aui/v0"
+      ? custom?.traceId
+      : format === "ai-sdk/v6"
+        ? metadata?.traceId
+        : undefined;
+  const provider =
+    typeof custom?.provider === "string"
+      ? custom.provider
+      : typeof metadata?.provider === "string"
+        ? metadata.provider
+        : undefined;
+
+  return {
+    ...(messageId ? { localMessageId: messageId } : undefined),
+    ...(outcome.status === "error" ? { status: "error" as const } : undefined),
+    ...(outcomeType ? { outcomeType } : undefined),
+    ...failure,
+    ...(firstTokenMs != null && firstTokenMs >= 0
+      ? { firstTokenMs }
+      : undefined),
+    ...(typeof traceId === "string" ? { traceId } : undefined),
+    ...(provider !== undefined ? { provider } : undefined),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
 function extractTelemetry<T>(format: string, content: T): TelemetryData | null {
   switch (format) {
     case "aui/v0":
@@ -346,7 +574,7 @@ const AUI_STATUS_MAP: Record<string, TelemetryData["status"]> = {
 export function extractAuiV0<T>(content: T): TelemetryData | null {
   const msg = content as {
     role?: string;
-    status?: { type: string };
+    status?: { type: string; reason?: string };
     content?: readonly {
       type: string;
       text?: string;
@@ -358,14 +586,7 @@ export function extractAuiV0<T>(content: T): TelemetryData | null {
     }[];
     metadata?: {
       modelId?: string;
-      steps?: readonly {
-        usage?: {
-          inputTokens?: number;
-          outputTokens?: number;
-          reasoningTokens?: number;
-          cachedInputTokens?: number;
-        };
-      }[];
+      steps?: readonly { usage?: RunTelemetryUsageInit }[];
       custom?: Record<string, unknown> & { modelId?: string };
     };
   };
@@ -408,20 +629,23 @@ export function extractAuiV0<T>(content: T): TelemetryData | null {
     let hasReasoning = false;
     let hasCachedInput = false;
     for (const step of steps) {
-      if (step.usage?.inputTokens != null) {
-        totalInput += step.usage.inputTokens;
+      if (!step.usage) continue;
+      const usage = normalizeRunTelemetryUsage(step.usage);
+      if (!usage) continue;
+      if (usage.inputTokens != null) {
+        totalInput += usage.inputTokens;
         hasInput = true;
       }
-      if (step.usage?.outputTokens != null) {
-        totalOutput += step.usage.outputTokens;
+      if (usage.outputTokens != null) {
+        totalOutput += usage.outputTokens;
         hasOutput = true;
       }
-      if (step.usage?.reasoningTokens != null) {
-        totalReasoning += step.usage.reasoningTokens;
+      if (usage.reasoningTokens != null) {
+        totalReasoning += usage.reasoningTokens;
         hasReasoning = true;
       }
-      if (step.usage?.cachedInputTokens != null) {
-        totalCachedInput += step.usage.cachedInputTokens;
+      if (usage.cachedInputTokens != null) {
+        totalCachedInput += usage.cachedInputTokens;
         hasCachedInput = true;
       }
     }
@@ -433,31 +657,36 @@ export function extractAuiV0<T>(content: T): TelemetryData | null {
 
   const statusType = msg.status?.type;
   const status: TelemetryData["status"] =
-    (statusType && AUI_STATUS_MAP[statusType]) || "completed";
+    statusType === "incomplete" && msg.status?.reason === "error"
+      ? "error"
+      : (statusType && AUI_STATUS_MAP[statusType]) || "completed";
 
   const metadata = msg.metadata?.custom as Record<string, unknown> | undefined;
-  const modelId =
-    msg.metadata?.modelId ??
-    (typeof msg.metadata?.custom?.modelId === "string"
-      ? msg.metadata.custom.modelId
-      : undefined);
+  const modelId = extractRunTelemetryModelId(
+    msg.metadata as Record<string, unknown> | undefined,
+  );
 
   const telemetrySteps: TelemetryStepData[] | undefined =
     steps && steps.length > 1
-      ? steps.map((s) => ({
-          ...(s.usage?.inputTokens != null
-            ? { input_tokens: s.usage.inputTokens }
-            : undefined),
-          ...(s.usage?.outputTokens != null
-            ? { output_tokens: s.usage.outputTokens }
-            : undefined),
-          ...(s.usage?.reasoningTokens != null
-            ? { reasoning_tokens: s.usage.reasoningTokens }
-            : undefined),
-          ...(s.usage?.cachedInputTokens != null
-            ? { cached_input_tokens: s.usage.cachedInputTokens }
-            : undefined),
-        }))
+      ? steps.map((s) => {
+          const usage = s.usage
+            ? normalizeRunTelemetryUsage(s.usage)
+            : undefined;
+          return {
+            ...(usage?.inputTokens != null
+              ? { input_tokens: usage.inputTokens }
+              : undefined),
+            ...(usage?.outputTokens != null
+              ? { output_tokens: usage.outputTokens }
+              : undefined),
+            ...(usage?.reasoningTokens != null
+              ? { reasoning_tokens: usage.reasoningTokens }
+              : undefined),
+            ...(usage?.cachedInputTokens != null
+              ? { cached_input_tokens: usage.cachedInputTokens }
+              : undefined),
+          };
+        })
       : undefined;
 
   return {
@@ -549,34 +778,19 @@ function collectAiSdkV6Parts(parts: readonly AiSdkV6Part[]): {
   return { textParts, toolCalls, stepsData };
 }
 
-function extractModelId(
-  metadata?: Record<string, unknown>,
-): string | undefined {
-  if (!metadata) return undefined;
-  if (typeof metadata.modelId === "string") return metadata.modelId;
-  const custom = metadata.custom as Record<string, unknown> | undefined;
-  if (typeof custom?.modelId === "string") return custom.modelId;
-  return undefined;
-}
-
 function buildAiSdkV6Result(
   textParts: string[],
   toolCalls: AssistantCloudRunReportToolCall[],
   totalSteps: number,
   metadata?: Record<string, unknown>,
   stepsData?: { tool_calls: AssistantCloudRunReportToolCall[] }[],
-  usage?: {
-    inputTokens?: number;
-    outputTokens?: number;
-    reasoningTokens?: number;
-    cachedInputTokens?: number;
-  },
+  usage?: RunTelemetryUsage,
 ): TelemetryData {
   const hasText = textParts.length > 0;
   const outputText = hasText
     ? truncateRunTelemetryText(textParts.join(""))
     : undefined;
-  const modelId = extractModelId(metadata);
+  const modelId = extractRunTelemetryModelId(metadata);
 
   const steps: TelemetryStepData[] | undefined =
     stepsData && stepsData.length > 1
@@ -610,14 +824,9 @@ function buildAiSdkV6Result(
   };
 }
 
-function extractAiSdkV6Usage(metadata?: Record<string, unknown>):
-  | {
-      inputTokens?: number;
-      outputTokens?: number;
-      reasoningTokens?: number;
-      cachedInputTokens?: number;
-    }
-  | undefined {
+function extractAiSdkV6Usage(
+  metadata?: Record<string, unknown>,
+): RunTelemetryUsage | undefined {
   // Try top-level metadata.usage
   const usage = metadata?.usage as RunTelemetryUsageInit | undefined;
   if (usage) {
@@ -759,7 +968,7 @@ function aggregateAiSdkV6RunSteps<T>(stepMessages: T[]): TelemetryData | null {
 
 export function useAssistantCloudThreadHistoryAdapter(
   cloudRef: RefObject<AssistantCloud>,
-): ThreadHistoryAdapter {
+): ThreadHistoryAdapter & { readonly feedback: FeedbackAdapter } {
   const aui = useAui();
   // Not useEffectEvent: history adapter methods run during render (SSR load).
   const auiRef = useRef(aui);
@@ -770,5 +979,239 @@ export function useAssistantCloudThreadHistoryAdapter(
     () =>
       new AssistantCloudThreadHistoryAdapter(cloudRef, () => auiRef.current),
   );
+  useAssistantCloudEngagementEvents(cloudRef, adapter, aui);
   return adapter;
 }
+
+type RootEngagementTracker = {
+  count: number;
+  adapter: AssistantCloudThreadHistoryAdapter;
+  cloudRef: RefObject<AssistantCloud>;
+  dispose: () => void;
+};
+
+const rootEngagementTrackers = new WeakMap<
+  AssistantClient,
+  RootEngagementTracker
+>();
+
+/**
+ * Thread switches are a thread list event, so one subscription per assistant
+ * client reports them; every thread runtime mounted under it shares the
+ * subscription and the last one to unmount removes it.
+ */
+const useRootEngagementEvents = (
+  cloudRef: RefObject<AssistantCloud>,
+  adapter: AssistantCloudThreadHistoryAdapter,
+  aui: AssistantClient,
+) => {
+  useEffect(() => {
+    let tracker = rootEngagementTrackers.get(aui);
+    if (!tracker) {
+      const created: RootEngagementTracker = {
+        count: 0,
+        adapter,
+        cloudRef,
+        dispose: () => {},
+      };
+      created.dispose = aui.on(
+        { scope: "*", event: "threads.selectionChanged" },
+        (payload) => {
+          void created.adapter
+            .resolveEngagementEventIds(payload.threadId)
+            .then((ids) => {
+              if (!ids.thread_id) return;
+              created.cloudRef.current.events?.track({
+                kind: "thread_switched",
+                ...ids,
+              });
+            })
+            .catch(() => {});
+        },
+      );
+      rootEngagementTrackers.set(aui, created);
+      tracker = created;
+    }
+    const active = tracker;
+    active.adapter = adapter;
+    active.cloudRef = cloudRef;
+    active.count += 1;
+    return () => {
+      active.count -= 1;
+      if (active.count === 0) {
+        active.dispose();
+        rootEngagementTrackers.delete(aui);
+      }
+    };
+  }, [adapter, aui, cloudRef]);
+};
+
+const useAssistantCloudEngagementEvents = (
+  cloudRef: RefObject<AssistantCloud>,
+  adapter: AssistantCloudThreadHistoryAdapter,
+  aui: AssistantClient,
+) => {
+  useRootEngagementEvents(cloudRef, adapter, aui);
+  const runStartedAt = useRef(new Map<string, number>());
+  const runEndedAt = useRef(new Map<string, number>());
+  const shownSuggestions = useRef(new Set<string>());
+
+  useEffect(() => {
+    const track = (
+      event: AssistantCloudEvent,
+      threadId: string,
+      messageId?: string,
+      options?: { awaitThread?: boolean },
+    ) => {
+      void adapter
+        .resolveEngagementEventIds(threadId, messageId, options)
+        .then((ids) => {
+          cloudRef.current.events?.track({ ...event, ...ids });
+        })
+        .catch(() => {});
+    };
+    const trackRunStopped = (threadId: string) => {
+      const startedAt = runStartedAt.current.get(threadId);
+      if (startedAt === undefined) return;
+      runStartedAt.current.delete(threadId);
+      track(
+        { kind: "run_stopped", value: Math.max(0, Date.now() - startedAt) },
+        threadId,
+      );
+    };
+
+    const unsubscribers = [
+      aui.on({ scope: "thread", event: "composer.send" }, (payload) => {
+        const previousRunEndedAt = runEndedAt.current.get(payload.threadId);
+        track(
+          {
+            kind: payload.messageId ? "message_edited" : "message_sent",
+            ...(payload.messageId
+              ? { props: { chars: payload.chars } }
+              : {
+                  props: {
+                    chars: payload.chars,
+                    attachments: payload.attachments,
+                  },
+                }),
+            ...(!payload.messageId && previousRunEndedAt !== undefined
+              ? { value: Math.max(0, Date.now() - previousRunEndedAt) }
+              : undefined),
+          },
+          payload.threadId,
+          payload.messageId,
+          { awaitThread: !payload.messageId },
+        );
+        if (payload.suggestion) {
+          track({ kind: "suggestion_clicked" }, payload.threadId);
+        }
+      }),
+      aui.on(
+        { scope: "thread", event: "composer.attachmentAdd" },
+        (payload) => {
+          track(
+            {
+              kind: "attachment_added",
+              ...(payload.contentType
+                ? { props: { type: payload.contentType } }
+                : undefined),
+            },
+            payload.threadId,
+            payload.messageId,
+          );
+        },
+      ),
+      aui.on(
+        { scope: "thread", event: "composer.attachmentAddError" },
+        (payload) => {
+          track(
+            {
+              kind: "attachment_failed",
+              ...(payload.contentType
+                ? { props: { type: payload.contentType } }
+                : undefined),
+            },
+            payload.threadId,
+            payload.messageId,
+          );
+        },
+      ),
+      aui.on({ scope: "thread", event: "composer.cancel" }, (payload) => {
+        trackRunStopped(payload.threadId);
+      }),
+      aui.on({ scope: "thread", event: "thread.runStart" }, (payload) => {
+        runStartedAt.current.set(payload.threadId, Date.now());
+      }),
+      aui.on({ scope: "thread", event: "thread.runEnd" }, (payload) => {
+        runStartedAt.current.delete(payload.threadId);
+        runEndedAt.current.set(payload.threadId, Date.now());
+      }),
+      aui.on({ scope: "thread", event: "thread.cancelRun" }, (payload) => {
+        trackRunStopped(payload.threadId);
+      }),
+      aui.on({ scope: "thread", event: "thread.voiceStarted" }, (payload) => {
+        track({ kind: "voice_started" }, payload.threadId);
+      }),
+      aui.on({ scope: "thread", event: "message.reload" }, (payload) => {
+        track(
+          { kind: "message_regenerated" },
+          payload.threadId,
+          payload.messageId,
+        );
+      }),
+      aui.on(
+        { scope: "thread", event: "message.branchSwitched" },
+        (payload) => {
+          track(
+            { kind: "branch_switched" },
+            payload.threadId,
+            payload.messageId,
+          );
+        },
+      ),
+      aui.on({ scope: "thread", event: "message.copied" }, (payload) => {
+        track({ kind: "message_copied" }, payload.threadId, payload.messageId);
+      }),
+      aui.on({ scope: "thread", event: "message.speak" }, (payload) => {
+        track({ kind: "speech_started" }, payload.threadId, payload.messageId);
+      }),
+      aui.on({ scope: "thread", event: "message.error" }, (payload) => {
+        track(
+          { kind: "error_shown", props: { reason: payload.reason } },
+          payload.threadId,
+          payload.messageId,
+        );
+      }),
+    ];
+
+    return () => {
+      for (const unsubscribe of unsubscribers) unsubscribe();
+    };
+  }, [adapter, aui, cloudRef]);
+
+  useEffect(() => {
+    const reportSuggestions = () => {
+      const { mainThreadId } = aui.threads.getState();
+      if (aui.threadListItem.getState().id !== mainThreadId) return;
+      const { isEmpty, suggestions } = aui.thread.getState();
+      if (
+        !isEmpty ||
+        suggestions.length === 0 ||
+        shownSuggestions.current.has(mainThreadId)
+      ) {
+        return;
+      }
+      shownSuggestions.current.add(mainThreadId);
+      void adapter.resolveEngagementEventIds(mainThreadId).then((ids) => {
+        cloudRef.current.events?.track({
+          kind: "suggestions_shown",
+          value: suggestions.length,
+          ...ids,
+        });
+      });
+    };
+
+    reportSuggestions();
+    return aui.subscribe(reportSuggestions);
+  }, [adapter, aui, cloudRef]);
+};