assistant-cloud 0.1.40 → 0.1.42

package/src/AssistantCloudThreadMessages.test.ts

@@ -12,6 +12,26 @@ const createCloudThreadMessages = () => {
 };
 
 describe("AssistantCloudThreadMessages responses", () => {
+  it("validates created message IDs", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    const body = {
+      parent_id: null,
+      format: "aui/v0",
+      content: {},
+    };
+    makeRequest.mockResolvedValueOnce({ message_id: "message-1" });
+
+    await expect(messages.create("thread-1", body)).resolves.toEqual({
+      message_id: "message-1",
+    });
+
+    makeRequest.mockResolvedValueOnce({});
+
+    await expect(messages.create("thread-1", body)).rejects.toThrow(
+      'Invalid Assistant Cloud response for "message_id": expected a string',
+    );
+  });
+
   it("decodes canonical message responses without changing content", async () => {
     const { messages, makeRequest } = createCloudThreadMessages();
     makeRequest.mockResolvedValue({

package/src/AssistantCloudThreadMessages.ts

@@ -89,10 +89,17 @@ export class AssistantCloudThreadMessages {
     threadId: string,
     body: AssistantCloudThreadMessageCreateBody,
   ): Promise<AssistantCloudMessageCreateResponse> {
-    return this.cloud.makeRequest(
-      `/threads/${encodeURIComponent(threadId)}/messages`,
-      { method: "POST", body },
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        `/threads/${encodeURIComponent(threadId)}/messages`,
+        { method: "POST", body },
+      ),
+      "thread message create response",
     );
+
+    return {
+      message_id: readCloudString(response.message_id, "message_id"),
+    };
   }
 
   public async update(

package/src/AssistantCloudThreads.test.ts

@@ -22,6 +22,23 @@ const threadResponse = {
 };
 
 describe("AssistantCloudThreads responses", () => {
+  it("validates created thread IDs", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValueOnce({ thread_id: "thread-1" });
+
+    await expect(
+      threads.create({ last_message_at: new Date() }),
+    ).resolves.toEqual({ thread_id: "thread-1" });
+
+    makeRequest.mockResolvedValueOnce({});
+
+    await expect(
+      threads.create({ last_message_at: new Date() }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "thread_id": expected a string',
+    );
+  });
+
   it("forwards both archive filter values", async () => {
     const { threads, makeRequest } = createCloudThreads();
     makeRequest.mockResolvedValue({ threads: [] });

package/src/AssistantCloudThreads.ts

@@ -117,7 +117,12 @@ export class AssistantCloudThreads {
   public async create(
     body: AssistantCloudThreadsCreateBody,
   ): Promise<AssistantCloudThreadsCreateResponse> {
-    return this.cloud.makeRequest("/threads", { method: "POST", body });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/threads", { method: "POST", body }),
+      "thread create response",
+    );
+
+    return { thread_id: readCloudString(response.thread_id, "thread_id") };
   }
 
   public async update(

package/src/generateThreadTitle.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "./AssistantCloud";
+import { generateThreadTitle } from "./generateThreadTitle";
+
+const titleStream = (...chunks: { type: string; textDelta?: string }[]) =>
+  new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) controller.enqueue(chunk);
+      controller.close();
+    },
+  });
+
+const createCloud = (stream: ReadableStream<unknown>) => {
+  const update = vi.fn().mockResolvedValue(undefined);
+  const run = vi.fn().mockResolvedValue(stream);
+  const cloud = {
+    threads: { update },
+    runs: { stream: run },
+  } as unknown as AssistantCloud;
+  return { cloud, update, run };
+};
+
+describe("generateThreadTitle", () => {
+  it("accumulates text deltas and updates the thread title", async () => {
+    const { cloud, run, update } = createCloud(
+      titleStream(
+        { type: "text-delta", textDelta: "Weather " },
+        { type: "text-delta", textDelta: "chat" },
+      ),
+    );
+
+    await expect(
+      generateThreadTitle(cloud, {
+        threadId: "thread-1",
+        messages: [
+          {
+            role: "user",
+            content: [{ type: "text", text: "What is the weather today?" }],
+          },
+        ],
+      }),
+    ).resolves.toBe("Weather chat");
+
+    expect(run).toHaveBeenCalledExactlyOnceWith({
+      thread_id: "thread-1",
+      assistant_id: "system/thread_title",
+      messages: [
+        {
+          role: "user",
+          content: [{ type: "text", text: "What is the weather today?" }],
+        },
+      ],
+    });
+    expect(update).toHaveBeenCalledExactlyOnceWith("thread-1", {
+      title: "Weather chat",
+    });
+  });
+
+  it("returns null without updating when the stream has no text", async () => {
+    const { cloud, update } = createCloud(titleStream());
+
+    await expect(
+      generateThreadTitle(cloud, {
+        threadId: "thread-1",
+        messages: [],
+      }),
+    ).resolves.toBeNull();
+
+    expect(update).not.toHaveBeenCalled();
+  });
+});

package/src/generateThreadTitle.ts

@@ -0,0 +1,38 @@
+import type { AssistantCloud } from "./AssistantCloud";
+
+export async function generateThreadTitle(
+  cloud: AssistantCloud,
+  options: {
+    threadId: string;
+    messages: readonly {
+      role: string;
+      content: readonly { type: "text"; text: string }[];
+    }[];
+  },
+): Promise<string | null> {
+  const stream = await cloud.runs.stream({
+    thread_id: options.threadId,
+    assistant_id: "system/thread_title",
+    messages: options.messages,
+  });
+
+  let title = "";
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done, value: chunk } = await reader.read();
+      if (done) break;
+      if (chunk.type === "text-delta") {
+        title += chunk.textDelta;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  if (title) {
+    await cloud.threads.update(options.threadId, { title });
+  }
+
+  return title || null;
+}

package/src/index.ts

@@ -2,7 +2,17 @@ export type { CloudMessage } from "./AssistantCloudThreadMessages";
 export type { AssistantCloudTelemetryConfig } from "./AssistantCloudAPI";
 export { CloudAPIError } from "./AssistantCloudAPI";
 export { CloudResponseError } from "./cloudResponse";
+export { generateThreadTitle } from "./generateThreadTitle";
 export type { AssistantCloudRunReport } from "./AssistantCloudRuns";
+export {
+  createRunTelemetryToolCall,
+  normalizeRunTelemetryUsage,
+  truncateRunTelemetryText,
+  type AssistantCloudRunReportToolCall,
+  type RunTelemetryToolCallInit,
+  type RunTelemetryUsage,
+  type RunTelemetryUsageInit,
+} from "./runTelemetry";
 export { AssistantCloud } from "./AssistantCloud";
 export { CloudMessagePersistence } from "./CloudMessagePersistence";
 export {

package/src/runTelemetry.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import {
+  createRunTelemetryToolCall,
+  normalizeRunTelemetryUsage,
+  truncateRunTelemetryText,
+} from "./runTelemetry";
+
+const MAX = 50_000;
+
+describe("truncateRunTelemetryText", () => {
+  it("passes text at or under the cap through unchanged", () => {
+    expect(truncateRunTelemetryText("hello")).toBe("hello");
+    const exact = "a".repeat(MAX);
+    expect(truncateRunTelemetryText(exact)).toBe(exact);
+  });
+
+  it("clamps text over the cap", () => {
+    expect(truncateRunTelemetryText("a".repeat(MAX + 1))).toHaveLength(MAX);
+  });
+});
+
+describe("createRunTelemetryToolCall", () => {
+  it("serializes args and omits tool_source when the caller gives none", () => {
+    expect(
+      createRunTelemetryToolCall({
+        toolName: "calculator",
+        toolCallId: "call-1",
+        args: { a: 1 },
+        result: { sum: 1 },
+      }),
+    ).toEqual({
+      tool_name: "calculator",
+      tool_call_id: "call-1",
+      tool_args: '{"a":1}',
+      tool_result: '{"sum":1}',
+    });
+  });
+
+  it("clamps serialized args and results", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      args: { blob: "a".repeat(MAX) },
+      result: { blob: "a".repeat(MAX) },
+    });
+    expect(call.tool_args).toHaveLength(MAX);
+    expect(call.tool_result).toHaveLength(MAX);
+  });
+
+  it("clamps pre-serialized argsText to the cap", () => {
+    const argsText = "a".repeat(MAX + 10);
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      argsText,
+      args: { ignored: true },
+    });
+    expect(call.tool_args).toBe(argsText.slice(0, MAX));
+  });
+
+  it("omits fields whose value cannot be serialized", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(
+      createRunTelemetryToolCall({
+        toolName: "t",
+        toolCallId: "call-1",
+        args: circular,
+        result: undefined,
+      }),
+    ).toEqual({ tool_name: "t", tool_call_id: "call-1" });
+  });
+
+  it("summarizes base64 image and audio blocks in an mcp result", () => {
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "mcp",
+      result: [
+        { type: "text", text: "keep me" },
+        { type: "image", data: "A".repeat(4096) },
+      ],
+    });
+    expect(call.tool_source).toBe("mcp");
+    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("leaves a non-mcp result unsummarized", () => {
+    const result = [{ type: "image", data: "A".repeat(4096) }];
+    const call = createRunTelemetryToolCall({
+      toolName: "t",
+      toolCallId: "call-1",
+      toolSource: "frontend",
+      result,
+    });
+    expect(call.tool_source).toBe("frontend");
+    expect(call.tool_result).toBe(JSON.stringify(result));
+  });
+});
+
+describe("normalizeRunTelemetryUsage", () => {
+  it("prefers the current names over the legacy ones", () => {
+    expect(
+      normalizeRunTelemetryUsage({
+        inputTokens: 1,
+        outputTokens: 2,
+        promptTokens: 90,
+        completionTokens: 90,
+      }),
+    ).toEqual({ inputTokens: 1, outputTokens: 2 });
+  });
+
+  it("falls back to the legacy prompt and completion names", () => {
+    expect(
+      normalizeRunTelemetryUsage({ promptTokens: 3, completionTokens: 4 }),
+    ).toEqual({ inputTokens: 3, outputTokens: 4 });
+  });
+
+  it("keeps a zero count and omits an absent one", () => {
+    expect(
+      normalizeRunTelemetryUsage({ inputTokens: 0, cachedInputTokens: 5 }),
+    ).toEqual({ inputTokens: 0, cachedInputTokens: 5 });
+  });
+
+  it("returns undefined when no count is present", () => {
+    expect(normalizeRunTelemetryUsage({})).toBeUndefined();
+  });
+});

package/src/runTelemetry.ts

@@ -0,0 +1,140 @@
+import type { SamplingCallData } from "./instrumentMcpSampling";
+
+const MAX_TELEMETRY_TEXT_LENGTH = 50_000;
+
+const BASE64_PATTERN = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+
+export type AssistantCloudRunReportToolCall = {
+  tool_name: string;
+  tool_call_id: string;
+  tool_args?: string;
+  tool_result?: string;
+  tool_source?: "mcp" | "frontend" | "backend";
+  start_ms?: number;
+  end_ms?: number;
+  sampling_calls?: SamplingCallData[];
+};
+
+/**
+ * Clamps a string to the size the runs endpoint accepts for a single span
+ * field.
+ */
+export function truncateRunTelemetryText(value: string): string {
+  if (value.length <= MAX_TELEMETRY_TEXT_LENGTH) return value;
+  return value.slice(0, MAX_TELEMETRY_TEXT_LENGTH);
+}
+
+function safeStringify(value: unknown): string | undefined {
+  if (value == null) return undefined;
+  try {
+    return truncateRunTelemetryText(JSON.stringify(value));
+  } catch {
+    return undefined;
+  }
+}
+
+function summarizeMcpResult(value: unknown): string | undefined {
+  if (value == null) return undefined;
+  try {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (Array.isArray(parsed)) {
+      const summarized = parsed.map((item) => {
+        if (item && typeof item === "object" && item.type) {
+          if (
+            (item.type === "image" || item.type === "audio") &&
+            typeof item.data === "string" &&
+            BASE64_PATTERN.test(item.data.slice(0, 200))
+          ) {
+            const sizeKB = ((item.data.length * 3) / 4 / 1024).toFixed(1);
+            return { ...item, data: `[${item.type}: ${sizeKB}KB]` };
+          }
+        }
+        return item;
+      });
+      return truncateRunTelemetryText(JSON.stringify(summarized));
+    }
+  } catch {
+    // not JSON array, fall through
+  }
+  return safeStringify(value);
+}
+
+export type RunTelemetryToolCallInit = {
+  toolName: string;
+  toolCallId: string;
+  args?: unknown;
+  /**
+   * Pre-serialized arguments, used in place of serializing `args`. Values over
+   * the span size are clamped before they are included in the report.
+   */
+  argsText?: string | undefined;
+  result?: unknown;
+  toolSource?: "mcp" | "frontend" | "backend" | undefined;
+};
+
+/**
+ * Serializes one tool call into the shape the runs endpoint accepts. An `mcp`
+ * source has its result summarized, because MCP content blocks carry inline
+ * base64 image and audio payloads that would otherwise dominate the report.
+ */
+export function createRunTelemetryToolCall(
+  init: RunTelemetryToolCallInit,
+): AssistantCloudRunReportToolCall {
+  const { toolName, toolCallId, args, argsText, result, toolSource } = init;
+  const call: AssistantCloudRunReportToolCall = {
+    tool_name: toolName,
+    tool_call_id: toolCallId,
+  };
+  const toolArgs =
+    argsText != null ? truncateRunTelemetryText(argsText) : safeStringify(args);
+  if (toolArgs !== undefined) call.tool_args = toolArgs;
+  const toolResult =
+    toolSource === "mcp" ? summarizeMcpResult(result) : safeStringify(result);
+  if (toolResult !== undefined) call.tool_result = toolResult;
+  if (toolSource) call.tool_source = toolSource;
+  return call;
+}
+
+export type RunTelemetryUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+};
+
+export type RunTelemetryUsageInit = RunTelemetryUsage & {
+  promptTokens?: number;
+  completionTokens?: number;
+};
+
+/**
+ * Resolves the token counts a provider reports under either the current or the
+ * legacy prompt/completion names. Returns undefined when no count is present,
+ * so callers can tell an empty usage object from a zeroed one.
+ */
+export function normalizeRunTelemetryUsage(
+  usage: RunTelemetryUsageInit,
+): RunTelemetryUsage | undefined {
+  const inputTokens = usage.inputTokens ?? usage.promptTokens;
+  const outputTokens = usage.outputTokens ?? usage.completionTokens;
+
+  if (
+    inputTokens == null &&
+    outputTokens == null &&
+    usage.reasoningTokens == null &&
+    usage.cachedInputTokens == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    ...(inputTokens != null ? { inputTokens } : undefined),
+    ...(outputTokens != null ? { outputTokens } : undefined),
+    ...(usage.reasoningTokens != null
+      ? { reasoningTokens: usage.reasoningTokens }
+      : undefined),
+    ...(usage.cachedInputTokens != null
+      ? { cachedInputTokens: usage.cachedInputTokens }
+      : undefined),
+  };
+}

