@convex-dev/agent 0.7.1 → 0.7.3

package/src/component/streams.ts

@@ -197,24 +197,29 @@ function publicStreamMessage(m: Doc<"streamingMessages">): StreamMessage {
   };
 }
 
+export async function abortStreamsAtOrder(
+  ctx: MutationCtx,
+  args: { threadId: Id<"threads">; order: number; reason: string },
+) {
+  const streams = await ctx.db
+    .query("streamingMessages")
+    .withIndex("threadId_state_order_stepOrder", (q) =>
+      q
+        .eq("threadId", args.threadId)
+        .eq("state.kind", "streaming")
+        .eq("order", args.order),
+    )
+    .take(100);
+  for (const stream of streams) {
+    await abortById(ctx, { streamId: stream._id, reason: args.reason });
+  }
+  return streams.length > 0;
+}
+
 export const abortByOrder = mutation({
   args: { threadId: v.id("threads"), order: v.number(), reason: v.string() },
   returns: v.boolean(),
-  handler: async (ctx, args) => {
-    const streams = await ctx.db
-      .query("streamingMessages")
-      .withIndex("threadId_state_order_stepOrder", (q) =>
-        q
-          .eq("threadId", args.threadId)
-          .eq("state.kind", "streaming")
-          .eq("order", args.order),
-      )
-      .take(100);
-    for (const stream of streams) {
-      await abortById(ctx, { streamId: stream._id, reason: args.reason });
-    }
-    return streams.length > 0;
-  },
+  handler: abortStreamsAtOrder,
 });
 
 export const abort = mutation({
@@ -465,8 +470,6 @@ export async function deleteStreamsPageForThreadId(
       );
   let deltaCursor = args.deltaCursor;
   const streamMessage = await mergedStream(allStreamMessages, [
-    "threadId",
-    "state.kind",
     "order",
     "stepOrder",
   ]).first();

package/src/component/threads.test.ts

@@ -458,6 +458,45 @@ describe("threads", () => {
     vi.useRealTimers();
   });
 
+  test("deleteAllForThreadIdAsync preserves its limit across continuations", async () => {
+    vi.useFakeTimers();
+
+    const t = convexTest(schema, modules);
+    const thread = await t.mutation(api.threads.createThread, {
+      userId: "boundedDeleteUser",
+      title: "Bounded Delete Thread",
+    });
+    const threadId = thread._id as Id<"threads">;
+    await t.mutation(api.messages.addMessages, {
+      threadId,
+      messages: Array.from({ length: 4 }, (_, i) => ({
+        message: { role: "user" as const, content: `Message ${i}` },
+      })),
+    });
+
+    await t.mutation(api.threads.deleteAllForThreadIdAsync, {
+      threadId,
+      limit: 1,
+    });
+
+    vi.runOnlyPendingTimers();
+    await t.finishInProgressScheduledFunctions();
+    const afterOneContinuation = await t.query(
+      api.messages.listMessagesByThreadId,
+      {
+        threadId,
+        order: "asc",
+        paginationOpts: { cursor: null, numItems: 10 },
+      },
+    );
+
+    await t.finishAllScheduledFunctions(vi.runAllTimers);
+    vi.useRealTimers();
+
+    expect(afterOneContinuation.page).toHaveLength(2);
+    expect(await t.query(api.threads.getThread, { threadId })).toBeNull();
+  });
+
   test("deleteAllForThreadIdSync handles thread with no messages", async () => {
     const t = convexTest(schema, modules);
 

package/src/component/threads.ts

@@ -207,6 +207,7 @@ export const deleteAllForThreadIdAsync = mutation({
     if (!isDone) {
       await ctx.scheduler.runAfter(0, api.threads.deleteAllForThreadIdAsync, {
         threadId: args.threadId,
+        limit: args.limit,
         cursor: messagesResult.cursor,
         messagesDone: messagesResult.isDone,
         streamsDone: streamResult.isDone,

package/src/component/vector/tables.ts

@@ -68,7 +68,7 @@ export type VectorSchema = SchemaDefinition<
 >;
 
 export const VectorDimensions = [
-  128, 256, 512, 768, 1024, 1408, 1536, 2048, 3072, 4096,
+  128, 256, 512, 768, 1024, 1408, 1536, 2048, 2560, 3072, 4096,
 ] as const;
 export function validateVectorDimension(
   dimension: number,

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/deltaFlush.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { stepCountIs } from "ai";
+import { Agent, createTool, createThread } from "../index.js";
+import {
+  actionGeneric,
+  anyApi,
+  defineSchema,
+  type ActionBuilder,
+  type ApiFromModules,
+  type DataModelFromSchemaDefinition,
+} from "convex/server";
+import { v } from "convex/values";
+import { components, initConvexTest } from "./setup.test.js";
+import { mockModel } from "./mockModel.js";
+
+const schema = defineSchema({});
+type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+const action = actionGeneric as ActionBuilder<DataModel, "public">;
+
+// The AI SDK emits tool-input-available before the tool runs. The whole point
+// of issue #221 is that a client can see it while the tool is still working,
+// so the tool itself is where the delta log has to be read.
+const partsSeenDuringTool: string[] = [];
+
+const sleepTool = createTool({
+  description: "sleep",
+  inputSchema: z.object({ seconds: z.number() }),
+  execute: async (ctx) => {
+    const readTypes = async () => {
+      const streams = await ctx.runQuery(components.agent.streams.list, {
+        threadId: ctx.threadId!,
+        statuses: ["streaming"],
+      });
+      const deltas = await ctx.runQuery(components.agent.streams.listDeltas, {
+        threadId: ctx.threadId!,
+        cursors: streams.map((s) => ({ streamId: s.streamId, cursor: 0 })),
+      });
+      return deltas.flatMap((d) => d.parts.map((p) => p.type));
+    };
+    // Wait on the condition rather than on a fixed sleep chosen to outrun the
+    // throttle: there is no margin to tune, so machine load cannot decide the
+    // outcome. Without a scheduled flush this simply never arrives.
+    const deadline = Date.now() + 2_000;
+    let types = await readTypes();
+    while (!types.includes("tool-input-available") && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      types = await readTypes();
+    }
+    partsSeenDuringTool.push(...types);
+    return { slept: 3 };
+  },
+});
+
+const agent = new Agent(components.agent, {
+  name: "slow-tool",
+  languageModel: mockModel({
+    contentSteps: [
+      [
+        {
+          type: "tool-call",
+          toolCallId: "t1",
+          toolName: "sleepTool",
+          input: JSON.stringify({ seconds: 3 }),
+        },
+      ],
+      [{ type: "text", text: "done" }],
+    ],
+  }),
+  tools: { sleepTool },
+});
+
+export const run = action({
+  args: { threadId: v.string() },
+  handler: async (ctx, { threadId }) => {
+    const r = await agent.streamText(
+      ctx,
+      { threadId },
+      { prompt: "go", stopWhen: stepCountIs(3) },
+      { saveStreamDeltas: { chunking: "word", throttleMs: 50 } },
+    );
+    await r.consumeStream();
+    return { ok: true };
+  },
+});
+
+const testApi: ApiFromModules<{ fns: { run: typeof run } }>["fns"] =
+  anyApi["deltaFlush.test"] as unknown as ApiFromModules<{
+    fns: { run: typeof run };
+  }>["fns"];
+
+describe("throttled deltas flush on time (issue #221)", () => {
+  test("the tool call is queryable while the tool is still running", async () => {
+    partsSeenDuringTool.length = 0;
+    const t = initConvexTest(schema);
+    const threadId = await t.run(async (ctx) =>
+      createThread(ctx, components.agent, { userId: "u" }),
+    );
+
+    await t.action(testApi.run, { threadId });
+    await t.finishAllScheduledFunctions(() => {});
+
+    expect(partsSeenDuringTool).toContain("tool-input-available");
+    expect(partsSeenDuringTool).not.toContain("tool-output-available");
+  });
+});

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