assistant-cloud 0.2.1 → 0.2.3

package/src/runTelemetry.ts

@@ -3,7 +3,7 @@ import type { AssistantCloudRunReport } from "./AssistantCloudRuns";
 
 const MAX_TELEMETRY_TEXT_LENGTH = 50_000;
 
-const BASE64_PATTERN = /^[A-Za-z0-9+/]{100,}={0,2}$/;
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
 
 export type AssistantCloudRunReportToolCall = {
   tool_name: string;
@@ -114,28 +114,81 @@ function safeStringify(value: unknown): string | undefined {
   }
 }
 
+const base64SizeKB = (value: string) =>
+  ((value.length * 3) / 4 / 1024).toFixed(1);
+
+// Both call sites read a field the MCP content grammar already defines as
+// base64, so the test only has to recognise the encoding's own shape: its
+// alphabet, and a length that is a multiple of four. A size floor would leave
+// a short payload — `aGk=` is a whole image in this repo's own fixtures —
+// serialized raw.
+const isInlineBase64 = (value: unknown): value is string => {
+  if (typeof value !== "string") return false;
+  const head = value.slice(0, 200);
+  return head.length > 0 && head.length % 4 === 0 && BASE64_PATTERN.test(head);
+};
+
+function summarizeMcpContentBlock(item: unknown): unknown {
+  if (!item || typeof item !== "object") return item;
+  const block = item as {
+    type?: unknown;
+    data?: unknown;
+    resource?: unknown;
+  };
+  if (
+    (block.type === "image" || block.type === "audio") &&
+    isInlineBase64(block.data)
+  ) {
+    return {
+      ...block,
+      data: `[${String(block.type)}: ${base64SizeKB(block.data)}KB]`,
+    };
+  }
+  // An EmbeddedResource is the third inline carrier: a binary resource arrives
+  // as base64 under `resource.blob` rather than as a top-level `data` field.
+  if (
+    block.type === "resource" &&
+    block.resource &&
+    typeof block.resource === "object"
+  ) {
+    const resource = block.resource as { blob?: unknown };
+    if (isInlineBase64(resource.blob)) {
+      return {
+        ...block,
+        resource: {
+          ...resource,
+          blob: `[resource: ${base64SizeKB(resource.blob)}KB]`,
+        },
+      };
+    }
+  }
+  return item;
+}
+
 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));
+      return truncateRunTelemetryText(
+        JSON.stringify(parsed.map(summarizeMcpContentBlock)),
+      );
+    }
+    // `callTool` resolves to a CallToolResult, so the blocks carrying base64
+    // arrive under `content` rather than as the result itself.
+    if (typeof parsed === "object") {
+      const content = (parsed as { content?: unknown }).content;
+      if (Array.isArray(content)) {
+        return truncateRunTelemetryText(
+          JSON.stringify({
+            ...(parsed as Record<string, unknown>),
+            content: content.map(summarizeMcpContentBlock),
+          }),
+        );
+      }
     }
   } catch {
-    // not JSON array, fall through
+    // not a shape with summarizable content, fall through
   }
   return safeStringify(value);
 }
