assistant-cloud 0.1.43 → 0.2.1

package/src/AssistantCloudScores.ts

@@ -0,0 +1,61 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  readCloudEnum,
+  readCloudNullableNumber,
+  readCloudNullableString,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
+
+const SCORE_DATA_TYPES = ["numeric", "categorical", "boolean"] as const;
+
+export type AssistantCloudScoreBody = {
+  name: string;
+  data_type: "numeric" | "categorical" | "boolean";
+  value?: number | boolean;
+  string_value?: string;
+  comment?: string;
+  thread_id?: string;
+  message_id?: string;
+  run_id?: string;
+};
+
+export type AssistantCloudScoreResponse = {
+  score_id: string;
+  name: string;
+  data_type: "numeric" | "categorical" | "boolean";
+  value: number | null;
+  string_value: string | null;
+};
+
+export class AssistantCloudScores {
+  private cloud: AssistantCloudAPI;
+
+  constructor(cloud: AssistantCloudAPI) {
+    this.cloud = cloud;
+  }
+
+  public async create(
+    body: AssistantCloudScoreBody,
+  ): Promise<AssistantCloudScoreResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/scores", { method: "POST", body }),
+      "score response",
+    );
+
+    return {
+      score_id: readCloudString(response.score_id, "score response.score_id"),
+      name: readCloudString(response.name, "score response.name"),
+      data_type: readCloudEnum(
+        response.data_type,
+        "score response.data_type",
+        SCORE_DATA_TYPES,
+      ),
+      value: readCloudNullableNumber(response.value, "score response.value"),
+      string_value: readCloudNullableString(
+        response.string_value,
+        "score response.string_value",
+      ),
+    };
+  }
+}

package/src/AssistantCloudThreadMessages.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import { CloudResponseError } from "./cloudResponse";
 
 const createCloudThreadMessages = () => {
   const makeRequest = vi.fn();
@@ -32,6 +33,41 @@ describe("AssistantCloudThreadMessages responses", () => {
     );
   });
 
+  it("submits and validates message feedback", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    const body = { type: "positive" as const };
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-1",
+      type: "positive",
+    });
+
+    await expect(
+      messages.feedback("thread/1", "message/1", body),
+    ).resolves.toEqual({
+      feedback_id: "feedback-1",
+      type: "positive",
+    });
+    expect(makeRequest).toHaveBeenCalledWith(
+      "/threads/thread%2F1/messages/message%2F1/feedback",
+      { method: "POST", body },
+    );
+
+    makeRequest.mockResolvedValueOnce({ type: "positive" });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", body),
+    ).rejects.toBeInstanceOf(CloudResponseError);
+
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-1",
+      type: "neutral",
+    });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", body),
+    ).rejects.toThrow('expected one of "positive", "negative"');
+  });
+
   it("decodes canonical message responses without changing content", async () => {
     const { messages, makeRequest } = createCloudThreadMessages();
     makeRequest.mockResolvedValue({
@@ -58,4 +94,19 @@ describe("AssistantCloudThreadMessages responses", () => {
       created_at: "leave-this-string-untouched",
     });
   });
+
+  it("forwards the pagination query to the list endpoint", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    makeRequest.mockResolvedValueOnce({ messages: [] });
+
+    await messages.list("thread/1", {
+      format: "aui/v0",
+      limit: 200,
+      after: "message-200",
+    });
+
+    expect(makeRequest).toHaveBeenCalledWith("/threads/thread%2F1/messages", {
+      query: { format: "aui/v0", limit: 200, after: "message-200" },
+    });
+  });
 });

package/src/AssistantCloudThreadMessages.ts

