assistant-cloud 0.2.1 → 0.2.3

package/src/AssistantCloudThreadMessages.test.ts

@@ -43,14 +43,65 @@ describe("AssistantCloudThreadMessages responses", () => {
 
     await expect(
       messages.feedback("thread/1", "message/1", body),
-    ).resolves.toEqual({
+    ).resolves.toStrictEqual({
       feedback_id: "feedback-1",
       type: "positive",
     });
     expect(makeRequest).toHaveBeenCalledWith(
       "/threads/thread%2F1/messages/message%2F1/feedback",
-      { method: "POST", body },
+      { method: "POST", body: { type: "positive" } },
     );
+    expect(makeRequest.mock.calls[0]![1].body).toStrictEqual({
+      type: "positive",
+    });
+
+    const bodyWithComment = {
+      type: "negative" as const,
+      comment: "The response missed a detail",
+    };
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-2",
+      type: "negative",
+      comment: "The response missed a detail",
+    });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", bodyWithComment),
+    ).resolves.toEqual({
+      feedback_id: "feedback-2",
+      type: "negative",
+      comment: "The response missed a detail",
+    });
+    expect(makeRequest).toHaveBeenLastCalledWith(
+      "/threads/thread-1/messages/message-1/feedback",
+      { method: "POST", body: bodyWithComment },
+    );
+
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-1",
+      type: "positive",
+    });
+    await messages.feedback("thread-1", "message-1", {
+      type: "positive",
+      comment: "   ",
+    });
+    expect(makeRequest.mock.lastCall![1].body).toStrictEqual({
+      type: "positive",
+    });
+
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-3",
+      type: "positive",
+      comment: null,
+    });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", body),
+    ).resolves.toStrictEqual({
+      feedback_id: "feedback-3",
+      type: "positive",
+      comment: null,
+    });
 
     makeRequest.mockResolvedValueOnce({ type: "positive" });
 

package/src/AssistantCloudThreadMessages.ts

