assistant-cloud 0.1.41 → 0.1.43

package/src/runTelemetry.test.ts

@@ -0,0 +1,171 @@
+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("reads the AI SDK v7 token detail objects", () => {
+    expect(
+      normalizeRunTelemetryUsage({
+        inputTokens: 12,
+        outputTokens: 7,
+        inputTokenDetails: { cacheReadTokens: 5 },
+        outputTokenDetails: { reasoningTokens: 3 },
+      }),
+    ).toEqual({
+      inputTokens: 12,
+      outputTokens: 7,
+      reasoningTokens: 3,
+      cachedInputTokens: 5,
+    });
+  });
+
+  it("prefers the top-level detail counts over the nested ones", () => {
+    expect(
+      normalizeRunTelemetryUsage({
+        reasoningTokens: 3,
+        cachedInputTokens: 5,
+        inputTokenDetails: { cacheReadTokens: 90 },
+        outputTokenDetails: { reasoningTokens: 90 },
+      }),
+    ).toEqual({ reasoningTokens: 3, cachedInputTokens: 5 });
+  });
+
+  it("returns a usage object when only the nested counts are present", () => {
+    expect(
+      normalizeRunTelemetryUsage({
+        inputTokenDetails: { cacheReadTokens: 5 },
+      }),
+    ).toEqual({ cachedInputTokens: 5 });
+  });
+
+  it("returns undefined when no count is present", () => {
+    expect(normalizeRunTelemetryUsage({})).toBeUndefined();
+    expect(
+      normalizeRunTelemetryUsage({
+        inputTokenDetails: {},
+        outputTokenDetails: {},
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/runTelemetry.ts

@@ -0,0 +1,144 @@
+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;
+  inputTokenDetails?: { cacheReadTokens?: number };
+  outputTokenDetails?: { reasoningTokens?: number };
+};
+
+/**
+ * Resolves the token counts a provider reports under any of the names the AI
+ * SDK has used: the current top-level ones, the legacy prompt/completion pair,
+ * and the v7 token detail objects. 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;
+  // AI SDK v7 moved these under token detail objects; v6 kept them top-level.
+  const reasoningTokens =
+    usage.reasoningTokens ?? usage.outputTokenDetails?.reasoningTokens;
+  const cachedInputTokens =
+    usage.cachedInputTokens ?? usage.inputTokenDetails?.cacheReadTokens;
+
+  if (
+    inputTokens == null &&
+    outputTokens == null &&
+    reasoningTokens == null &&
+    cachedInputTokens == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    ...(inputTokens != null ? { inputTokens } : undefined),
+    ...(outputTokens != null ? { outputTokens } : undefined),
+    ...(reasoningTokens != null ? { reasoningTokens } : undefined),
+    ...(cachedInputTokens != null ? { 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,