@@ -2,6 +2,7 @@ import type { ReadonlyJSONObject } from "assistant-stream/utils";
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import {
   readCloudArray,
+  readCloudEnum,
   readCloudInteger,
   readCloudJSONObject,
   readCloudNullableString,
@@ -22,6 +23,8 @@ export type CloudMessage = {
 
 type AssistantCloudThreadMessageListQuery = {
   format?: string;
+  limit?: number;
+  after?: string;
 };
 
 type AssistantCloudThreadMessageListResponse = {
@@ -42,6 +45,17 @@ type AssistantCloudThreadMessageUpdateBody = {
   content: ReadonlyJSONObject;
 };
 
+const MESSAGE_FEEDBACK_TYPES = ["positive", "negative"] as const;
+
+export type AssistantCloudThreadMessageFeedbackBody = {
+  type: "positive" | "negative";
+};
+
+export type AssistantCloudThreadMessageFeedbackResponse = {
+  feedback_id: string;
+  type: "positive" | "negative";
+};
+
 export const decodeCloudMessage = (
   value: unknown,
   field: string,
@@ -112,4 +126,23 @@ export class AssistantCloudThreadMessages {
       { method: "PUT", body },
     );
   }
+
+  public async feedback(
+    threadId: string,
+    messageId: string,
+    body: AssistantCloudThreadMessageFeedbackBody,
+  ): Promise<AssistantCloudThreadMessageFeedbackResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        `/threads/${encodeURIComponent(threadId)}/messages/${encodeURIComponent(messageId)}/feedback`,
+        { method: "POST", body },
+      ),
+      "thread message feedback response",
+    );
+
+    return {
+      feedback_id: readCloudString(response.feedback_id, "feedback_id"),
+      type: readCloudEnum(response.type, "type", MESSAGE_FEEDBACK_TYPES),
+    };
+  }
 }

package/src/AssistantCloudThreads.test.ts

@@ -39,6 +39,27 @@ describe("AssistantCloudThreads responses", () => {
     );
   });
 
