assistant-cloud 0.1.34 → 0.1.36

package/src/AssistantCloudAuthStrategy.ts

@@ -39,6 +39,7 @@ export class AssistantCloudJWTAuthStrategy implements AssistantCloudAuthStrategy
 
   private cachedToken: string | null = null;
   private tokenExpiry: number | null = null;
+  private tokenRequest: Promise<Record<string, string> | false> | null = null;
   #authTokenCallback: () => Promise<string | null>;
 
   constructor(authTokenCallback: () => Promise<string | null>) {
@@ -57,14 +58,28 @@ export class AssistantCloudJWTAuthStrategy implements AssistantCloudAuthStrategy
       return { Authorization: `Bearer ${this.cachedToken}` };
     }
 
-    // Fetch a new token via the callback
-    const newToken = await this.#authTokenCallback();
-    if (!newToken) return false;
+    if (!this.tokenRequest) {
+      this.tokenRequest = this.fetchAuthHeaders();
+    }
+
+    const tokenRequest = this.tokenRequest;
+    try {
+      return await tokenRequest;
+    } finally {
+      if (this.tokenRequest === tokenRequest) {
+        this.tokenRequest = null;
+      }
+    }
+  }
 
-    this.cachedToken = newToken;
-    this.tokenExpiry = getJwtExpiry(newToken);
+  private async fetchAuthHeaders(): Promise<Record<string, string> | false> {
+    const token = await this.#authTokenCallback();
+    if (!token) return false;
 
-    return { Authorization: `Bearer ${newToken}` };
+    this.cachedToken = token;
+    this.tokenExpiry = getJwtExpiry(token);
+
+    return { Authorization: `Bearer ${token}` };
   }
 
   public readAuthHeaders(headers: Headers) {
@@ -109,6 +124,49 @@ export class AssistantCloudAPIKeyAuthStrategy implements AssistantCloudAuthStrat
 
 const AUI_REFRESH_TOKEN_NAME = "aui:refresh_token";
 
+const getLocalStorage = (): Storage | null => {
+  if (!("localStorage" in globalThis)) return null;
+  try {
+    return (globalThis as { localStorage: Storage }).localStorage;
+  } catch {
+    return null;
+  }
+};
+
+const readRefreshToken = ():
+  | { token: string; expires_at: string }
+  | undefined => {
+  const storage = getLocalStorage();
+  if (!storage) return undefined;
+  try {
+    const value = storage.getItem(AUI_REFRESH_TOKEN_NAME);
+    return value
+      ? (JSON.parse(value) as { token: string; expires_at: string })
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const writeRefreshToken = (refreshToken: {
+  token: string;
+  expires_at: string;
+}): void => {
+  const storage = getLocalStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(AUI_REFRESH_TOKEN_NAME, JSON.stringify(refreshToken));
+  } catch {}
+};
+
+const removeRefreshToken = (): void => {
+  const storage = getLocalStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(AUI_REFRESH_TOKEN_NAME);
+  } catch {}
+};
+
 export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthStrategy {
   public readonly strategy = "anon";
 
@@ -119,15 +177,7 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
     this.baseUrl = baseUrl;
     this.jwtStrategy = new AssistantCloudJWTAuthStrategy(async () => {
       const currentTime = Date.now();
-      const storedRefreshTokenJson = localStorage.getItem(
-        AUI_REFRESH_TOKEN_NAME,
-      );
-      const storedRefreshToken = storedRefreshTokenJson
-        ? (JSON.parse(storedRefreshTokenJson) as {
-            token: string;
-            expires_at: string;
-          })
-        : undefined;
+      const storedRefreshToken = readRefreshToken();
 
       if (storedRefreshToken) {
         const refreshExpiry = new Date(storedRefreshToken.expires_at).getTime();
@@ -145,15 +195,12 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
             const data = await response.json();
             const { access_token, refresh_token } = data;
             if (refresh_token) {
-              localStorage.setItem(
-                AUI_REFRESH_TOKEN_NAME,
-                JSON.stringify(refresh_token),
-              );
+              writeRefreshToken(refresh_token);
             }
             return access_token;
           }
         } else {
-          localStorage.removeItem(AUI_REFRESH_TOKEN_NAME);
+          removeRefreshToken();
         }
       }
 
@@ -169,10 +216,7 @@ export class AssistantCloudAnonymousAuthStrategy implements AssistantCloudAuthSt
 
       if (!access_token || !refresh_token) return null;
 
-      localStorage.setItem(
-        AUI_REFRESH_TOKEN_NAME,
-        JSON.stringify(refresh_token),
-      );
+      writeRefreshToken(refresh_token);
       return access_token;
     });
   }

