@convex-dev/agent 0.7.0 → 0.7.2

package/src/errors.test.ts

@@ -0,0 +1,76 @@
+import { APICallError } from "@ai-sdk/provider";
+import { describe, expect, test } from "vitest";
+import { errorToString } from "./errors.js";
+
+describe("errorToString", () => {
+  test("preserves provider error classifications", () => {
+    const details = {
+      error: {
+        code: "invalid_prompt",
+        message: "Invalid prompt: flagged by policy",
+      },
+    };
+    const apiError = new APICallError({
+      message: "Invalid prompt: flagged by policy",
+      url: "https://api.example.test",
+      requestBodyValues: {},
+      statusCode: 400,
+      data: details,
+    });
+
+    expect(errorToString(details)).toBe(
+      "invalid_prompt: Invalid prompt: flagged by policy",
+    );
+    expect(errorToString(apiError)).toBe(
+      "invalid_prompt: Invalid prompt: flagged by policy",
+    );
+    expect(errorToString(new Error())).toBe("Error");
+    expect(errorToString(new TypeError())).toBe("TypeError");
+    const systemError = Object.assign(new Error("socket hang up"), {
+      code: "ECONNRESET",
+    });
+    expect(errorToString(systemError)).toBe("socket hang up");
+    const codeOnly = Object.assign(new Error("Request failed"), {
+      data: { code: "rate_limit" },
+    });
+    expect(errorToString(codeOnly)).toBe("rate_limit: Request failed");
+  });
+
+  test("serializes objects without mistaking shared values for cycles", () => {
+    const shared = { detail: "provider disconnected" };
+    const circular: Record<string, unknown> = { shared };
+    circular.self = circular;
+
+    expect(errorToString({ x: shared, y: shared })).toBe(
+      '{"x":{"detail":"provider disconnected"},"y":{"detail":"provider disconnected"}}',
+    );
+    expect(errorToString(circular)).toBe(
+      '{"shared":{"detail":"provider disconnected"},"self":"[Circular]"}',
+    );
+  });
+
+  test("bounds stored error text without splitting surrogate pairs", () => {
+    const serialized = errorToString(`${"x".repeat(1022)}😀tail`);
+
+    expect(serialized.length).toBeLessThanOrEqual(1024);
+    expect(serialized.endsWith("x…")).toBe(true);
+  });
+
+  test("does not throw when Error properties are hostile accessors", () => {
+    const error = new Error();
+    Object.defineProperties(error, {
+      message: {
+        get() {
+          throw new Error("message getter failed");
+        },
+      },
+      name: {
+        get() {
+          throw new Error("name getter failed");
+        },
+      },
+    });
+
+    expect(errorToString(error)).toBe("Unknown error");
+  });
+});

package/src/errors.ts