@@ -19,6 +19,7 @@ export type CloudMessage = {
   updated_at: Date;
   format: "aui/v0" | string;
   content: ReadonlyJSONObject;
+  external_id?: string | null | undefined;
 };
 
 type AssistantCloudThreadMessageListQuery = {
@@ -35,6 +36,8 @@ type AssistantCloudThreadMessageCreateBody = {
   parent_id: string | null;
   format: "aui/v0" | string;
   content: ReadonlyJSONObject;
+  external_id?: string | undefined;
+  parent_external_id?: string | undefined;
 };
 
 type AssistantCloudMessageCreateResponse = {
@@ -49,11 +52,13 @@ const MESSAGE_FEEDBACK_TYPES = ["positive", "negative"] as const;
 
 export type AssistantCloudThreadMessageFeedbackBody = {
   type: "positive" | "negative";
+  comment?: string;
 };
 
 export type AssistantCloudThreadMessageFeedbackResponse = {
   feedback_id: string;
   type: "positive" | "negative";
+  comment?: string | null;
 };
 
 export const decodeCloudMessage = (
@@ -69,6 +74,10 @@ export const decodeCloudMessage = (
     updated_at: readCloudTimestamp(message.updated_at, `${field}.updated_at`),
     format: readCloudString(message.format, `${field}.format`),
     content: readCloudJSONObject(message.content, `${field}.content`),
+    external_id: readCloudNullableString(
+      message.external_id ?? null,
+      `${field}.external_id`,
+    ),
   };
 };
 
@@ -106,7 +115,20 @@ export class AssistantCloudThreadMessages {
     const response = readCloudRecord(
       await this.cloud.makeRequest(
         `/threads/${encodeURIComponent(threadId)}/messages`,
-        { method: "POST", body },
+        {
+          method: "POST",
+          body: {
+            parent_id: body.parent_id,
+            format: body.format,
+            content: body.content,
+            ...(body.external_id !== undefined
+              ? { external_id: body.external_id }
+              : undefined),
+            ...(body.parent_external_id !== undefined
+              ? { parent_external_id: body.parent_external_id }
+              : undefined),
+          },
+        },
       ),
       "thread message create response",
     );
@@ -132,10 +154,17 @@ export class AssistantCloudThreadMessages {
     messageId: string,
     body: AssistantCloudThreadMessageFeedbackBody,
   ): Promise<AssistantCloudThreadMessageFeedbackResponse> {
+    const comment = body.comment?.trim();
     const response = readCloudRecord(
       await this.cloud.makeRequest(
         `/threads/${encodeURIComponent(threadId)}/messages/${encodeURIComponent(messageId)}/feedback`,
-        { method: "POST", body },
+        {
+          method: "POST",
+          body: {
+            type: body.type,
+            ...(comment ? { comment } : undefined),
+          },
+        },
       ),
       "thread message feedback response",
     );
@@ -143,6 +172,9 @@ export class AssistantCloudThreadMessages {
     return {
       feedback_id: readCloudString(response.feedback_id, "feedback_id"),
       type: readCloudEnum(response.type, "type", MESSAGE_FEEDBACK_TYPES),
+      ...("comment" in response
+        ? { comment: readCloudNullableString(response.comment, "comment") }
+        : undefined),
     };
   }
 }

package/src/BackendTranscriptCopy.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "./AssistantCloud";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import { CloudMessagePersistence } from "./CloudMessagePersistence";
+
+describe("backend transcript cloud client", () => {
+  it("sends external ids only when supplied", async () => {
+    const makeRequest = vi.fn().mockResolvedValue({ message_id: "cloud-1" });
+    const messages = new AssistantCloudThreadMessages({
+      makeRequest,
+    } as unknown as AssistantCloudAPI);
+    const body = { parent_id: null, format: "aui/v0", content: {} };
+
+    await messages.create("thread-1", body);
+    expect(makeRequest).toHaveBeenLastCalledWith("/threads/thread-1/messages", {
+      method: "POST",
+      body,
+    });
+
+    await messages.create("thread-1", {
+      ...body,
+      external_id: "backend-1",
+      parent_external_id: "backend-0",
+    });
+    expect(makeRequest).toHaveBeenLastCalledWith("/threads/thread-1/messages", {
+      method: "POST",
+      body: {
+        ...body,
+        external_id: "backend-1",
+        parent_external_id: "backend-0",
+      },
+    });
+  });
+
+  it("decodes external ids and treats an absent field as null", async () => {
+    const makeRequest = vi.fn().mockResolvedValue({
+      messages: [
+        {
+          id: "cloud-1",
+          parent_id: null,
+          height: 0,
+          created_at: "2026-01-01T00:00:00.000Z",
+          updated_at: "2026-01-01T00:00:00.000Z",
+          format: "aui/v0",
+          content: {},
+          external_id: "backend-1",
+        },
+        {
+          id: "cloud-2",
+          parent_id: "cloud-1",
+          height: 1,
+          created_at: "2026-01-01T00:00:00.000Z",
+          updated_at: "2026-01-01T00:00:00.000Z",
+          format: "aui/v0",
+          content: {},
+        },
+      ],
+    });
+    const messages = new AssistantCloudThreadMessages({
+      makeRequest,
+    } as unknown as AssistantCloudAPI);
+
+    const result = await messages.list("thread-1");
+    expect(result.messages.map((message) => message.external_id)).toEqual([
+      "backend-1",
+      null,
+    ]);
+  });
+
+  it("records a resolved local to cloud message mapping", async () => {
+    const persistence = new CloudMessagePersistence({} as AssistantCloud);
+    persistence.record("backend-1", "cloud-1");
+
+    expect(persistence.isPersisted("backend-1")).toBe(true);
+    expect(await persistence.getRemoteId("backend-1")).toBe("cloud-1");
+    expect(persistence.getResolvedRemoteId("backend-1")).toBe("cloud-1");
+  });
+});

package/src/CloudEngagementReporter.ts

@@ -13,13 +13,14 @@ export type EngagementEventIds = Pick<
  * 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.
+ * already exist. Returning nothing declines the event: the thread is not one
+ * the integration knows, so there is nothing to attribute it to.
  */
 export type EngagementIdResolver = (
   threadId: string,
   messageId: string | undefined,
   options: { awaitThread: boolean },
-) => EngagementEventIds | Promise<EngagementEventIds>;
+) => EngagementEventIds | undefined | Promise<EngagementEventIds | undefined>;
 
 type EngagementEventInit = Pick<AssistantCloudEvent, "value" | "props">;
 
@@ -86,9 +87,13 @@ export class CloudEngagementReporter {
   public runStopped(threadId: string): void {
     const startedAt = this.runStartedAt.get(threadId);
     if (startedAt === undefined) return;
+    const stoppedAt = Date.now();
     this.runStartedAt.delete(threadId);
+    // A stopped run is a run that ended, so the next send measures its idle
+    // time from here rather than from the last run allowed to finish.
+    remember(this.runEndedAt, threadId, stoppedAt);
     this.track("run_stopped", threadId, undefined, {
-      value: Math.max(0, Date.now() - startedAt),
+      value: Math.max(0, stoppedAt - startedAt),
     });
   }
 
@@ -223,6 +228,7 @@ export class CloudEngagementReporter {
     void Promise.resolve()
       .then(() => this.resolveIds(threadId, messageId, options))
       .then((ids) => {
+        if (!ids) return;
         if (kind === "thread_switched" && !ids.thread_id) return;
         this.getCloud().events.track({ kind, ...init, ...ids });
       })

package/src/CloudMessagePersistence.ts

@@ -111,6 +111,10 @@ export class CloudMessagePersistence {
     return typeof entry === "string" ? entry : undefined;
   }
 
+  record(localId: string, remoteId: string): void {
+    this.idMapping.set(localId, remoteId);
+  }
+
   /**
    * Load messages from the cloud and populate the ID mapping.
    *

package/src/CloudRunReporter.ts

@@ -1,4 +1,5 @@
 import type { AssistantCloud } from "./AssistantCloud";
+import { CloudAPIError } from "./AssistantCloudAPI";
 import { createRunReport, type RunReportInit } from "./runTelemetry";
 
 export type CloudRunReportInit = Omit<RunReportInit, "telemetry">;
@@ -7,8 +8,8 @@ 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.
+ * A keyed report is deduplicated while in flight and after an attempt. A
+ * rate-limited attempt releases the key so a later observation can try again.
  */
 export class CloudRunReporter {
   private readonly reported = new Set<string>();
@@ -19,6 +20,7 @@ export class CloudRunReporter {
   }
 
   public async report(init: CloudRunReportInit, key?: string): Promise<void> {
+    let claimedKey: string | undefined;
     try {
       const cloud = this.getCloud();
       if (!cloud.telemetry.enabled) return;
@@ -29,10 +31,20 @@ export class CloudRunReporter {
       const report = beforeReport ? beforeReport(initial) : initial;
       if (!report) return;
 
-      if (key !== undefined) this.reported.add(key);
+      if (key !== undefined) {
+        this.reported.add(key);
+        claimedKey = key;
+      }
       await cloud.runs.report(report);
-    } catch {
+    } catch (error) {
+      if (claimedKey !== undefined && isRetryableReportError(error)) {
+        this.reported.delete(claimedKey);
+      }
       return;
     }
   }
 }
+
+const isRetryableReportError = (error: unknown): boolean => {
+  return error instanceof CloudAPIError && error.status === 429;
+};

package/src/ai-sdk/index.test.ts

@@ -79,7 +79,7 @@ describe("extractAISDKRunTelemetry", () => {
           {},
         ],
         samplingCalls: { call_2: [{ duration_ms: 20 }] },
-        modelId: "gpt-5.6-luna",
+        modelId: "gpt-6-luna",
       },
     );
 
@@ -119,7 +119,7 @@ describe("extractAISDKRunTelemetry", () => {
       totalSteps: 3,
       outputText: "Cold.",
       usage: { inputTokens: 10, outputTokens: 5 },
-      modelId: "gpt-5.6-luna",
+      modelId: "gpt-6-luna",
       metadata: message.metadata,
     });
   });

package/src/runTelemetry.test.ts

@@ -187,7 +187,7 @@ describe("createRunReport", () => {
         threadId: "ai-sdk-thread",
         status: "completed",
         traceId: "00112233445566778899aabbccddeeff",
-        modelId: "gpt-5.6-terra",
+        modelId: "gpt-6-sol",
         provider: "gateway",
         usage: {
           inputTokens: 100,
@@ -215,7 +215,7 @@ describe("createRunReport", () => {
       thread_id: "ai-sdk-thread",
       status: "completed",
       trace_id: "00112233445566778899aabbccddeeff",
-      model_id: "gpt-5.6-terra",
+      model_id: "gpt-6-sol",
       provider: "gateway",
       provider_type: "gateway",
       input_tokens: 100,
@@ -289,6 +289,90 @@ describe("createRunReport", () => {
       }),
     ).toEqual({ thread_id: "thread", status: "completed" });
   });
+
+  it("normalizes caller-supplied run cost, attributes, and root span", () => {
+    expect(
+      createRunReport({
+        threadId: "thread",
+        status: "completed",
+        rootSpanId: "AABBCCDDEEFF0011",
+        costUsd: 0.012,
+        costDetails: {
+          input: 0.002,
+          inputCachedTokens: 0.001,
+          output: 0.009,
+          total: 0.012,
+        },
+        attributes: { tenant: "acme" },
+      }),
+    ).toEqual({
+      thread_id: "thread",
+      status: "completed",
+      root_span_id: "aabbccddeeff0011",
+      cost_usd: 0.012,
+      cost_details: {
+        input: 0.002,
+        input_cached_tokens: 0.001,
+        output: 0.009,
+        total: 0.012,
+      },
+      attributes: { tenant: "acme" },
+    });
+  });
+
+  it("keeps valid cost members beside invalid ones", () => {
+    expect(
+      createRunReport({
+        threadId: "thread",
+        status: "completed",
+        costUsd: 0,
+        costDetails: {
+          input: 0.002,
+          inputCachedTokens: Number.NaN,
+          output: -1,
+          total: 0,
+        },
+      }),
+    ).toEqual({
+      thread_id: "thread",
+      status: "completed",
+      cost_usd: 0,
+      cost_details: { input: 0.002, total: 0 },
+    });
+  });
+
+  it("omits invalid run cost and root span values", () => {
+    expect(
+      createRunReport({
+        threadId: "thread",
+        status: "completed",
+        rootSpanId: "not-a-span-id",
+        costUsd: Number.POSITIVE_INFINITY,
+        costDetails: {
+          input: -1,
+          inputCachedTokens: Number.NaN,
+          output: Number.NEGATIVE_INFINITY,
+        },
+      }),
+    ).toEqual({ thread_id: "thread", status: "completed" });
+  });
+
+  it("keeps a server outcome type and truncates the step input", () => {
+    expect(
+      createRunReport({
+        threadId: "thread",
+        status: "error",
+        outcome: "timeout",
+        steps: [{ input: "a".repeat(MAX + 1) }],
+      }),
+    ).toEqual({
+      thread_id: "thread",
+      status: "error",
+      outcome_type: "timeout",
+      steps: [{ input: "a".repeat(MAX) }],
+      total_steps: 1,
+    });
+  });
 });
 
 describe("truncateRunTelemetryText", () => {
@@ -371,6 +455,146 @@ describe("createRunTelemetryToolCall", () => {
     expect(call.tool_result).not.toContain("A".repeat(200));
   });
 
+  it("summarizes a short base64 payload the same as a long one", () => {
+    // `aGk=` is how this repo's own MCP fixtures spell a whole image.
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: {
+        content: [
+          { type: "image", data: "aGk=", mimeType: "image/png" },
+          { type: "audio", data: "aGk=", mimeType: "audio/wav" },
+          {
+            type: "resource",
+            resource: { uri: "file:///a.pdf", blob: "aGk=" },
+          },
+        ],
+      },
+    });
+    expect(call.tool_result).not.toContain("aGk=");
+    expect(call.tool_result).toContain("[image:");
+    expect(call.tool_result).toContain("[audio:");
+    expect(call.tool_result).toContain("[resource:");
+    // a field the grammar does not define as base64 is left alone
+    expect(call.tool_result).toContain("image/png");
+  });
+
+  it("leaves plain text in an mcp result untouched", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: { content: [{ type: "text", text: "test" }] },
+    });
+    expect(call.tool_result).toContain("test");
+  });
+
+  it("summarizes base64 blocks inside an mcp CallToolResult envelope", () => {
+    // what @modelcontextprotocol/sdk callTool actually returns
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: {
+        content: [
+          { type: "text", text: "keep me" },
+          { type: "image", data: "A".repeat(4096) },
+        ],
+        isError: false,
+      },
+    });
+
+    expect(call.tool_result).toContain("keep me");
+    expect(call.tool_result).toContain("[image: 3.0KB]");
+    expect(call.tool_result).not.toContain("A".repeat(200));
+  });
+
+  it("keeps the envelope's sibling fields when summarizing its content", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: {
+        content: [{ type: "image", data: "A".repeat(4096) }],
+        isError: true,
+        structuredContent: { ok: false },
+      },
+    });
+
+    expect(call.tool_result).toContain("[image: 3.0KB]");
+    expect(call.tool_result).toContain('"isError":true');
+    expect(call.tool_result).toContain('"structuredContent":{"ok":false}');
+  });
+
+  it("summarizes a CallToolResult that arrived as a JSON string", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: JSON.stringify({
+        content: [{ type: "audio", data: "A".repeat(4096) }],
+      }),
+    });
+
+    expect(call.tool_result).toContain("[audio: 3.0KB]");
+    expect(call.tool_result).not.toContain("A".repeat(200));
+  });
+
+  it("leaves an object without content blocks alone", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: { content: "not blocks", other: 1 },
+    });
+
+    expect(call.tool_result).toContain('"content":"not blocks"');
+    expect(call.tool_result).toContain('"other":1');
+  });
+
+  it("summarizes the base64 blob of an embedded resource", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: {
+        content: [
+          {
+            type: "resource",
+            resource: {
+              uri: "file:///report.pdf",
+              mimeType: "application/pdf",
+              blob: "A".repeat(4096),
+            },
+          },
+        ],
+      },
+    });
+
+    expect(call.tool_result).toContain("[resource: 3.0KB]");
+    expect(call.tool_result).toContain("file:///report.pdf");
+    expect(call.tool_result).not.toContain("A".repeat(200));
+  });
+
+  it("leaves a text-bearing embedded resource alone", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: {
+        content: [
+          {
+            type: "resource",
+            resource: { uri: "file:///a.txt", text: "plain text" },
+          },
+        ],
+      },
+    });
+
+    expect(call.tool_result).toContain("plain text");
+  });
+
   it("leaves a non-mcp result unsummarized", () => {
     const result = [{ type: "image", data: "A".repeat(4096) }];
     const call = createRunTelemetryToolCall({