package/src/AssistantCloudProjectThreadMessages.ts

@@ -0,0 +1,40 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  decodeCloudMessage,
+  type CloudMessage,
+} from "./AssistantCloudThreadMessages";
+import { readCloudArray, readCloudRecord } from "./cloudResponse";
+
+type AssistantCloudProjectThreadMessageListQuery = {
+  format?: string;
+  limit?: number;
+  after?: string;
+};
+
+type AssistantCloudProjectThreadMessageListResponse = {
+  messages: CloudMessage[];
+};
+
+export class AssistantCloudProjectThreadMessages {
+  constructor(private cloud: AssistantCloudAPI) {}
+
+  public async list(
+    threadId: string,
+    query?: AssistantCloudProjectThreadMessageListQuery,
+  ): Promise<AssistantCloudProjectThreadMessageListResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        `/projects/threads/${encodeURIComponent(threadId)}/messages`,
+        { query },
+      ),
+      "project thread message list response",
+    );
+    const messages = readCloudArray(response.messages, "messages");
+
+    return {
+      messages: messages.map((message, index) =>
+        decodeCloudMessage(message, `messages[${index}]`),
+      ),
+    };
+  }
+}

package/src/AssistantCloudProjectThreads.ts

@@ -0,0 +1,47 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudProjectThreadMessages } from "./AssistantCloudProjectThreadMessages";
+import { decodeCloudThread, type CloudThread } from "./AssistantCloudThreads";
+import { readCloudArray, readCloudRecord } from "./cloudResponse";
+
+type AssistantCloudProjectThreadsListQuery = {
+  is_archived?: boolean;
+  limit?: number;
+  after?: string;
+};
+
+type AssistantCloudProjectThreadsListResponse = {
+  threads: CloudThread[];
+};
+
+export class AssistantCloudProjectThreads {
+  public readonly messages: AssistantCloudProjectThreadMessages;
+
+  constructor(private cloud: AssistantCloudAPI) {
+    this.messages = new AssistantCloudProjectThreadMessages(cloud);
+  }
+
+  public async list(
+    query?: AssistantCloudProjectThreadsListQuery,
+  ): Promise<AssistantCloudProjectThreadsListResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/projects/threads", {
+        query: {
+          ...query,
+          // The shared query serializer drops `false`; the wire accepts the
+          // string form, so the archive filter survives explicitly.
+          ...(query?.is_archived !== undefined
+            ? { is_archived: String(query.is_archived) }
+            : {}),
+        },
+      }),
+      "project thread list response",
+    );
+    const threads = readCloudArray(response.threads, "threads");
+
+    return {
+      threads: threads.map((thread, index) =>
+        decodeCloudThread(thread, `threads[${index}]`),
+      ),
+    };
+  }
+}

package/src/AssistantCloudProjects.ts

@@ -0,0 +1,10 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudProjectThreads } from "./AssistantCloudProjectThreads";
+
+export class AssistantCloudProjects {
+  public readonly threads: AssistantCloudProjectThreads;
+
+  constructor(cloud: AssistantCloudAPI) {
+    this.threads = new AssistantCloudProjectThreads(cloud);
+  }
+}

package/src/AssistantCloudThreadMessages.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+
+const createCloudThreadMessages = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return {
+    messages: new AssistantCloudThreadMessages(api),
+    makeRequest,
+  };
+};
+
+describe("AssistantCloudThreadMessages responses", () => {
+  it("decodes canonical message responses without changing content", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    makeRequest.mockResolvedValue({
+      messages: [
+        {
+          id: "message-1",
+          parent_id: null,
+          height: 0,
+          created_at: "2026-07-16T13:00:00.000Z",
+          updated_at: "2026-07-16T13:05:00.987Z",
+          format: "aui/v0",
+          content: { created_at: "leave-this-string-untouched" },
+        },
+      ],
+    });
+
+    const result = await messages.list("thread-1");
+    const message = result.messages[0]!;
+
+    expect(message.created_at).toBeInstanceOf(Date);
+    expect(message.updated_at).toBeInstanceOf(Date);
+    expect(message.updated_at.toISOString()).toBe("2026-07-16T13:05:00.987Z");
+    expect(message.content).toEqual({
+      created_at: "leave-this-string-untouched",
+    });
+  });
+});