@@ -0,0 +1,113 @@
+const MAX_ERROR_LENGTH = 1024;
+
+export function errorToString(error: unknown): string {
+  return truncateError(describeError(error));
+}
+
+function describeError(error: unknown): string {
+  if (typeof error === "string") return error;
+  if (error instanceof Error) {
+    const message = property(error, "message");
+    if (typeof message !== "string" || message.length === 0) {
+      const name = property(error, "name");
+      return typeof name === "string" && name.length > 0
+        ? name
+        : safeString(error);
+    }
+    const nested = errorDetails(
+      property(error, "error") ?? property(error, "data"),
+    );
+    return (
+      formatDetails({
+        message: nested.message ?? message,
+        code: nested.code,
+      }) ?? message
+    );
+  }
+
+  const details = formatDetails(errorDetails(error));
+  if (details) return details;
+
+  if (error && typeof error === "object") {
+    try {
+      const ancestors: object[] = [];
+      const serialized = JSON.stringify(error, function (_key, value: unknown) {
+        if (typeof value === "bigint") return value.toString();
+        if (!value || typeof value !== "object") return value;
+        while (ancestors.length > 0 && ancestors.at(-1) !== this) {
+          ancestors.pop();
+        }
+        if (ancestors.includes(value)) return "[Circular]";
+        ancestors.push(value);
+        return value;
+      });
+      if (serialized) return serialized;
+    } catch {
+      return safeString(error);
+    }
+  }
+
+  return safeString(error);
+}
+
+function safeString(error: unknown): string {
+  try {
+    return String(error);
+  } catch {
+    return "Unknown error";
+  }
+}
+
+function errorDetails(error: unknown): { message?: string; code?: string } {
+  let current = error;
+  let message: string | undefined;
+  let code: string | undefined;
+  for (let depth = 0; depth < 3; depth++) {
+    if (typeof current === "string") {
+      message ??= current;
+      break;
+    }
+    if (!current || typeof current !== "object") break;
+
+    const currentMessage = property(current, "message");
+    if (typeof currentMessage === "string" && currentMessage.length > 0) {
+      message ??= currentMessage;
+    }
+    const currentCode = property(current, "code");
+    if (typeof currentCode === "string" || typeof currentCode === "number") {
+      code ??= String(currentCode);
+    }
+    if (message && code) break;
+    current = property(current, "error") ?? property(current, "data");
+  }
+  return { message, code };
+}
+
+function property(value: object, key: string): unknown {
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function formatDetails({
+  message,
+  code,
+}: {
+  message?: string;
+  code?: string;
+}): string | undefined {
+  if (message && code) {
+    return message.startsWith(`${code}:`) ? message : `${code}: ${message}`;
+  }
+  return message ?? code;
+}
+
+function truncateError(error: string): string {
+  if (error.length <= MAX_ERROR_LENGTH) return error;
+  let truncated = error.slice(0, MAX_ERROR_LENGTH - 1);
+  const last = truncated.charCodeAt(truncated.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) truncated = truncated.slice(0, -1);
+  return `${truncated}…`;
+}

package/src/streaming/materializePersistedUIMessageChunks.test.ts

@@ -51,6 +51,39 @@ describe("projectPersistedUIMessageChunks", () => {
     expect(validate(vMessageWithMetadataInternal, actual[1])).toBe(true);
   });
 
+  it("attaches materialized canonical tool-result files during recovery", () => {
+    const url = "https://files.example/tool-result";
+    const actual = projectPersistedUIMessageChunks(
+      stream,
+      [
+        {
+          type: "tool-input-available",
+          toolCallId: "call-1",
+          toolName: "render",
+          input: {},
+        },
+        {
+          type: "tool-output-available",
+          toolCallId: "call-1",
+          output: {
+            type: "content",
+            value: [
+              {
+                type: "file",
+                data: { type: "url", url },
+                mediaType: "application/octet-stream",
+              },
+            ],
+          },
+        },
+      ],
+      { status: "success" },
+      [{ url, fileId: "file-1" }],
+    );
+
+    expect(actual[1]).toMatchObject({ fileIds: ["file-1"] });
+  });
+
   it("keeps persisted sources on the step that produced them", () => {
     const chunks = [
       { type: "start-step" },

package/src/streaming/materializePersistedUIMessageChunks.ts

@@ -33,6 +33,7 @@ export function projectPersistedUIMessageChunks(
   stream: StreamMessage,
   chunks: readonly unknown[],
   metadata: PersistedStreamMetadata,
+  fileRefs: readonly { url: string; fileId: string }[] = [],
 ): MessageWithMetadataInternal[] {
   if (stream.format !== "UIMessageChunk") {
     throw new Error(
@@ -60,6 +61,7 @@ export function projectPersistedUIMessageChunks(
     reduced.state.parts,
     stream,
     metadata,
+    fileRefs,
   );
 }
 
@@ -91,6 +93,7 @@ export function projectPersistedUIMessageChunkParts(
   parts: PersistedUIMessagePart[],
   stream: StreamMessage,
   metadata: PersistedStreamMetadata,
+  fileRefs: readonly { url: string; fileId: string }[] = [],
 ): MessageWithMetadataInternal[] {
   const blocks: PersistedUIMessagePart[][] = [];
   let block: PersistedUIMessagePart[] = [];
@@ -267,6 +270,7 @@ export function projectPersistedUIMessageChunkParts(
     const hasToolCall =
       message.role === "tool" ||
       content.some((part) => part.type === "tool-call");
+    const fileIds = referencedFileIds(message, fileRefs);
     return {
       message,
       status: metadata.status,
@@ -284,6 +288,9 @@ export function projectPersistedUIMessageChunkParts(
         )
         .map((part) => part.text)
         .join(" "),
+      ...(fileIds.length > 0
+        ? { fileIds: fileIds as MessageWithMetadataInternal["fileIds"] }
+        : {}),
       ...(metadata.error !== undefined ? { error: metadata.error } : {}),
     } satisfies MessageWithMetadataInternal;
   });
@@ -316,6 +323,36 @@ function projectSources(parts: PersistedUIMessagePart[]) {
     );
 }
 
+function referencedFileIds(
+  message: Message,
+  fileRefs: readonly { url: string; fileId: string }[],
+) {
+  if (typeof message.content === "string") return [];
+  const urls = new Set<string>();
+  for (const part of message.content) {
+    if (part.type === "file") {
+      if (typeof part.data === "string") urls.add(part.data);
+    } else if (part.type === "reasoning-file") {
+      if ("url" in part && part.url) urls.add(part.url);
+    } else if (part.type === "tool-result" && part.output?.type === "content") {
+      for (const outputPart of part.output.value) {
+        if (
+          outputPart.type === "file" &&
+          outputPart.data.type === "url" &&
+          typeof outputPart.data.url === "string"
+        ) {
+          urls.add(outputPart.data.url);
+        }
+      }
+    }
+  }
+  return [
+    ...new Set(
+      fileRefs.filter((ref) => urls.has(ref.url)).map((ref) => ref.fileId),
+    ),
+  ];
+}
+
 function toolResult(
   part: PersistedToolPart,
   mode: "normal" | "error-text" | "error-json" | "execution-denied",

package/src/vercel/UIMessages.ts

@@ -344,7 +344,7 @@ function createUserUIMessage<
 
   const parts: UIMessage<METADATA, DATA_PARTS, TOOLS>["parts"] = [];
   if (text && !nonStringContent.length) {
-    parts.push({ type: "text", text });
+    parts.push({ type: "text", text, ...partCommon });
   }
   for (const contentPart of nonStringContent) {
     switch (contentPart.type) {

package/src/vercel/client/files.test.ts

@@ -0,0 +1,56 @@
+/// <reference types="vite/client" />
+
+import { describe, expect, test } from "vitest";
+import { storeFile } from "./files.js";
+
+describe("storeFile", () => {
+  test("throws a clear error when a reused file is missing from storage", async () => {
+    const ctx = {
+      runAction: async () => null,
+      runMutation: async () => ({
+        fileId: "existing-file",
+        storageId: "existing-storage",
+      }),
+      storage: {
+        getUrl: async () => null,
+      },
+    } as unknown as Parameters<typeof storeFile>[0];
+    const component = {
+      files: { useExistingFile: {}, addFile: {} },
+    } as unknown as Parameters<typeof storeFile>[1];
+
+    await expect(storeFile(ctx, component, new Blob(["x"]))).rejects.toThrow(
+      "File not found in storage: existing-storage",
+    );
+  });
+
+  test("cleans its losing blob before an existing URL read fails", async () => {
+    const deleted: string[] = [];
+    let mutationCount = 0;
+    const ctx = {
+      runAction: async () => null,
+      runMutation: async () => {
+        mutationCount++;
+        return mutationCount === 1
+          ? null
+          : { fileId: "existing-file", storageId: "existing-storage" };
+      },
+      storage: {
+        store: async () => "new-storage",
+        getMetadata: async () => null,
+        getUrl: async () => null,
+        delete: async (storageId: string) => {
+          deleted.push(storageId);
+        },
+      },
+    } as unknown as Parameters<typeof storeFile>[0];
+    const component = {
+      files: { useExistingFile: {}, addFile: {} },
+    } as unknown as Parameters<typeof storeFile>[1];
+
+    await expect(storeFile(ctx, component, new Blob(["x"]))).rejects.toThrow(
+      "File not found in storage: existing-storage",
+    );
+    expect(deleted).toEqual(["new-storage"]);
+  });
+});

package/src/vercel/client/files.ts

@@ -67,9 +67,13 @@ export async function storeFile(
   const reused = await ctx.runMutation(component.files.useExistingFile, {
     hash,
     filename,
+    mediaType: blob.type || undefined,
   });
   if (reused) {
-    const url = (await ctx.storage.getUrl(reused.storageId))!;
+    const url = await ctx.storage.getUrl(reused.storageId);
+    if (!url) {
+      throw new Error(`File not found in storage: ${reused.storageId}`);
+    }
     return {
       ...getParts(url, blob.type, filename),
       file: {
@@ -82,35 +86,56 @@ export async function storeFile(
     };
   }
   const newStorageId = await ctx.storage.store(blob);
-  if (sha256) {
-    const metadata = await ctx.storage.getMetadata(newStorageId);
-    if (metadata?.sha256 !== sha256) {
-      throw new Error("Hash mismatch: " + metadata?.sha256 + " != " + sha256);
-    }
-  }
-  const { fileId, storageId } = await ctx.runMutation(component.files.addFile, {
-    storageId: newStorageId,
-    hash,
-    filename,
-    mediaType: blob.type,
-  });
-  const url = (await ctx.storage.getUrl(storageId as Id<"_storage">))!;
-  if (storageId !== newStorageId) {
-    // We're re-using another file's storageId
-    // Because we try to reuse the file above, this should be very very rare
-    // and only in the case of racing to check then store the file.
+  let newStorageRegistered = false;
+  let cleanupAttempted = false;
+  const cleanupNewStorage = async () => {
+    if (cleanupAttempted) return;
+    cleanupAttempted = true;
     await ctx.storage.delete(newStorageId);
-  }
-  return {
-    ...getParts(url, blob.type, filename),
-    file: {
-      url,
-      fileId,
-      storageId: storageId as Id<"_storage">,
-      hash,
-      filename,
-    },
   };
+  try {
+    if (sha256) {
+      const metadata = await ctx.storage.getMetadata(newStorageId);
+      if (metadata?.sha256 !== sha256) {
+        throw new Error("Hash mismatch: " + metadata?.sha256 + " != " + sha256);
+      }
+    }
+    const { fileId, storageId } = await ctx.runMutation(
+      component.files.addFile,
+      {
+        storageId: newStorageId,
+        hash,
+        filename,
+        mediaType: blob.type,
+      },
+    );
+    newStorageRegistered = storageId === newStorageId;
+    // A competing request can win after useExistingFile but before addFile.
+    // Delete our losing blob before the existing file's URL is read, so a
+    // failed getUrl cannot leave the raw object orphaned.
+    if (!newStorageRegistered) {
+      await cleanupNewStorage();
+    }
+    const url = await ctx.storage.getUrl(storageId as Id<"_storage">);
+    if (!url) {
+      throw new Error(`File not found in storage: ${storageId}`);
+    }
+    return {
+      ...getParts(url, blob.type, filename),
+      file: {
+        url,
+        fileId,
+        storageId: storageId as Id<"_storage">,
+        hash,
+        filename,
+      },
+    };
+  } catch (error) {
+    if (!newStorageRegistered && !cleanupAttempted) {
+      await cleanupNewStorage().catch(() => {});
+    }
+    throw error;
+  }
 }
 
 /**

package/src/vercel/client/index.test.ts

@@ -4,6 +4,8 @@ import {
   createThread,
   createTool,
   filterOutOrphanedToolMessages,
+  saveMessage,
+  toUIMessages,
   type MessageDoc,
 } from "../index.js";
 import type { DataModelFromSchemaDefinition } from "convex/server";
@@ -458,6 +460,51 @@ describe("Agent message operations", () => {
     expect(messages.length).toBe(2);
     expect(messages[1]._id).toBeDefined();
   });
+
+  test("saveMessage can place a standalone assistant message on a new order", async () => {
+    const t = initConvexTest(schema);
+    const threadId = await t.run(async (ctx) =>
+      createThread(ctx, components.agent, { userId: "operator-test" }),
+    );
+    const { message: agentReply } = await t.run(async (ctx) =>
+      agent.saveMessage(ctx, {
+        threadId,
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool-call",
+              toolCallId: "handoff-1",
+              toolName: "handoff",
+              input: {},
+            },
+          ],
+        },
+      }),
+    );
+    const { message: operatorReply } = await t.run(async (ctx) =>
+      saveMessage(ctx, components.agent, {
+        threadId,
+        order: "next",
+        agentName: "human:Alex",
+        message: { role: "assistant", content: "Operator reply" },
+      }),
+    );
+    const uiMessages = toUIMessages([agentReply, operatorReply]);
+
+    expect(agentReply).toMatchObject({ order: 0, stepOrder: 0 });
+    expect(operatorReply).toMatchObject({
+      order: 1,
+      stepOrder: 0,
+      agentName: "human:Alex",
+    });
+    expect(uiMessages).toHaveLength(2);
+    expect(uiMessages[1]).toMatchObject({
+      order: 1,
+      agentName: "human:Alex",
+      text: "Operator reply",
+    });
+  });
 });
 
 describe("Agent text/object generation", () => {

package/src/vercel/client/messages.ts

@@ -11,6 +11,7 @@ import { toUIMessages, type UIMessage } from "../UIMessages.js";
 import {
   listMessages,
   saveMessages as saveCanonicalMessages,
+  type MessageOrder,
 } from "../../client/messages.js";
 import type {
   AgentComponent,
@@ -36,6 +37,15 @@ export async function listUIMessages(
 export type SaveMessagesArgs = {
   threadId: string;
   userId?: string | null;
+  /**
+   * Save the first message at this order. Pass `"next"` to allocate a new
+   * order after the current latest message. If the numeric order already
+   * contains messages, the message is appended at the next stepOrder.
+   * Numeric orders must be non-negative safe integers less than
+   * Number.MAX_SAFE_INTEGER.
+   * Cannot be combined with promptMessageId or pendingMessageId.
+   */
+  order?: MessageOrder;
   /**
    * The message that these messages are in response to. They will be
    * the same "order" as this message, at increasing stepOrder(s).
@@ -86,6 +96,7 @@ export async function saveMessages(
     userId: args.userId ?? undefined,
     agentName: args.agentName,
     promptMessageId: args.promptMessageId,
+    order: args.order,
     pendingMessageId: args.pendingMessageId,
     embeddings: args.embeddings,
     messages: serialized.map(({ message }) => message),
@@ -105,6 +116,14 @@ export async function saveMessages(
 export type SaveMessageArgs = {
   threadId: string;
   userId?: string | null;
+  /**
+   * Save the message at this order. Pass `"next"` to allocate a new order
+   * after the current latest message. If the numeric order already contains
+   * messages, the message is appended at the next stepOrder. Numeric orders
+   * must be non-negative safe integers less than Number.MAX_SAFE_INTEGER.
+   * Cannot be combined with promptMessageId or pendingMessageId.
+   */
+  order?: MessageOrder;
   /**
    * The message that these messages are in response to. They will be
    * the same "order" as this message, at increasing stepOrder(s).
@@ -169,6 +188,7 @@ export async function saveMessage(
     userId: args.userId ?? undefined,
     agentName: args.agentName,
     promptMessageId: args.promptMessageId,
+    order: args.order,
     pendingMessageId: args.pendingMessageId,
     messages:
       args.prompt !== undefined