@@ -223,6 +276,7 @@ export type RunReportStepInit = {
   startMs?: number | undefined;
   endMs?: number | undefined;
   finishReason?: string | undefined;
+  input?: string | undefined;
 };
 
 /**
@@ -245,11 +299,12 @@ export type RunMessageTelemetry = {
 export type RunReportInit = {
   threadId: string;
   status: AssistantCloudRunReport["status"];
-  outcome?: RunReportOutcome | undefined;
+  outcome?: AssistantCloudRunReport["outcome_type"] | undefined;
   errorCode?: string | undefined;
   error?: string | undefined;
   messageId?: string | undefined;
   traceId?: string | undefined;
+  rootSpanId?: string | undefined;
   modelId?: string | undefined;
   provider?: string | undefined;
   usage?: RunTelemetryUsageInit | undefined;
@@ -258,7 +313,17 @@ export type RunReportInit = {
   toolCalls?: AssistantCloudRunReportToolCall[] | undefined;
   durationMs?: number | undefined;
   firstTokenMs?: number | undefined;
+  costUsd?: number | undefined;
+  costDetails?:
+    | {
+        input?: number | undefined;
+        inputCachedTokens?: number | undefined;
+        output?: number | undefined;
+        total?: number | undefined;
+      }
+    | undefined;
   outputText?: string | undefined;
+  attributes?: Record<string, unknown> | undefined;
   metadata?: Record<string, unknown> | undefined;
   telemetry?: {
     environment?: string | undefined;
@@ -308,6 +373,9 @@ function createRunReportStep(
   if (init.finishReason !== undefined) {
     step.finish_reason = init.finishReason.slice(0, 32);
   }
+  if (init.input !== undefined) {
+    step.input = truncateRunTelemetryText(init.input);
+  }
   return step;
 }
 
@@ -334,6 +402,34 @@ function normalizeRunReportMilliseconds(
   return Math.max(0, Math.round(value));
 }
 
+function normalizeRunReportCost(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  return value;
+}
+
+function assignCostDetails(
+  report: AssistantCloudRunReport,
+  costDetails: RunReportInit["costDetails"],
+): void {
+  if (!costDetails) return;
+  const normalized: NonNullable<AssistantCloudRunReport["cost_details"]> = {};
+  const input = normalizeRunReportCost(costDetails.input);
+  if (input !== undefined) normalized.input = input;
+  const inputCachedTokens = normalizeRunReportCost(
+    costDetails.inputCachedTokens,
+  );
+  if (inputCachedTokens !== undefined) {
+    normalized.input_cached_tokens = inputCachedTokens;
+  }
+  const output = normalizeRunReportCost(costDetails.output);
+  if (output !== undefined) normalized.output = output;
+  const total = normalizeRunReportCost(costDetails.total);
+  if (total !== undefined) normalized.total = total;
+  if (Object.keys(normalized).length > 0) report.cost_details = normalized;
+}
+
 export function createRunReport(init: RunReportInit): AssistantCloudRunReport {
   const report: AssistantCloudRunReport = {
     thread_id: init.threadId,
@@ -341,6 +437,10 @@ export function createRunReport(init: RunReportInit): AssistantCloudRunReport {
   };
   const traceId = init.traceId?.toLowerCase();
   if (traceId && /^[0-9a-f]{32}$/.test(traceId)) report.trace_id = traceId;
+  const rootSpanId = init.rootSpanId?.toLowerCase();
+  if (rootSpanId && /^[0-9a-f]{16}$/.test(rootSpanId)) {
+    report.root_span_id = rootSpanId;
+  }
   if (init.outcome !== undefined) report.outcome_type = init.outcome;
   if (init.errorCode !== undefined) report.error_code = init.errorCode;
   if (init.error !== undefined) report.error = init.error;
@@ -362,9 +462,13 @@ export function createRunReport(init: RunReportInit): AssistantCloudRunReport {
   if (durationMs !== undefined) report.duration_ms = durationMs;
   const firstTokenMs = normalizeRunReportMilliseconds(init.firstTokenMs);
   if (firstTokenMs !== undefined) report.first_token_ms = firstTokenMs;
+  const costUsd = normalizeRunReportCost(init.costUsd);
+  if (costUsd !== undefined) report.cost_usd = costUsd;
+  assignCostDetails(report, init.costDetails);
   if (init.outputText !== undefined) {
     report.output_text = truncateRunTelemetryText(init.outputText);
   }
+  if (init.attributes !== undefined) report.attributes = init.attributes;
   if (init.metadata !== undefined) report.metadata = init.metadata;
   if (init.telemetry?.environment !== undefined) {
     report.environment = init.telemetry.environment;

package/src/tests/AssistantCloud.test.ts

@@ -14,6 +14,7 @@ const createCloud = (
 
 describe("AssistantCloud telemetry config", () => {
   afterEach(() => {
+    vi.useRealTimers();
     vi.unstubAllGlobals();
   });
 
@@ -34,6 +35,27 @@ describe("AssistantCloud telemetry config", () => {
     });
   });
 
+  it.each(["enabled", "events"] as const)(
+    "does not resume pending events after telemetry %s is disabled",
+    async (property) => {
+      vi.useFakeTimers();
+      const fetchMock = vi.fn().mockRejectedValueOnce(new Error("offline"));
+      vi.stubGlobal("fetch", fetchMock);
+      const cloud = createCloud();
+
+      for (let index = 0; index < 20; index++) {
+        cloud.events.track({ kind: "message_sent" });
+      }
+      await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+
+      cloud.telemetry[property] = false;
+      cloud.telemetry[property] = true;
+      await vi.runAllTimersAsync();
+
+      expect(fetchMock).toHaveBeenCalledOnce();
+    },
+  );
+
   it("stays enabled when the config object carries an undefined enabled", () => {
     const beforeReport: NonNullable<
       AssistantCloudTelemetryConfig["beforeReport"]

package/src/tests/AssistantCloudRuns.test.ts

@@ -90,6 +90,34 @@ describe("AssistantCloudRuns", () => {
     );
     expect(cancel).toHaveBeenCalledOnce();
   });
+
+  it("pins the UI message stream protocol in assistant options", () => {
+    const { protocol } =
+      createCloud().runs.__internal_getAssistantOptions("assistant-id");
+
+    expect(protocol).toBe("ui-message-stream");
+  });
+
+  it("uses the requested thread ID in assistant options", async () => {
+    const { body } =
+      createCloud().runs.__internal_getAssistantOptions("assistant-id");
+
+    await expect(body({ threadId: "remote-thread" })).resolves.toEqual({
+      assistant_id: "assistant-id",
+      response_format: "vercel-ai-data-stream/v1",
+      thread_id: "remote-thread",
+    });
+  });
+
+  it("rejects assistant options without a thread ID", async () => {
+    const { body } =
+      createCloud().runs.__internal_getAssistantOptions("assistant-id");
+
+    await expect(body({})).rejects.toThrow(
+      "Assistant Cloud runs need a thread",
+    );
+    await expect(body()).rejects.toThrow("Assistant Cloud runs need a thread");
+  });
 });
 
 const createCloudRuns = () => {

package/src/tests/CloudEngagementReporter.test.ts

@@ -47,6 +47,24 @@ describe("CloudEngagementReporter", () => {
     });
   });
 
+  it("drops an event its resolver declines", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud, (threadId) =>
+      threadId === "known" ? { thread_id: "remote-known" } : undefined,
+    );
+
+    reporter.messageSent("unknown", { chars: 3, attachments: 0 });
+    reporter.messageSent("known", { chars: 5, attachments: 0 });
+    await flush();
+
+    expect(track).toHaveBeenCalledOnce();
+    expect(track).toHaveBeenCalledWith({
+      kind: "message_sent",
+      thread_id: "remote-known",
+      props: { chars: 5, attachments: 0 },
+    });
+  });
+
   it("reports tool approval decisions with their resolved message IDs", async () => {
     const { cloud, track } = createCloud();
     const reporter = new CloudEngagementReporter(
@@ -113,6 +131,33 @@ describe("CloudEngagementReporter", () => {
     );
   });
 
+  it("measures the next send from a stopped run, not the last completed one", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+
+    vi.setSystemTime(new Date("2023-01-01T00:00:00.000Z"));
+    reporter.runStarted("t1");
+    vi.setSystemTime(new Date("2023-01-01T00:01:40.000Z"));
+    reporter.runEnded("t1");
+
+    // a second run the user stops rather than lets finish
+    vi.setSystemTime(new Date("2023-01-01T00:03:20.000Z"));
+    reporter.runStarted("t1");
+    vi.setSystemTime(new Date("2023-01-01T00:05:00.000Z"));
+    reporter.runStopped("t1");
+
+    vi.setSystemTime(new Date("2023-01-01T00:05:10.000Z"));
+    reporter.messageSent("t1", { chars: 3, attachments: 0 });
+    await flush();
+
+    // a stopped run is still a run that ended, so the idle gap is the 10s
+    // since the stop, not the 210s since the last completed run
+    const sent = track.mock.calls
+      .map(([event]) => event as { kind: string; value?: number })
+      .find((event) => event.kind === "message_sent");
+    expect(sent?.value).toBe(10_000);
+  });
+
   it("shows one error per run and one suggestion list per thread", async () => {
     const { cloud, track } = createCloud();
     const reporter = new CloudEngagementReporter(cloud);

package/src/tests/CloudRunReporter.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AssistantCloud } from "../AssistantCloud";
+import { CloudAPIError } from "../AssistantCloudAPI";
 import { CloudRunReporter } from "../CloudRunReporter";
+import { CloudResponseError } from "../cloudResponse";
 
 const createCloud = (telemetry: AssistantCloud["telemetry"]) => {
   const report = vi.fn().mockResolvedValue({ run_id: "run_1" });
@@ -19,7 +21,13 @@ describe("CloudRunReporter", () => {
   });
 
   it("stamps the cloud's environment, release and tags and applies beforeReport last", async () => {
-    const beforeReport = vi.fn((report) => ({ ...report, model_id: "gpt" }));
+    const beforeReport = vi.fn((report) => ({
+      ...report,
+      model_id: "gpt",
+      cost_usd: 0.012,
+      attributes: { tenant: "acme" },
+      root_span_id: "0011223344556677",
+    }));
     const { cloud, report } = createCloud({
       enabled: true,
       environment: "production",
@@ -41,7 +49,13 @@ describe("CloudRunReporter", () => {
       }),
     );
     expect(report).toHaveBeenCalledWith(
-      expect.objectContaining({ thread_id: "thread_1", model_id: "gpt" }),
+      expect.objectContaining({
+        thread_id: "thread_1",
+        model_id: "gpt",
+        cost_usd: 0.012,
+        attributes: { tenant: "acme" },
+        root_span_id: "0011223344556677",
+      }),
     );
   });
 
@@ -69,6 +83,39 @@ describe("CloudRunReporter", () => {
     expect(report).toHaveBeenCalledTimes(3);
   });
 
+  it("allows a keyed run to retry after rate limiting", async () => {
+    const { cloud, report } = createCloud({ enabled: true });
+    report.mockRejectedValueOnce(new CloudAPIError("rate limited", 429));
+    const reporter = new CloudRunReporter(cloud);
+
+    await reporter.report({ threadId: "t", status: "completed" }, "t:m");
+    await reporter.report({ threadId: "t", status: "completed" }, "t:m");
+    await reporter.report({ threadId: "t", status: "completed" }, "t:m");
+
+    expect(report).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    ["a transport failure", new Error("offline")],
+    ["a request timeout", new CloudAPIError("timeout", 408)],
+    ["a server error", new CloudAPIError("unavailable", 503)],
+    [
+      "a successful response with an invalid body",
+      new CloudResponseError("invalid response"),
+    ],
+    ["a successful response with invalid JSON", new SyntaxError("invalid")],
+    ["a permanent client error", new CloudAPIError("invalid report", 400)],
+  ])("does not retry after %s", async (_name, error) => {
+    const { cloud, report } = createCloud({ enabled: true });
+    report.mockRejectedValueOnce(error);
+    const reporter = new CloudRunReporter(cloud);
+
+    await reporter.report({ threadId: "t", status: "completed" }, "t:m");
+    await reporter.report({ threadId: "t", status: "completed" }, "t:m");
+
+    expect(report).toHaveBeenCalledOnce();
+  });
+
   it("swallows a failed send and reads the cloud through a getter", async () => {
     const { cloud } = createCloud({ enabled: true });
     (cloud.runs.report as ReturnType<typeof vi.fn>).mockRejectedValue(

package/dist/tests/setup.d.ts

@@ -1 +0,0 @@
-export {}

package/dist/tests/setup.js

@@ -1,7 +0,0 @@
-import { vi } from "vitest";
-//#region src/tests/setup.ts
-vi.useFakeTimers({ toFake: ["Date"] });
-vi.setSystemTime(/* @__PURE__ */ new Date("2023-01-01T00:00:00.000Z"));
-//#endregion
-
-//# sourceMappingURL=setup.js.map

package/dist/tests/setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup.js","names":[],"sources":["../../src/tests/setup.ts"],"sourcesContent":["import { vi } from \"vitest\";\n\nvi.useFakeTimers({ toFake: [\"Date\"] });\nvi.setSystemTime(new Date(\"2023-01-01T00:00:00.000Z\"));\n"],"mappings":";;AAEA,GAAG,cAAc,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;AACrC,GAAG,8BAAc,IAAI,KAAK,0BAA0B,CAAC"}