assistant-cloud 0.1.43 → 0.2.0

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/CloudMessagePersistence.ts

@@ -1,5 +1,8 @@
 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.
@@ -13,7 +16,7 @@ import type { AssistantCloud } from "./AssistantCloud";
  * to get its remote ID before creating B.
  */
 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 +42,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 +61,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 +99,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,14 +107,22 @@ 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.
    *
@@ -120,13 +132,33 @@ export class CloudMessagePersistence {
    */
   async load(threadId: string, format?: string) {
     const cloud = this.getCloud();
-    const { messages } = await cloud.threads.messages.list(
-      threadId,
-      format ? { format } : undefined,
-    );
+    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;
+    }
+
     // Populate ID mapping so isPersisted() recognizes loaded messages
     for (const m of messages) {
-      this.idMapping[m.id] = m.id;
+      this.idMapping.set(m.id, m.id);
     }
     return messages;
   }
@@ -135,6 +167,6 @@ export class CloudMessagePersistence {
    * Reset the ID mapping (call when switching threads).
    */
   reset() {
-    this.idMapping = {};
+    this.idMapping.clear();
   }
 }

package/src/cloudResponse.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { CloudResponseError, readCloudTimestamp } from "./cloudResponse";
+import {
+  CloudResponseError,
+  readCloudNullableNumber,
+  readCloudNumber,
+  readCloudTimestamp,
+} from "./cloudResponse";
 
 describe("readCloudTimestamp", () => {
   it("decodes a canonical Cloud timestamp", () => {
@@ -26,3 +31,31 @@ describe("readCloudTimestamp", () => {
     );
   });
 });
+
+describe("readCloudNumber", () => {
+  it("returns a finite number", () => {
+    expect(readCloudNumber(0.5, "score.value")).toBe(0.5);
+    expect(readCloudNumber(0, "score.value")).toBe(0);
+  });
+
+  it.each([null, undefined, "1", true, Number.NaN, Number.POSITIVE_INFINITY])(
+    "rejects %s",
+    (value) => {
+      const decode = () => readCloudNumber(value, "score.value");
+      expect(decode).toThrow(CloudResponseError);
+      expect(decode).toThrow(
+        'Invalid Assistant Cloud response for "score.value": expected a number',
+      );
+    },
+  );
+});
+
+describe("readCloudNullableNumber", () => {
+  it("passes null through and validates everything else", () => {
+    expect(readCloudNullableNumber(null, "score.value")).toBeNull();
+    expect(readCloudNullableNumber(1, "score.value")).toBe(1);
+    expect(() => readCloudNullableNumber("1", "score.value")).toThrow(
+      CloudResponseError,
+    );
+  });
+});

package/src/cloudResponse.ts

@@ -32,6 +32,36 @@ export const readCloudString = (value: unknown, field: string): string => {
   return value;
 };
 
+export const readCloudNumber = (value: unknown, field: string): number => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw invalidCloudResponse(field, "a number");
+  }
+  return value;
+};
+
+export const readCloudNullableNumber = (
+  value: unknown,
+  field: string,
+): number | null => {
+  if (value === null) return null;
+  return readCloudNumber(value, field);
+};
+
+export const readCloudEnum = <const T extends readonly string[]>(
+  value: unknown,
+  field: string,
+  allowed: T,
+): T[number] => {
+  const text = readCloudString(value, field);
+  if (!allowed.includes(text)) {
+    throw invalidCloudResponse(
+      field,
+      `one of ${allowed.map((entry) => `"${entry}"`).join(", ")}`,
+    );
+  }
+  return text;
+};
+
 export const readCloudNullableString = (
   value: unknown,
   field: string,

package/src/index.ts

@@ -1,19 +1,42 @@
-export type { CloudMessage } from "./AssistantCloudThreadMessages";
+export type {
+  CloudMessage,
+  AssistantCloudThreadMessageFeedbackBody,
+  AssistantCloudThreadMessageFeedbackResponse,
+} from "./AssistantCloudThreadMessages";
 export type { AssistantCloudTelemetryConfig } from "./AssistantCloudAPI";
+export {
+  AssistantCloudEvents,
+  type AssistantCloudEvent,
+  type AssistantCloudEventKind,
+} from "./AssistantCloudEvents";
+export {
+  AssistantCloudScores,
+  type AssistantCloudScoreBody,
+  type AssistantCloudScoreResponse,
+} from "./AssistantCloudScores";
+export type { GeneratePresignedDownloadUrlResponse } from "./AssistantCloudFiles";
 export { CloudAPIError } from "./AssistantCloudAPI";
 export { CloudResponseError } from "./cloudResponse";
 export { generateThreadTitle } from "./generateThreadTitle";
 export type { AssistantCloudRunReport } from "./AssistantCloudRuns";
 export {
+  createRunReport,
   createRunTelemetryToolCall,
+  deriveRunOutcome,
+  describeRunError,
+  extractRunTelemetryModelId,
   normalizeRunTelemetryUsage,
   truncateRunTelemetryText,
   type AssistantCloudRunReportToolCall,
+  type RunReportInit,
+  type RunReportOutcome,
+  type RunReportStepInit,
   type RunTelemetryToolCallInit,
   type RunTelemetryUsage,
   type RunTelemetryUsageInit,
 } from "./runTelemetry";
 export { AssistantCloud } from "./AssistantCloud";
+export { readAnonymousRefreshToken } from "./AssistantCloudAuthStrategy";
 export { CloudMessagePersistence } from "./CloudMessagePersistence";
 export {
   createFormattedPersistence,