+  it("claims anonymous threads and validates the moved count", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValueOnce({ moved: 2 });
+
+    await expect(
+      threads.claim({ refresh_token: "anonymous-refresh" }),
+    ).resolves.toEqual({ moved: 2 });
+    expect(makeRequest).toHaveBeenLastCalledWith("/threads/claim", {
+      method: "POST",
+      body: { refresh_token: "anonymous-refresh" },
+    });
+
+    makeRequest.mockResolvedValueOnce({ moved: 1.5 });
+
+    await expect(
+      threads.claim({ refresh_token: "anonymous-refresh" }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "moved": expected an integer',
+    );
+  });
+
   it("forwards both archive filter values", async () => {
     const { threads, makeRequest } = createCloudThreads();
     makeRequest.mockResolvedValue({ threads: [] });

package/src/AssistantCloudThreads.ts

@@ -3,6 +3,7 @@ import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
 import {
   readCloudArray,
   readCloudBoolean,
+  readCloudInteger,
   readCloudNullableString,
   readCloudRecord,
   readCloudString,
@@ -43,6 +44,14 @@ type AssistantCloudThreadsCreateResponse = {
   thread_id: string;
 };
 
+type AssistantCloudThreadsClaimBody = {
+  refresh_token: string;
+};
+
+type AssistantCloudThreadsClaimResponse = {
+  moved: number;
+};
+
 type AssistantCloudThreadsUpdateBody = {
   title?: string | undefined;
   last_message_at?: Date | undefined;
@@ -135,6 +144,18 @@ export class AssistantCloudThreads {
     });
   }
 
+  /** Moves every thread of the anonymous identity behind `refresh_token` into the caller's workspace. */
+  public async claim(
+    body: AssistantCloudThreadsClaimBody,
+  ): Promise<AssistantCloudThreadsClaimResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/threads/claim", { method: "POST", body }),
+      "thread claim response",
+    );
+
+    return { moved: readCloudInteger(response.moved, "moved") };
+  }
+
   public async delete(threadId: string): Promise<void> {
     return this.cloud.makeRequest(`/threads/${encodeURIComponent(threadId)}`, {
       method: "DELETE",

package/src/CloudEngagementReporter.ts

@@ -0,0 +1,231 @@
+import type { AssistantCloud } from "./AssistantCloud";
+import type {
+  AssistantCloudEvent,
+  AssistantCloudEventKind,
+} from "./AssistantCloudEvents";
+
+export type EngagementEventIds = Pick<
+  AssistantCloudEvent,
+  "thread_id" | "message_id" | "run_id"
+>;
+
+/**
+ * Turns the ids an integration knows (its own thread and message ids) into the
+ * ids the cloud stores. A send is the one event that may create the remote
+ * thread, so it asks for `awaitThread`; every other event reads the ids that
+ * already exist.
+ */
+export type EngagementIdResolver = (
+  threadId: string,
+  messageId: string | undefined,
+  options: { awaitThread: boolean },
+) => EngagementEventIds | Promise<EngagementEventIds>;
+
+type EngagementEventInit = Pick<AssistantCloudEvent, "value" | "props">;
+
+const MAX_REMEMBERED_THREADS = 256;
+
+function remember<T>(map: Map<string, T>, threadId: string, value: T): void {
+  map.delete(threadId);
+  map.set(threadId, value);
+  if (map.size > MAX_REMEMBERED_THREADS) {
+    map.delete(map.keys().next().value!);
+  }
+}
+
+function mark(set: Set<string>, threadId: string): void {
+  set.delete(threadId);
+  set.add(threadId);
+  if (set.size > MAX_REMEMBERED_THREADS) {
+    set.delete(set.values().next().value!);
+  }
+}
+
+const passThroughIds: EngagementIdResolver = (threadId, messageId) => ({
+  thread_id: threadId,
+  ...(messageId !== undefined ? { message_id: messageId } : undefined),
+});
+
+/**
+ * Derives engagement events from what a chat integration observes and keeps
+ * the per thread state the events need: a run's start for the stop duration,
+ * a run's end for the time to the next message, one error and one suggestion
+ * list per run or thread. A started run is kept until it ends or stops; the
+ * rest is kept for the 256 most recently touched threads, so a long session
+ * does not grow it without bound. Delivery goes through the cloud's event
+ * buffer, so a disabled telemetry setting drops everything here as well.
+ */
+export class CloudEngagementReporter {
+  private readonly runStartedAt = new Map<string, number>();
+  private readonly runEndedAt = new Map<string, number>();
+  private readonly shownErrors = new Set<string>();
+  private readonly shownSuggestions = new Set<string>();
+
+  private readonly getCloud: () => AssistantCloud;
+  private readonly resolveIds: EngagementIdResolver;
+
+  constructor(
+    cloud: AssistantCloud | (() => AssistantCloud),
+    resolveIds: EngagementIdResolver = passThroughIds,
+  ) {
+    this.getCloud = typeof cloud === "function" ? cloud : () => cloud;
+    this.resolveIds = resolveIds;
+  }
+
+  public runStarted(threadId: string): void {
+    this.runStartedAt.set(threadId, Date.now());
+    this.shownErrors.delete(threadId);
+  }
+
+  public runEnded(threadId: string): void {
+    this.runStartedAt.delete(threadId);
+    remember(this.runEndedAt, threadId, Date.now());
+  }
+
+  /** Reported once per started run, with the time the run had been going. */
+  public runStopped(threadId: string): void {
+    const startedAt = this.runStartedAt.get(threadId);
+    if (startedAt === undefined) return;
+    this.runStartedAt.delete(threadId);
+    this.track("run_stopped", threadId, undefined, {
+      value: Math.max(0, Date.now() - startedAt),
+    });
+  }
+
+  /** Carries the time since the previous run of the thread ended, when known. */
+  public messageSent(
+    threadId: string,
+    init: {
+      messageId?: string | undefined;
+      chars: number;
+      attachments: number;
+    },
+  ): void {
+    const previousRunEndedAt = this.runEndedAt.get(threadId);
+    this.track(
+      "message_sent",
+      threadId,
+      init.messageId,
+      {
+        props: { chars: init.chars, attachments: init.attachments },
+        ...(previousRunEndedAt !== undefined
+          ? { value: Math.max(0, Date.now() - previousRunEndedAt) }
+          : undefined),
+      },
+      { awaitThread: true },
+    );
+  }
+
+  public messageEdited(
+    threadId: string,
+    init: { messageId: string; chars: number },
+  ): void {
+    this.track("message_edited", threadId, init.messageId, {
+      props: { chars: init.chars },
+    });
+  }
+
+  public messageRegenerated(threadId: string, messageId?: string): void {
+    this.track("message_regenerated", threadId, messageId);
+  }
+
+  /** Reported once per run, so a retried render of the same error stays one event. */
+  public errorShown(
+    threadId: string,
+    init: { messageId?: string | undefined; reason: string },
+  ): void {
+    if (this.shownErrors.has(threadId)) return;
+    mark(this.shownErrors, threadId);
+    this.track("error_shown", threadId, init.messageId, {
+      props: { reason: init.reason },
+    });
+  }
+
+  /** Reported once per thread, with the number of suggestions on offer. */
+  public suggestionsShown(threadId: string, count: number): void {
+    if (this.shownSuggestions.has(threadId)) return;
+    mark(this.shownSuggestions, threadId);
+    this.track("suggestions_shown", threadId, undefined, { value: count });
+  }
+
+  public suggestionClicked(threadId: string): void {
+    this.track("suggestion_clicked", threadId);
+  }
+
+  public attachmentAdded(
+    threadId: string,
+    init: { messageId?: string | undefined; contentType?: string | undefined },
+  ): void {
+    this.track("attachment_added", threadId, init.messageId, {
+      ...(init.contentType ? { props: { type: init.contentType } } : undefined),
+    });
+  }
+
+  public attachmentFailed(
+    threadId: string,
+    init: { messageId?: string | undefined; contentType?: string | undefined },
+  ): void {
+    this.track("attachment_failed", threadId, init.messageId, {
+      ...(init.contentType ? { props: { type: init.contentType } } : undefined),
+    });
+  }
+
+  public voiceStarted(threadId: string): void {
+    this.track("voice_started", threadId);
+  }
+
+  public speechStarted(threadId: string, messageId?: string): void {
+    this.track("speech_started", threadId, messageId);
+  }
+
+  public branchSwitched(threadId: string, messageId?: string): void {
+    this.track("branch_switched", threadId, messageId);
+  }
+
+  public messageCopied(threadId: string, messageId?: string): void {
+    this.track("message_copied", threadId, messageId);
+  }
+
+  public toolApproved(
+    threadId: string,
+    messageId: string,
+    toolCallId: string,
+    toolName: string,
+  ): void {
+    this.track("tool_approved", threadId, messageId, {
+      props: { toolCallId, toolName },
+    });
+  }
+
+  public toolRejected(
+    threadId: string,
+    messageId: string,
+    toolCallId: string,
+    toolName: string,
+  ): void {
+    this.track("tool_rejected", threadId, messageId, {
+      props: { toolCallId, toolName },
+    });
+  }
+
+  /** Reported only for a thread the cloud already knows. */
+  public threadSwitched(threadId: string): void {
+    this.track("thread_switched", threadId);
+  }
+
+  private track(
+    kind: AssistantCloudEventKind,
+    threadId: string,
+    messageId?: string,
+    init: EngagementEventInit = {},
+    options: { awaitThread: boolean } = { awaitThread: false },
+  ): void {
+    void Promise.resolve()
+      .then(() => this.resolveIds(threadId, messageId, options))
+      .then((ids) => {
+        if (kind === "thread_switched" && !ids.thread_id) return;
+        this.getCloud().events.track({ kind, ...init, ...ids });
+      })
+      .catch(() => {});
+  }
+}

package/src/CloudMessagePersistence.ts

@@ -1,19 +1,16 @@
 import type { ReadonlyJSONObject } from "assistant-stream/utils";
 import type { AssistantCloud } from "./AssistantCloud";
+import type { CloudMessage } from "./AssistantCloudThreadMessages";
+
+const CLOUD_MESSAGE_PAGE_SIZE = 200;
 
 /**
- * Shared persistence logic for cloud message storage.
- *
- * Handles ID mapping (local → remote) and parent_id chaining for both:
- * - AssistantCloudThreadHistoryAdapter (assistant-ui runtime)
- * - useCloudChat (standalone AI SDK hook)
- *
- * The promise-based ID resolution handles concurrent appends — if message B's
- * parent is message A, and A is still being created, we await A's promise
- * to get its remote ID before creating B.
+ * Appends, updates and loads cloud messages while mapping local ids to cloud
+ * ids and chaining parent_id. A parent that is still being created is awaited,
+ * so concurrent appends land under the right parent.
  */
 export class CloudMessagePersistence {
-  private idMapping: Record<string, string | Promise<string>> = {};
+  private idMapping = new Map<string, string | Promise<string>>();
   private getCloud: () => AssistantCloud;
 
   constructor(cloud: AssistantCloud);
@@ -39,15 +36,16 @@ export class CloudMessagePersistence {
     content: ReadonlyJSONObject,
   ): Promise<void> {
     const cloud = this.getCloud();
-    const existing = this.idMapping[messageId];
+    const existing = this.idMapping.get(messageId);
     if (existing instanceof Promise) {
       await existing;
       return;
     }
 
     const task = (async () => {
+      const parentEntry = parentId ? this.idMapping.get(parentId) : undefined;
       const resolvedParentId = parentId
-        ? ((await this.idMapping[parentId]) ?? parentId)
+        ? ((await parentEntry) ?? parentId)
         : null;
       const { message_id } = await cloud.threads.messages.create(threadId, {
         parent_id: resolvedParentId,
@@ -57,15 +55,15 @@ export class CloudMessagePersistence {
       return message_id;
     })();
 
-    this.idMapping[messageId] = task;
+    this.idMapping.set(messageId, task);
     try {
       const remoteId = await task;
-      if (this.idMapping[messageId] === task) {
-        this.idMapping[messageId] = remoteId;
+      if (this.idMapping.get(messageId) === task) {
+        this.idMapping.set(messageId, remoteId);
       }
     } catch (err) {
-      if (this.idMapping[messageId] === task) {
-        delete this.idMapping[messageId];
+      if (this.idMapping.get(messageId) === task) {
+        this.idMapping.delete(messageId);
       }
       throw err;
     }
@@ -95,7 +93,7 @@ export class CloudMessagePersistence {
    * Check if a message has been persisted (or is currently being persisted).
    */
   isPersisted(messageId: string): boolean {
-    return messageId in this.idMapping;
+    return this.idMapping.has(messageId);
   }
 
   /**
@@ -103,38 +101,83 @@ export class CloudMessagePersistence {
    * Returns undefined if not persisted.
    */
   async getRemoteId(messageId: string): Promise<string | undefined> {
-    const entry = this.idMapping[messageId];
+    const entry = this.idMapping.get(messageId);
     if (!entry) return undefined;
     return entry;
   }
 
+  getResolvedRemoteId(messageId: string): string | undefined {
+    const entry = this.idMapping.get(messageId);
+    return typeof entry === "string" ? entry : undefined;
+  }
+
   /**
    * Load messages from the cloud and populate the ID mapping.
    *
+   * The list endpoint caps a response at 200 rows, so pages are followed by
+   * message ID cursor until a short page and concatenated in server order.
+   *
    * The ID mapping is populated so that `isPersisted()` returns true for
    * loaded messages, preventing re-persistence of already-stored messages.
    *
+   * A loaded ID that an append already maps keeps the remote ID from that append, and falls back to the loaded ID if the append fails.
+   *
    * @param threadId - Remote thread ID
    * @param format - Optional format filter
    * @returns Array of cloud messages
    */
   async load(threadId: string, format?: string) {
+    const idMapping = this.idMapping;
     const cloud = this.getCloud();
-    const { messages } = await cloud.threads.messages.list(
-      threadId,
-      format ? { format } : undefined,
-    );
-    // Populate ID mapping so isPersisted() recognizes loaded messages
-    for (const m of messages) {
-      this.idMapping[m.id] = m.id;
+    const messages: CloudMessage[] = [];
+    const seen = new Set<string>();
+    let after: string | undefined;
+
+    while (true) {
+      const page = await cloud.threads.messages.list(threadId, {
+        ...(format ? { format } : undefined),
+        limit: CLOUD_MESSAGE_PAGE_SIZE,
+        ...(after ? { after } : undefined),
+      });
+      const last = page.messages.at(-1);
+      if (!last) break;
+
+      // A cursor the server cannot resolve drops the keyset filter and replays
+      // an earlier page, so already-seen rows end the walk instead of repeating.
+      const fresh = page.messages.filter((m) => !seen.has(m.id));
+      if (fresh.length === 0) break;
+      for (const m of fresh) seen.add(m.id);
+
+      messages.push(...fresh);
+      if (page.messages.length < CLOUD_MESSAGE_PAGE_SIZE) break;
+      after = last.id;
+    }
+
+    if (this.idMapping === idMapping) {
+      for (const m of messages) {
+        const entry = idMapping.get(m.id);
+        if (entry === undefined) {
+          idMapping.set(m.id, m.id);
+        } else if (entry instanceof Promise) {
+          void entry.catch(() => {
+            const current = idMapping.get(m.id);
+            if (current === undefined || current === entry) {
+              idMapping.set(m.id, m.id);
+            }
+          });
+        }
+      }
     }
     return messages;
   }
 
   /**
    * Reset the ID mapping (call when switching threads).
+   *
+   * Pending `load()` and `append()` calls are not cancelled and still settle
+   * normally, but their results no longer populate the ID mapping.
    */
   reset() {
-    this.idMapping = {};
+    this.idMapping = new Map();
   }
 }

package/src/CloudRunReporter.ts

@@ -0,0 +1,38 @@
+import type { AssistantCloud } from "./AssistantCloud";
+import { createRunReport, type RunReportInit } from "./runTelemetry";
+
+export type CloudRunReportInit = Omit<RunReportInit, "telemetry">;
+
+/**
+ * Sends run reports the way every client integration has to: nothing while
+ * telemetry is off, the cloud's environment, release and tags on every report,
+ * the `beforeReport` hook applied last, and a failed send that never surfaces.
+ * A report given a key is sent once per key, so an integration that observes
+ * the same finished run twice reports it once.
+ */
+export class CloudRunReporter {
+  private readonly reported = new Set<string>();
+  private readonly getCloud: () => AssistantCloud;
+
+  constructor(cloud: AssistantCloud | (() => AssistantCloud)) {
+    this.getCloud = typeof cloud === "function" ? cloud : () => cloud;
+  }
+
+  public async report(init: CloudRunReportInit, key?: string): Promise<void> {
+    try {
+      const cloud = this.getCloud();
+      if (!cloud.telemetry.enabled) return;
+      if (key !== undefined && this.reported.has(key)) return;
+
+      const initial = createRunReport({ ...init, telemetry: cloud.telemetry });
+      const { beforeReport } = cloud.telemetry;
+      const report = beforeReport ? beforeReport(initial) : initial;
+      if (!report) return;
+
+      if (key !== undefined) this.reported.add(key);
+      await cloud.runs.report(report);
+    } catch {
+      return;
+    }
+  }
+}