@convex-dev/agent 0.7.1 → 0.7.2

package/src/vercel/client/start.ts

@@ -386,6 +386,7 @@ export async function startGeneration<
           threadId,
           agentName: opts.agentName,
           promptMessageId,
+          abandonIfPromptMissing: true,
           pendingMessageId,
           messages: serialized.messages,
           embeddings,

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

@@ -11,13 +11,27 @@ import {
 import { v } from "convex/values";
 import { components, initConvexTest } from "./setup.test.js";
 import { mockModel } from "./mockModel.js";
-import { runAbortCleanup } from "./streamText.js";
+import { runStreamCleanup } from "./streamText.js";
+import { errorToString } from "./utils.js";
 
 const schema = defineSchema({});
 type DataModel = DataModelFromSchemaDefinition<typeof schema>;
 const action = actionGeneric as ActionBuilder<DataModel, "public">;
 
 const FINAL_TEXT = "Hello from the model";
+const PROVIDER_FAILURE_TEXT = "Mock provider failure";
+const CLEANUP_FAILURE_TEXT = "finalizeMessage rejected";
+
+function hasKeys(
+  value: unknown,
+  keys: string[],
+): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    keys.every((key) => key in value)
+  );
+}
 
 const agent = new Agent(components.agent, {
   name: "stream-test",
@@ -34,6 +48,14 @@ const emptyAgent = new Agent(components.agent, {
   }),
 });
 
+const failingAgent = new Agent(components.agent, {
+  name: "failing-stream-test",
+  languageModel: mockModel({
+    content: [{ type: "text", text: "partial response" }],
+    fail: { error: PROVIDER_FAILURE_TEXT },
+  }),
+});
+
 // Action that exercises streamText with saveStreamDeltas.returnImmediately=true.
 // It consumes the stream after streamText returns, simulating the HTTP response
 // path described in issue #265.
@@ -91,11 +113,49 @@ export const streamTextEmptyReturnImmediately = action({
   },
 });
 
+export const streamTextCleanupFailure = action({
+  args: { threadId: v.string() },
+  handler: async (ctx, { threadId }) => {
+    const providerErrors: string[] = [];
+    let aborts = 0;
+    const failingCtx = {
+      ...ctx,
+      runMutation: (async (reference, args) => {
+        if (hasKeys(args, ["messageId", "result"])) {
+          throw new Error(CLEANUP_FAILURE_TEXT);
+        }
+        return ctx.runMutation(reference, args);
+      }) as typeof ctx.runMutation,
+    };
+    let caught: string | undefined;
+    try {
+      await failingAgent.streamText(
+        failingCtx,
+        { threadId },
+        {
+          prompt: "Test",
+          onError: ({ error }) => {
+            providerErrors.push(errorToString(error));
+          },
+          onAbort: () => {
+            aborts += 1;
+          },
+        },
+        { saveStreamDeltas: { chunking: "word", throttleMs: 0 } },
+      );
+    } catch (error) {
+      caught = errorToString(error);
+    }
+    return { providerErrors, aborts, caught };
+  },
+});
+
 const testApi: ApiFromModules<{
   fns: {
     streamTextReturnImmediately: typeof streamTextReturnImmediately;
     streamTextEmptyAwaited: typeof streamTextEmptyAwaited;
     streamTextEmptyReturnImmediately: typeof streamTextEmptyReturnImmediately;
+    streamTextCleanupFailure: typeof streamTextCleanupFailure;
   };
 }>["fns"] = anyApi["streamText.test"] as any;
 