package/src/AssistantCloudThreadMessages.ts

@@ -1,5 +1,14 @@
 import type { ReadonlyJSONObject } from "assistant-stream/utils";
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  readCloudArray,
+  readCloudInteger,
+  readCloudJSONObject,
+  readCloudNullableString,
+  readCloudRecord,
+  readCloudString,
+  readCloudTimestamp,
+} from "./cloudResponse";
 
 export type CloudMessage = {
   id: string;
@@ -33,6 +42,22 @@ type AssistantCloudThreadMessageUpdateBody = {
   content: ReadonlyJSONObject;
 };
 
+export const decodeCloudMessage = (
+  value: unknown,
+  field: string,
+): CloudMessage => {
+  const message = readCloudRecord(value, field);
+  return {
+    id: readCloudString(message.id, `${field}.id`),
+    parent_id: readCloudNullableString(message.parent_id, `${field}.parent_id`),
+    height: readCloudInteger(message.height, `${field}.height`),
+    created_at: readCloudTimestamp(message.created_at, `${field}.created_at`),
+    updated_at: readCloudTimestamp(message.updated_at, `${field}.updated_at`),
+    format: readCloudString(message.format, `${field}.format`),
+    content: readCloudJSONObject(message.content, `${field}.content`),
+  };
+};
+
 export class AssistantCloudThreadMessages {
   constructor(private cloud: AssistantCloudAPI) {}
 
@@ -40,10 +65,20 @@ export class AssistantCloudThreadMessages {
     threadId: string,
     query?: AssistantCloudThreadMessageListQuery,
   ): Promise<AssistantCloudThreadMessageListResponse> {
-    return this.cloud.makeRequest(
-      `/threads/${encodeURIComponent(threadId)}/messages`,
-      { query },
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        `/threads/${encodeURIComponent(threadId)}/messages`,
+        { query },
+      ),
+      "thread message list response",
     );
+    const messages = readCloudArray(response.messages, "messages");
+
+    return {
+      messages: messages.map((message, index) =>
+        decodeCloudMessage(message, `messages[${index}]`),
+      ),
+    };
   }
 
   public async create(

package/src/AssistantCloudThreads.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudThreads } from "./AssistantCloudThreads";
+
+const createCloudThreads = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return { threads: new AssistantCloudThreads(api), makeRequest };
+};
+
+const threadResponse = {
+  title: null,
+  last_message_at: "2026-07-16T12:30:00.000Z",
+  metadata: { created_at: "leave-this-string-untouched" },
+  external_id: null,
+  id: "thread-1",
+  project_id: "project-1",
+  created_at: "2026-07-16T12:00:00.000Z",
+  updated_at: "2026-07-16T12:15:00.123Z",
+  workspace_id: "workspace-1",
+  is_archived: false,
+};
+
+describe("AssistantCloudThreads responses", () => {
+  it("decodes canonical thread list responses", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValue({ threads: [threadResponse] });
+
+    const result = await threads.list();
+    const thread = result.threads[0]!;
+
+    expect(thread.created_at).toBeInstanceOf(Date);
+    expect(thread.updated_at).toBeInstanceOf(Date);
+    expect(thread.last_message_at).toBeInstanceOf(Date);
+    expect(thread.updated_at.toISOString()).toBe("2026-07-16T12:15:00.123Z");
+    expect(thread.title).toBe("");
+    expect(thread.metadata).toEqual({
+      created_at: "leave-this-string-untouched",
+    });
+  });
+
+  it("unwraps and decodes a single thread response", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValue({ thread: threadResponse });
+
+    const result = await threads.get("thread-1");
+
+    expect(result.created_at).toBeInstanceOf(Date);
+    expect(result.created_at.toISOString()).toBe("2026-07-16T12:00:00.000Z");
+  });
+
+  it("rejects a bare thread that is missing the response envelope", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValue(threadResponse);
+
+    await expect(threads.get("thread-1")).rejects.toThrow(
+      'Invalid Assistant Cloud response for "thread": expected an object',
+    );
+  });
+
+  it("rejects genuinely invalid response timestamps with field context", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValue({
+      thread: {
+        ...threadResponse,
+        updated_at: "not-a-timestamp",
+      },
+    });
+
+    await expect(threads.get("thread-1")).rejects.toThrow(
+      'Invalid Assistant Cloud response for "thread.updated_at": expected a canonical ISO timestamp',
+    );
+  });
+});

