@convex-dev/agent 0.7.1 → 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/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

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

@@ -20,6 +20,7 @@ import {
   fetchContextMessages,
   filterOutOrphanedToolMessages,
   getPromptArray,
+  trimIncompleteOldestOrder,
 } from "./search.js";
 import { components, initConvexTest } from "./setup.test.js";
 import { createThread } from "../../client/threads.js";
@@ -31,13 +32,14 @@ const createMockMessageDoc = (
   role: "user" | "assistant" | "tool" | "system",
   content: any,
   order: number = 1,
+  stepOrder: number = 0,
 ): MessageDoc => ({
   _id: id,
   _creationTime: Date.now(),
   userId: "test-user",
   threadId: "test-thread",
   order,
-  stepOrder: order,
+  stepOrder,
   status: "success",
   tool: false,
   message: { role, content },
@@ -127,6 +129,27 @@ describe("search.ts", () => {
     });
   });
 
+  describe("trimIncompleteOldestOrder", () => {
+    it("keeps a window that begins at the start of an order", () => {
+      const messages = [
+        createMockMessageDoc("user", "user", "Question", 1, 0),
+        createMockMessageDoc("assistant", "assistant", "Answer", 1, 1),
+      ];
+
+      expect(trimIncompleteOldestOrder(messages)).toEqual(messages);
+    });
+
+    it("omits only the incomplete oldest order", () => {
+      const messages = [
+        createMockMessageDoc("partial", "assistant", "Partial", 1, 2),
+        createMockMessageDoc("next-user", "user", "Next question", 2, 0),
+        createMockMessageDoc("next-answer", "assistant", "Next answer", 2, 1),
+      ];
+
+      expect(trimIncompleteOldestOrder(messages)).toEqual(messages.slice(1));
+    });
+  });
+
   describe("filterOutOrphanedToolMessages", () => {
     it("should keep non-tool messages", () => {
       const messages: MessageDoc[] = [
@@ -442,6 +465,7 @@ describe("search.ts", () => {
       expect(result.length).toBe(2);
       expect(result[0]._id).toBe("1"); // Should be reversed back to asc order
       expect(result[1]._id).toBe("2");
+      expect(mockCtx.runQuery).toHaveBeenCalledTimes(1);
     });
 
     it("should skip recent messages when recentMessages is 0", async () => {
@@ -560,11 +584,13 @@ describe("search.ts", () => {
           _id: "ctx1",
           message: { role: "user", content: "Context message 1" },
           order: 1,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "ctx2",
           message: { role: "assistant", content: "Context response 1" },
           order: 2,
+          stepOrder: 0,
         } as MessageDoc,
       ];
 
@@ -590,6 +616,143 @@ describe("search.ts", () => {
       });
     });
 
+    it("should complete an order truncated by the recent messages limit", async () => {
+      const toolCallId = "call_issue_309";
+      vi.mocked(mockCtx.runQuery)
+        .mockResolvedValueOnce({
+          page: [
+            createMockMessageDoc(
+              "assistant-final",
+              "assistant",
+              [{ type: "text", text: "The result is 72." }],
+              1,
+              3,
+            ),
+            createMockMessageDoc(
+              "tool-result",
+              "tool",
+              [
+                {
+                  type: "tool-result",
+                  toolCallId,
+                  toolName: "getWeather",
+                  output: {
+                    type: "json",
+                    value: { temperature: 72 },
+                  },
+                },
+              ],
+              1,
+              2,
+            ),
+            createMockMessageDoc(
+              "assistant-tool-call",
+              "assistant",
+              [
+                {
+                  type: "tool-call",
+                  toolCallId,
+                  toolName: "getWeather",
+                  input: { city: "New York" },
+                },
+              ],
+              1,
+              1,
+            ),
+          ],
+          continueCursor: "complete-order",
+          isDone: false,
+        })
+        .mockResolvedValueOnce({
+          page: [
+            createMockMessageDoc(
+              "user",
+              "user",
+              "What is the weather?",
+              1,
+              0,
+            ),
+          ],
+          continueCursor: "done",
+          isDone: true,
+        });
+
+      const result = await fetchContextWithPrompt(
+        mockCtx,
+        components.agent,
+        {
+          ...baseArgs,
+          prompt: "What should I do next?",
+          messages: undefined,
+          promptMessageId: undefined,
+          contextOptions: { recentMessages: 3 },
+        },
+      );
+
+      expect(result.messages.map((message) => message.role)).toEqual([
+        "user",
+        "assistant",
+        "tool",
+        "assistant",
+        "user",
+      ]);
+      expect(mockCtx.runQuery).toHaveBeenNthCalledWith(2, expect.anything(), {
+        threadId: "thread123",
+        excludeToolMessages: undefined,
+        paginationOpts: { numItems: 1, cursor: "complete-order" },
+        upToAndIncludingMessageId: undefined,
+        order: "desc",
+        statuses: ["success"],
+      });
+    });
+
+    it("should omit an order when its boundary cannot be fetched", async () => {
+      vi.mocked(mockCtx.runQuery)
+        .mockResolvedValueOnce({
+          page: [
+            createMockMessageDoc(
+              "assistant-final",
+              "assistant",
+              "Partial answer",
+              1,
+              2,
+            ),
+          ],
+          continueCursor: "complete-order",
+          isDone: false,
+        })
+        .mockResolvedValueOnce({
+          page: [
+            createMockMessageDoc(
+              "assistant-step",
+              "assistant",
+              "Still partial",
+              1,
+              1,
+            ),
+          ],
+          continueCursor: "done",
+          isDone: true,
+        });
+
+      const result = await fetchContextWithPrompt(
+        mockCtx,
+        components.agent,
+        {
+          ...baseArgs,
+          prompt: "New prompt",
+          messages: undefined,
+          promptMessageId: undefined,
+          contextOptions: { recentMessages: 1 },
+        },
+      );
+
+      expect(result.messages).toEqual([
+        { role: "user", content: "New prompt" },
+      ]);
+      expect(mockCtx.runQuery).toHaveBeenCalledTimes(2);
+    });
+
     it("should handle input messages correctly", async () => {
       const inputMessages: ModelMessage[] = [
         { role: "user", content: "Input message 1" },
@@ -618,16 +781,19 @@ describe("search.ts", () => {
           _id: "msg1",
           message: { role: "user", content: "Before prompt" },
           order: 1,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "prompt-msg",
           message: { role: "user", content: "Original prompt" },
           order: 2,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "msg3",
           message: { role: "assistant", content: "After prompt" },
           order: 3,
+          stepOrder: 0,
         } as MessageDoc,
       ];
 
@@ -659,16 +825,19 @@ describe("search.ts", () => {
           _id: "msg1",
           message: { role: "user", content: "Before prompt" },
           order: 1,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "prompt-msg",
           message: { role: "user", content: "Original prompt" },
           order: 2,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "msg3",
           message: { role: "assistant", content: "After prompt" },
           order: 3,
+          stepOrder: 0,
         } as MessageDoc,
       ];
 
@@ -696,16 +865,19 @@ describe("search.ts", () => {
           _id: "ctx1",
           message: { role: "user", content: "Context 1" },
           order: 1,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "prompt-msg",
           message: { role: "user", content: "Prompt" },
           order: 3,
+          stepOrder: 0,
         } as MessageDoc,
         {
           _id: "ctx2",
           message: { role: "assistant", content: "Context 2" },
           order: 5,
+          stepOrder: 0,
         } as MessageDoc,
       ];
 
@@ -864,10 +1036,10 @@ describe("search.ts", () => {
       });
     });
 
-    it("should respect recentMessages limit", async () => {
+    it("should extend recentMessages to complete an order", async () => {
       const threadId = await createTestThread("user999");
 
-      // Create 5 messages but only fetch the most recent 2
+      // Start with a two-message window that splits the previous order.
       await createTestMessages(threadId, "user999", [
         { role: "user", content: "Message 1", order: 1 },
         { role: "assistant", content: "Response 1", order: 2 },
@@ -883,13 +1055,16 @@ describe("search.ts", () => {
         prompt: "New prompt",
         messages: undefined,
         promptMessageId: undefined,
-        contextOptions: { recentMessages: 2 }, // Only fetch 2 most recent
+        contextOptions: { recentMessages: 2 },
       });
 
-      expect(result.messages).toHaveLength(3); // 2 context + 1 prompt
-      expect(result.messages[0].content).toBe("Response 2"); // 4th message
-      expect(result.messages[1].content).toBe("Message 3"); // 5th message
-      expect(result.messages[2]).toEqual({
+      // The limit splits the previous order after its user message, so the
+      // context extends backward to include the whole order.
+      expect(result.messages).toHaveLength(4);
+      expect(result.messages[0].content).toBe("Message 2");
+      expect(result.messages[1].content).toBe("Response 2");
+      expect(result.messages[2].content).toBe("Message 3");
+      expect(result.messages[3]).toEqual({
         role: "user",
         content: "New prompt",
       });

package/src/vercel/client/search.ts

@@ -36,10 +36,24 @@ import {
 } from "../mapping.js";
 
 const DEFAULT_VECTOR_SCORE_THRESHOLD = 0.0;
+// Bound the rare boundary-extension query; incomplete orders are trimmed below.
+const MAX_ORDER_COMPLETION_MESSAGES = 1_000;
 // 10k characters should be more than enough for most cases, and stays under
 // the 8k token limit for some models.
 const MAX_EMBEDDING_TEXT_LENGTH = 10_000;
 
+/**
+ * Omit the oldest order when a descending pagination window split it.
+ * Expects the messages to be sorted in ascending order.
+ */
+export function trimIncompleteOldestOrder(docs: MessageDoc[]) {
+  const oldest = docs[0];
+  if (!oldest || oldest.stepOrder === 0) {
+    return docs;
+  }
+  return docs.filter((doc) => doc.order !== oldest.order);
+}
+
 export type GetEmbedding = (text: string) => Promise<
   | {
       embedding: number[];
@@ -133,25 +147,45 @@ export async function fetchRecentAndSearchMessages(
   let included: Set<string> | undefined;
   let recentMessages: MessageDoc[] = [];
   let searchMessages: MessageDoc[] = [];
+  const threadId = args.threadId;
   const targetMessageId =
     args.targetMessageId ?? args.upToAndIncludingMessageId;
-  if (args.threadId && opts.recentMessages !== 0) {
-    const { page } = await ctx.runQuery(
-      component.messages.listMessagesByThreadId,
-      {
-        threadId: args.threadId,
+  if (threadId && opts.recentMessages !== 0) {
+    const fetchRecentPage = (numItems: number, cursor: string | null) =>
+      ctx.runQuery(component.messages.listMessagesByThreadId, {
+        threadId,
         excludeToolMessages: opts.excludeToolMessages,
-        paginationOpts: {
-          numItems: opts.recentMessages ?? DEFAULT_RECENT_MESSAGES,
-          cursor: null,
-        },
+        paginationOpts: { numItems, cursor },
         upToAndIncludingMessageId: targetMessageId,
         order: "desc",
         statuses: ["success"],
-      },
+      });
+    const firstPage = await fetchRecentPage(
+      opts.recentMessages ?? DEFAULT_RECENT_MESSAGES,
+      null,
     );
-    included = new Set(page.map((m) => m._id));
-    recentMessages = filterOutOrphanedToolMessages(sorted(page));
+    let page = firstPage.page;
+    const oldest = page.at(-1);
+    if (
+      oldest &&
+      oldest.stepOrder > 0 &&
+      !firstPage.isDone &&
+      firstPage.continueCursor
+    ) {
+      const completionPage = await fetchRecentPage(
+        Math.min(oldest.stepOrder, MAX_ORDER_COMPLETION_MESSAGES),
+        firstPage.continueCursor,
+      );
+      page = [
+        ...page,
+        ...completionPage.page.filter(
+          (message) => message.order === oldest.order,
+        ),
+      ];
+    }
+    const retained = trimIncompleteOldestOrder(sorted(page));
+    included = new Set(retained.map((m) => m._id));
+    recentMessages = filterOutOrphanedToolMessages(retained);
   }
   if (
     (opts.searchOptions?.textSearch || opts.searchOptions?.vectorSearch) &&