@@ -147,28 +207,64 @@ describe("streamText with saveStreamDeltas.returnImmediately (issue #265)", () =
 });
 
 describe("streamText abort cleanup", () => {
-  test("attempts every cleanup and rethrows the first internal failure", async () => {
+  test("finishes durable cleanup before invoking onAbort", async () => {
     const calls: string[] = [];
-    const firstFailure = new Error("failed pending message cleanup");
+    let resolveStreamer!: () => void;
+    const syncFailure = new Error("synchronous pending message cleanup");
 
-    await expect(
-      runAbortCleanup({
-        failCall: async () => {
-          calls.push("call.fail");
-          throw firstFailure;
-        },
-        failStreamer: async () => {
+    const cleanup = runStreamCleanup({
+      failCall: () => {
+        calls.push("call.fail");
+        throw syncFailure;
+      },
+      failStreamer: () =>
+        new Promise<void>((resolve) => {
           calls.push("streamer.fail");
-          throw new Error("failed stream cleanup");
-        },
-        onAbort: () => {
-          calls.push("user.onAbort");
-        },
-      }),
-    ).rejects.toBe(firstFailure);
+          resolveStreamer = resolve;
+        }),
+      onAbort: () => {
+        calls.push("user.onAbort");
+      },
+    });
+
+    await Promise.resolve();
+    expect(calls).toEqual(["call.fail", "streamer.fail"]);
+    resolveStreamer();
+    await expect(cleanup).rejects.toBe(syncFailure);
 
     expect(calls).toEqual(["call.fail", "streamer.fail", "user.onAbort"]);
   });
+
+  test("surfaces a cleanup failure without hiding the provider error", async () => {
+    const t = initConvexTest(schema);
+    const threadId = await t.run(async (ctx) =>
+      createThread(ctx, components.agent, { userId: "u1" }),
+    );
+
+    const { providerErrors, aborts, caught } = await t.action(
+      testApi.streamTextCleanupFailure,
+      { threadId },
+    );
+
+    expect(providerErrors).toEqual([PROVIDER_FAILURE_TEXT]);
+    expect(aborts).toBe(0);
+    expect(caught).toBe(CLEANUP_FAILURE_TEXT);
+
+    const streaming = await t.run(async (ctx) =>
+      ctx.runQuery(components.agent.streams.list, {
+        threadId,
+        statuses: ["streaming"],
+      }),
+    );
+    const aborted = await t.run(async (ctx) =>
+      ctx.runQuery(components.agent.streams.list, {
+        threadId,
+        statuses: ["aborted"],
+      }),
+    );
+    expect(streaming).toHaveLength(0);
+    expect(aborted).toHaveLength(1);
+  });
 });
 
 describe("streamText with an empty final step (issue #274)", () => {

package/src/vercel/client/streamText.ts

@@ -27,19 +27,22 @@ import { getModelName, getProviderName } from "../../shared.js";
 import { errorToString, willContinue } from "./utils.js";
 import { materializeUIMessageChunkFiles } from "../fileMaterialization.js";
 
-/** Finish every abort cleanup path before surfacing an internal failure. */
-export async function runAbortCleanup(cleanup: {
+export async function runStreamCleanup(cleanup: {
   failCall: () => Promise<void>;
   failStreamer: () => Promise<void>;
   onAbort?: () => PromiseLike<void> | void;
 }): Promise<void> {
   const results = await Promise.allSettled([
-    cleanup.failCall(),
-    cleanup.failStreamer(),
+    Promise.resolve().then(() => cleanup.failCall()),
+    Promise.resolve().then(() => cleanup.failStreamer()),
   ]);
-  await cleanup.onAbort?.();
-  const failure = results.find((result) => result.status === "rejected");
-  if (failure) throw failure.reason;
+  const [abortResult] = await Promise.allSettled([
+    Promise.resolve().then(() => cleanup.onAbort?.()),
+  ]);
+  const failure = [...results, abortResult].find(
+    (result) => result.status === "rejected",
+  );
+  if (failure?.status === "rejected") throw failure.reason;
 }
 
 /**
@@ -103,15 +106,11 @@ export async function streamText<
       Tools,
       object,
       RUNTIME_CONTEXT
-    >(
-      ctx,
-      component,
-      streamTextArgs,
-      options,
-      "streamText",
-    );
+    >(ctx, component, streamTextArgs, options, "streamText");
 
   const steps: StepResult<Tools, RUNTIME_CONTEXT>[] = [];
+  let firstStreamError: string | undefined;
+  let streamCleanupFailure: { error: unknown } | undefined;
   let initialResponseMessages: ModelMessage[] = [];
   let initialResponseMessagesSaved = false;
   const responseMessagesForStep = (
@@ -180,15 +179,26 @@ export async function streamText<
     ),
     onError: async (error) => {
       console.error("onError", error);
-      await call.fail(errorToString(error.error));
-      await streamer?.fail(errorToString(error.error));
+      const reason = (firstStreamError ??= errorToString(error.error));
+      try {
+        await runStreamCleanup({
+          failCall: () => call.fail(reason),
+          failStreamer: async () => streamer?.fail(reason),
+        });
+      } catch (cleanupError) {
+        streamCleanupFailure ??= { error: cleanupError };
+        console.error("Failed to clean up errored stream:", cleanupError);
+      }
       return streamTextArgs.onError?.(error);
     },
     onAbort: async (event) => {
+      const providerTriggeredAbort =
+        firstStreamError !== undefined && !args.abortSignal?.aborted;
+      if (providerTriggeredAbort) return;
       const reason = args.abortSignal?.reason
         ? errorToString(args.abortSignal.reason)
         : "streamText aborted";
-      await runAbortCleanup({
+      await runStreamCleanup({
         failCall: () => call.fail(reason),
         failStreamer: async () => streamer?.fail(reason),
         onAbort: () => streamTextArgs.onAbort?.(event),
@@ -227,13 +237,17 @@ export async function streamText<
           // returnImmediately path: streamText is about to return without
           // awaiting consumption, so the deferred-save block below won't
           // see this step. Save inline now (issue #265).
-          const finishStreamId = await streamer.getOrCreateStreamId();
-          await call.save(
-            { step, responseMessages: responseMessagesForStep(step) },
-            false,
-            finishStreamId,
-          );
-          initialResponseMessagesSaved = true;
+          const finishStreamId = await streamer.getOrCreateStreamId({
+            ifAborted: "returnUndefined",
+          });
+          if (finishStreamId) {
+            await call.save(
+              { step, responseMessages: responseMessagesForStep(step) },
+              false,
+              finishStreamId,
+            );
+            initialResponseMessagesSaved = true;
+          }
         }
       } else {
         await call.save(
@@ -258,8 +272,11 @@ export async function streamText<
       // If the stream errored (e.g. onStepFinish threw), the DeltaStreamer's
       // finish() was never called, leaving the streaming message stuck in
       // "streaming" state. Clean it up by marking it as aborted.
-      await streamer?.fail(e instanceof Error ? e.message : String(e));
-      // Save the deferred final step if it was already generated but not yet persisted
+      try {
+        await streamer?.fail(errorToString(e));
+      } catch (cleanupError) {
+        streamCleanupFailure ??= { error: cleanupError };
+      }
       if (pendingFinalStep) {
         try {
           await call.save(pendingFinalStep, false);
@@ -272,10 +289,17 @@ export async function streamText<
     }
   }
 
+  if (streamCleanupFailure) throw streamCleanupFailure.error;
+
   // If we deferred the final step save, do it now with atomic stream finish.
   if (pendingFinalStep && streamer) {
-    const finishStreamId = await streamer.getOrCreateStreamId();
-    await call.save(pendingFinalStep, false, finishStreamId);
+    const finishStreamId = await streamer.getOrCreateStreamId({
+      ifAborted: "returnUndefined",
+    });
+    if (finishStreamId) {
+      await call.save(pendingFinalStep, false, finishStreamId);
+    }
+    pendingFinalStep = undefined;
   }
   const metadata: GenerationOutputMetadata = {
     promptMessageId,

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

@@ -5,10 +5,7 @@ import type { GenericSchema, SchemaDefinition } from "convex/server";
 import { streamText } from "ai";
 import { components, initConvexTest } from "./setup.test.js";
 import { mockModel } from "./mockModel.js";
-import {
-  compressUIMessageChunks,
-  DeltaStreamer,
-} from "./streaming.js";
+import { compressUIMessageChunks, DeltaStreamer } from "./streaming.js";
 import { getParts } from "../deltas.js";
 import type { TestConvex } from "convex-test";
 
@@ -200,12 +197,73 @@ describe("DeltaStreamer", () => {
       expect(streamer.abortController.signal.aborted).toBe(true);
       await streamer.addParts(["ignored"]);
       expect(streamer.streamId).toBeUndefined();
+      await expect(
+        streamer.getOrCreateStreamId({ ifAborted: "returnUndefined" }),
+      ).resolves.toBeUndefined();
       await expect(streamer.getOrCreateStreamId()).rejects.toThrow(
         "Cannot create a stream after it has been aborted",
       );
+      await expect(streamer.getStreamId()).rejects.toThrow(
+        "Cannot create a stream after it has been aborted",
+      );
+    });
+  });
+
+  test("preserves the public throwing behavior after an existing stream aborts", async () => {
+    await t.run(async (ctx) => {
+      const streamer = new DeltaStreamer<string>(
+        components.agent,
+        ctx,
+        { ...defaultTestOptions },
+        { ...testMetadata, threadId },
+      );
+      const streamId = await streamer.getStreamId();
+
+      await streamer.fail("provider error");
+
+      expect(streamer.streamId).toBe(streamId);
+      await expect(streamer.getStreamId()).rejects.toThrow(
+        "Cannot create a stream after it has been aborted",
+      );
+      await expect(streamer.getOrCreateStreamId()).rejects.toThrow(
+        "Cannot create a stream after it has been aborted",
+      );
+      await expect(
+        streamer.getOrCreateStreamId({ ifAborted: "returnUndefined" }),
+      ).resolves.toBeUndefined();
     });
   });
 
+  test("does not return an ID when abort wins during stream creation", async () => {
+    let resolveCreate!: (streamId: string) => void;
+    const creatingStream = new Promise<string>((resolve) => {
+      resolveCreate = resolve;
+    });
+    const runMutation = vi
+      .fn()
+      .mockImplementationOnce(() => creatingStream)
+      .mockResolvedValueOnce(true);
+    const streamer = new DeltaStreamer<string>(
+      components.agent,
+      { runMutation } as unknown as MutationCtx,
+      { ...defaultTestOptions },
+      { ...testMetadata, threadId },
+    );
+
+    const getting = streamer.getOrCreateStreamId({
+      ifAborted: "returnUndefined",
+    });
+    const failing = streamer.fail("provider error");
+    resolveCreate("stream-1");
+
+    await failing;
+    await expect(getting).resolves.toBeUndefined();
+    expect(streamer.streamId).toBe("stream-1");
+    await expect(streamer.getStreamId()).rejects.toThrow(
+      "Cannot create a stream after it has been aborted",
+    );
+  });
+
   test("shares signal and fail cleanup while stream creation is in flight", async () => {
     let resolveCreate!: (streamId: string) => void;
     const creatingStream = new Promise<string>((resolve) => {
@@ -293,10 +351,13 @@ describe("DeltaStreamer", () => {
   });
 
   test("aborts the component stream when a delta write fails", async () => {
+    const deltaFailure = {
+      error: { code: "provider_disconnected", message: "Provider dropped" },
+    };
     const runMutation = vi
       .fn()
       .mockResolvedValueOnce("stream-1")
-      .mockRejectedValueOnce(new Error("delta failed"))
+      .mockRejectedValueOnce(deltaFailure)
       .mockResolvedValueOnce(undefined);
     let abortReason: string | undefined;
     const streamer = new DeltaStreamer<string>(
@@ -314,11 +375,14 @@ describe("DeltaStreamer", () => {
     await streamer.addParts(["A"]);
     await streamer.finish();
 
-    expect(abortReason).toBe("delta failed");
+    expect(abortReason).toBe("provider_disconnected: Provider dropped");
     expect(runMutation).toHaveBeenNthCalledWith(
       3,
       components.agent.streams.abort,
-      { streamId: "stream-1", reason: "delta failed" },
+      {
+        streamId: "stream-1",
+        reason: "provider_disconnected: Provider dropped",
+      },
     );
   });
 

package/src/vercel/client/streaming.ts

@@ -8,6 +8,7 @@ import {
   type UIMessageChunk,
 } from "ai";
 import { v } from "convex/values";
+import { errorToString } from "../../errors.js";
 import {
   vMessageDoc,
   vPaginationResult,
@@ -300,7 +301,10 @@ export class DeltaStreamer<T> {
     if (this.#finishedExternally) {
       return;
     }
-    await this.getStreamId();
+    const streamId = await this.getOrCreateStreamId({
+      ifAborted: "returnUndefined",
+    });
+    if (!streamId) return;
     this.#nextParts.push(...parts);
     if (
       !this.#ongoingWrite &&
@@ -319,9 +323,7 @@ export class DeltaStreamer<T> {
       // A provider can throw while responding to an abort. Join the durable
       // abort transition here, outside the active delta writer, before
       // preserving the provider error for the caller.
-      await this.#abort(
-        error instanceof Error ? error.message : "stream consumption failed",
-      ).catch(() => {});
+      await this.#abort(errorToString(error)).catch(() => {});
       throw error;
     }
     // Skip finish if it will be handled externally (atomically with message save)
@@ -348,8 +350,26 @@ export class DeltaStreamer<T> {
    * Get the stream ID, waiting for it to be created if necessary.
    * Useful for passing to addMessages for atomic finish.
    */
-  public async getOrCreateStreamId(): Promise<string> {
-    return this.getStreamId();
+  public async getOrCreateStreamId(): Promise<string>;
+  public async getOrCreateStreamId(options: {
+    ifAborted: "returnUndefined";
+  }): Promise<string | undefined>;
+  public async getOrCreateStreamId(options?: {
+    ifAborted?: "returnUndefined";
+  }): Promise<string | undefined> {
+    if (options?.ifAborted !== "returnUndefined") {
+      return this.getStreamId();
+    }
+    if (this.abortController.signal.aborted) {
+      await this.#abortPromise;
+      return undefined;
+    }
+    const streamId = await this.getStreamId();
+    if (this.abortController.signal.aborted) {
+      await this.#abortPromise;
+      return undefined;
+    }
+    return streamId;
   }
 
   async #sendDelta() {
@@ -368,7 +388,7 @@ export class DeltaStreamer<T> {
         delta,
       );
     } catch (e) {
-      await this.#abortDelta(e instanceof Error ? e.message : "unknown error");
+      await this.#abortDelta(errorToString(e));
       return;
     }
     if (!success) {

package/src/vercel/client/types.ts

@@ -203,6 +203,8 @@ export type ContextOptions = {
   /**
    * How many recent messages to include. These are added after the search
    * messages, and do not count against the search limit.
+   * If the limit splits an order, additional messages are included to complete
+   * that order. If it cannot be completed, the incomplete order is omitted.
    * Default: 100
    */
   recentMessages?: number;

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

@@ -0,0 +1,97 @@
+import type { StepResult } from "ai";
+import { describe, expect, test } from "vitest";
+import { hasSuccessfulToolCall, willContinue } from "./utils.js";
+
+// Minimal StepResult builder — only the fields willContinue and
+// hasSuccessfulToolCall actually read. Loosely typed on purpose so test
+// fixtures can be terse; cast at the boundary.
+type StepFixture = {
+  finishReason?: string;
+  content?: Array<{ type: string; toolName?: string }>;
+  toolCalls?: Array<{ toolCallId: string; toolName: string }>;
+  toolResults?: Array<{ toolCallId: string; toolName: string }>;
+};
+
+function makeStep(partial: StepFixture): StepResult<any> {
+  return {
+    finishReason: "tool-calls",
+    content: [],
+    toolCalls: [],
+    toolResults: [],
+    ...partial,
+  } as unknown as StepResult<any>;
+}
+
+describe("hasSuccessfulToolCall", () => {
+  test("returns true when last step has a tool-result for the named tool", () => {
+    const step = makeStep({
+      content: [{ type: "tool-result", toolName: "search" }],
+    });
+    expect(hasSuccessfulToolCall("search")({ steps: [step] })).toBe(true);
+  });
+
+  test("returns false when only a tool-error is present for the named tool", () => {
+    const step = makeStep({
+      content: [{ type: "tool-error", toolName: "search" }],
+    });
+    expect(hasSuccessfulToolCall("search")({ steps: [step] })).toBe(false);
+  });
+
+  test("returns false when the matching tool name is missing", () => {
+    const step = makeStep({
+      content: [{ type: "tool-result", toolName: "other" }],
+    });
+    expect(hasSuccessfulToolCall("search")({ steps: [step] })).toBe(false);
+  });
+
+  test("only inspects the last step", () => {
+    const earlier = makeStep({
+      content: [{ type: "tool-result", toolName: "search" }],
+    });
+    const last = makeStep({
+      content: [{ type: "tool-error", toolName: "search" }],
+    });
+    expect(hasSuccessfulToolCall("search")({ steps: [earlier, last] })).toBe(
+      false,
+    );
+  });
+
+  test("returns false when steps is empty", () => {
+    expect(hasSuccessfulToolCall("search")({ steps: [] })).toBe(false);
+  });
+});
+
+describe("willContinue", () => {
+  test("does not stop when a tool-error fills in for a missing tool-result", async () => {
+    // Two tool calls; one returns a result, the other errors.
+    const step = makeStep({
+      toolCalls: [
+        { toolCallId: "1", toolName: "a" },
+        { toolCallId: "2", toolName: "b" },
+      ],
+      toolResults: [{ toolCallId: "1", toolName: "a" }],
+      content: [
+        { type: "tool-result", toolName: "a" },
+        { type: "tool-error", toolName: "b" },
+      ],
+    });
+    // No stopWhen → returns false (no further stop conditions). The point
+    // is the function progresses past the early `toolCalls > completed`
+    // bail; pre-fix it returned early because tool-error wasn't counted.
+    expect(await willContinue([step], undefined)).toBe(false);
+  });
+
+  test("stops when a tool call has neither a result nor an error yet", async () => {
+    const step = makeStep({
+      toolCalls: [{ toolCallId: "1", toolName: "a" }],
+      toolResults: [],
+      content: [],
+    });
+    expect(await willContinue([step], undefined)).toBe(false);
+  });
+
+  test("stops when finishReason is not tool-calls", async () => {
+    const step = makeStep({ finishReason: "stop" });
+    expect(await willContinue([step], undefined)).toBe(false);
+  });
+});

package/src/vercel/client/utils.ts

@@ -1,17 +1,23 @@
 import type { Context } from "@ai-sdk/provider-utils";
 import type { StepResult, StopCondition, ToolSet } from "ai";
 
+export { errorToString } from "../../errors.js";
+
 /**
- * A stop condition that only matches tool calls which completed
- * successfully (i.e. produced a `tool-result`, not a `tool-error`).
+ * A stop condition that only matches tool calls of the given name which
+ * completed successfully — i.e. produced a `tool-result` content part.
+ * Failed tool calls (which surface as `tool-error` parts under AI SDK v6)
+ * do not match.
  *
- * Use this instead of the AI SDK's `hasToolCall` when you want the
- * agent to retry on argument validation failures rather than stopping.
+ * Use this instead of the AI SDK's `hasToolCall` when you want the agent
+ * to retry on argument-validation or runtime tool failures rather than
+ * stopping. Evaluated only against the last step (consistent with how
+ * `stopWhen` is applied after each step).
  */
 export function hasSuccessfulToolCall(toolName: string): StopCondition<any> {
   return ({ steps }) =>
-    steps[steps.length - 1]?.toolResults?.some(
-      (result) => result.toolName === toolName,
+    steps[steps.length - 1]?.content?.some(
+      (p) => p.type === "tool-result" && p.toolName === toolName,
     ) ?? false;
 }
 
@@ -31,12 +37,13 @@ export async function willContinue<
   if (step.finishReason !== "tool-calls") return false;
   // Count both successful results and errors as completed outputs.
   // Failed tool calls are represented as tool-error content parts, so only
-  // checking toolResults misses them.
+  // checking toolResults misses them. The fallback to step.toolResults.length
+  // is for callers whose steps lack content (mocks); the optional chain is
+  // defensive rather than load-bearing.
   const completedOutputs =
     step.content?.filter(
       (p) => p.type === "tool-result" || p.type === "tool-error",
     ).length ?? step.toolResults.length;
-  // we don't have a tool result, so we'll wait for more
   if (step.toolCalls.length > completedOutputs) return false;
   if (Array.isArray(stopWhen)) {
     return (await Promise.all(stopWhen.map(async (s) => s({ steps })))).every(
@@ -45,10 +52,3 @@ export async function willContinue<
   }
   return !!stopWhen && !(await stopWhen({ steps }));
 }
-
-export function errorToString(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return String(error);
-}