package/src/tests/AssistantCloud.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { AssistantCloud } from "../AssistantCloud";
+import type { AssistantCloudTelemetryConfig } from "../AssistantCloudAPI";
+
+const createCloud = (
+  telemetry?: ConstructorParameters<typeof AssistantCloud>[0]["telemetry"],
+) =>
+  new AssistantCloud({
+    apiKey: "test-key",
+    userId: "user-id",
+    workspaceId: "workspace-id",
+    ...(telemetry !== undefined ? { telemetry } : {}),
+  });
+
+describe("AssistantCloud telemetry config", () => {
+  it("defaults to enabled", () => {
+    expect(createCloud().telemetry.enabled).toBe(true);
+    expect(createCloud(true).telemetry.enabled).toBe(true);
+  });
+
+  it("disables when configured off", () => {
+    expect(createCloud(false).telemetry.enabled).toBe(false);
+    expect(createCloud({ enabled: false }).telemetry.enabled).toBe(false);
+  });
+
+  it("stays enabled when the config object carries an undefined enabled", () => {
+    const beforeReport: NonNullable<
+      AssistantCloudTelemetryConfig["beforeReport"]
+    > = (report) => report;
+    // JS consumers (and TS apps without exactOptionalPropertyTypes) can pass
+    // an explicitly-undefined enabled, e.g. { enabled: cfg.enabled }.
+    const telemetry = createCloud({
+      enabled: undefined,
+      beforeReport,
+    } as unknown as AssistantCloudTelemetryConfig).telemetry;
+    expect(telemetry.enabled).toBe(true);
+    expect(telemetry.beforeReport).toBe(beforeReport);
+  });
+});

package/src/tests/AssistantCloudAPI.test.ts

@@ -169,6 +169,31 @@ describe("AssistantCloudAPI", () => {
     expect(error.status).toBe(400);
   });
 
+  it("falls back to the response text when the JSON error body has no message", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 429,
+      headers: new Headers(),
+      text: vi
+        .fn()
+        .mockResolvedValue(JSON.stringify({ error: "rate limited" })),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new AssistantCloudAPI({
+      apiKey: "test-key",
+      userId: "u-1",
+      workspaceId: "w-1",
+    });
+
+    const error = await api.makeRawRequest("/threads").catch((e) => e);
+    expect(error).toBeInstanceOf(CloudAPIError);
+    expect(error.message).toBe(
+      'Request failed with status 429, {"error":"rate limited"}',
+    );
+    expect(error.status).toBe(429);
+  });
+
   it("throws generic error with status for non-JSON error responses", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: false,