package/src/AssistantCloudThreads.ts

@@ -1,5 +1,13 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import {
+  readCloudArray,
+  readCloudBoolean,
+  readCloudNullableString,
+  readCloudRecord,
+  readCloudString,
+  readCloudTimestamp,
+} from "./cloudResponse";
 
 type AssistantCloudThreadsListQuery = {
   is_archived?: boolean;
@@ -7,7 +15,7 @@ type AssistantCloudThreadsListQuery = {
   after?: string;
 };
 
-type CloudThread = {
+export type CloudThread = {
   title: string;
   last_message_at: Date;
   metadata: unknown;
@@ -42,6 +50,31 @@ type AssistantCloudThreadsUpdateBody = {
   is_archived?: boolean | undefined;
 };
 
+export const decodeCloudThread = (
+  value: unknown,
+  field: string,
+): CloudThread => {
+  const thread = readCloudRecord(value, field);
+  return {
+    title: readCloudNullableString(thread.title, `${field}.title`) ?? "",
+    last_message_at: readCloudTimestamp(
+      thread.last_message_at,
+      `${field}.last_message_at`,
+    ),
+    metadata: thread.metadata,
+    external_id: readCloudNullableString(
+      thread.external_id,
+      `${field}.external_id`,
+    ),
+    id: readCloudString(thread.id, `${field}.id`),
+    project_id: readCloudString(thread.project_id, `${field}.project_id`),
+    created_at: readCloudTimestamp(thread.created_at, `${field}.created_at`),
+    updated_at: readCloudTimestamp(thread.updated_at, `${field}.updated_at`),
+    workspace_id: readCloudString(thread.workspace_id, `${field}.workspace_id`),
+    is_archived: readCloudBoolean(thread.is_archived, `${field}.is_archived`),
+  };
+};
+
 export class AssistantCloudThreads {
   public readonly messages: AssistantCloudThreadMessages;
 
@@ -52,11 +85,26 @@ export class AssistantCloudThreads {
   public async list(
     query?: AssistantCloudThreadsListQuery,
   ): Promise<AssistantCloudThreadsListResponse> {
-    return this.cloud.makeRequest("/threads", { query });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/threads", { query }),
+      "thread list response",
+    );
+    const threads = readCloudArray(response.threads, "threads");
+
+    return {
+      threads: threads.map((thread, index) =>
+        decodeCloudThread(thread, `threads[${index}]`),
+      ),
+    };
   }
 
   public async get(threadId: string): Promise<CloudThread> {
-    return this.cloud.makeRequest(`/threads/${encodeURIComponent(threadId)}`);
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(`/threads/${encodeURIComponent(threadId)}`),
+      "thread response",
+    );
+
+    return decodeCloudThread(response.thread, "thread");
   }
 
   public async create(

package/src/CloudMessagePersistence.ts

@@ -14,8 +14,13 @@ import type { AssistantCloud } from "./AssistantCloud";
  */
 export class CloudMessagePersistence {
   private idMapping: Record<string, string | Promise<string>> = {};
+  private getCloud: () => AssistantCloud;
 
-  constructor(private cloud: AssistantCloud) {}
+  constructor(cloud: AssistantCloud);
+  constructor(getCloud: () => AssistantCloud);
+  constructor(cloud: AssistantCloud | (() => AssistantCloud)) {
+    this.getCloud = typeof cloud === "function" ? cloud : () => cloud;
+  }
 
   /**
    * Persist a message to the cloud.
@@ -33,12 +38,13 @@ export class CloudMessagePersistence {
     format: string,
     content: ReadonlyJSONObject,
   ): Promise<void> {
+    const cloud = this.getCloud();
     // Resolve parent's remote ID if it exists (may be a promise if concurrent)
     const resolvedParentId = parentId
       ? ((await this.idMapping[parentId]) ?? parentId)
       : null;
 
-    const task = this.cloud.threads.messages
+    const task = cloud.threads.messages
       .create(threadId, {
         parent_id: resolvedParentId,
         format,
@@ -70,9 +76,15 @@ export class CloudMessagePersistence {
     _format: string,
     content: ReadonlyJSONObject,
   ): Promise<void> {
+    const cloud = this.getCloud();
     const remoteId = await this.getRemoteId(messageId);
-    if (!remoteId) return; // not persisted yet, skip
-    await this.cloud.threads.messages.update(threadId, remoteId, { content });
+    if (!remoteId) {
+      console.warn(
+        `Skipping update for message ${messageId}: no remote id is mapped.`,
+      );
+      return;
+    }
+    await cloud.threads.messages.update(threadId, remoteId, { content });
   }
 
   /**
@@ -103,7 +115,8 @@ export class CloudMessagePersistence {
    * @returns Array of cloud messages
    */
   async load(threadId: string, format?: string) {
-    const { messages } = await this.cloud.threads.messages.list(
+    const cloud = this.getCloud();
+    const { messages } = await cloud.threads.messages.list(
       threadId,
       format ? { format } : undefined,
     );

package/src/cloudResponse.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { CloudResponseError, readCloudTimestamp } from "./cloudResponse";
+
+describe("readCloudTimestamp", () => {
+  it("decodes a canonical Cloud timestamp", () => {
+    expect(
+      readCloudTimestamp(
+        "2026-07-16T12:15:00.123Z",
+        "thread.updated_at",
+      ).toISOString(),
+    ).toBe("2026-07-16T12:15:00.123Z");
+  });
+
+  it.each([
+    "2026-02-30T12:15:00.000Z",
+    "2026-13-01T12:15:00Z",
+    "2026-07-16 12:15:00.123456",
+    "2026-07-16T12:15:00.123+00:00",
+    new Date("2026-07-16T12:15:00.123Z"),
+    "not-a-timestamp",
+  ])("rejects invalid timestamp %s", (value) => {
+    const decode = () => readCloudTimestamp(value, "thread.updated_at");
+    expect(decode).toThrow(CloudResponseError);
+    expect(decode).toThrow(
+      'Invalid Assistant Cloud response for "thread.updated_at": expected a canonical ISO timestamp',
+    );
+  });
+});

package/src/cloudResponse.ts

@@ -0,0 +1,72 @@
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+export class CloudResponseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CloudResponseError";
+  }
+}
+
+const invalidCloudResponse = (field: string, expected: string) =>
+  new CloudResponseError(
+    `Invalid Assistant Cloud response for "${field}": expected ${expected}`,
+  );
+
+export const readCloudRecord = (
+  value: unknown,
+  field: string,
+): Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalidCloudResponse(field, "an object");
+  }
+  return value as Record<string, unknown>;
+};
+
+export const readCloudArray = (value: unknown, field: string): unknown[] => {
+  if (!Array.isArray(value)) throw invalidCloudResponse(field, "an array");
+  return value;
+};
+
+export const readCloudString = (value: unknown, field: string): string => {
+  if (typeof value !== "string") throw invalidCloudResponse(field, "a string");
+  return value;
+};
+
+export const readCloudNullableString = (
+  value: unknown,
+  field: string,
+): string | null => {
+  if (value === null) return null;
+  return readCloudString(value, field);
+};
+
+export const readCloudBoolean = (value: unknown, field: string): boolean => {
+  if (typeof value !== "boolean") {
+    throw invalidCloudResponse(field, "a boolean");
+  }
+  return value;
+};
+
+export const readCloudInteger = (value: unknown, field: string): number => {
+  if (!Number.isInteger(value)) throw invalidCloudResponse(field, "an integer");
+  return value as number;
+};
+
+export const readCloudTimestamp = (value: unknown, field: string): Date => {
+  if (typeof value !== "string") {
+    throw invalidCloudResponse(field, "a canonical ISO timestamp");
+  }
+
+  const date = new Date(value);
+  // The round trip pins the backend DTO's Date#toISOString() wire contract.
+  if (Number.isNaN(date.getTime()) || date.toISOString() !== value) {
+    throw invalidCloudResponse(field, "a canonical ISO timestamp");
+  }
+
+  return date;
+};
+
+export const readCloudJSONObject = (
+  value: unknown,
+  field: string,
+): ReadonlyJSONObject => readCloudRecord(value, field) as ReadonlyJSONObject;

package/src/index.ts

@@ -1,5 +1,7 @@
 export type { CloudMessage } from "./AssistantCloudThreadMessages";
 export type { AssistantCloudTelemetryConfig } from "./AssistantCloudAPI";
+export { CloudAPIError } from "./AssistantCloudAPI";
+export { CloudResponseError } from "./cloudResponse";
 export type { AssistantCloudRunReport } from "./AssistantCloudRuns";
 export { AssistantCloud } from "./AssistantCloud";
 export { CloudMessagePersistence } from "./CloudMessagePersistence";