@convex-dev/agent 0.7.0 → 0.7.2

package/src/vercel/client/streamText.ts

@@ -25,20 +25,24 @@ import { startGeneration } from "./start.js";
 import type { Agent } from "../index.js";
 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;
 }
 
 /**
@@ -102,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 = (
@@ -152,6 +152,8 @@ export async function streamText<
                 : undefined,
             onAsyncAbort: call.fail,
             compress: compressUIMessageChunks,
+            materialize: (parts) =>
+              materializeUIMessageChunkFiles(ctx, component, parts),
             abortSignal: args.abortSignal,
           },
           {
@@ -177,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),
@@ -224,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(
@@ -255,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);
@@ -269,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,10 +197,71 @@ 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 () => {
@@ -249,11 +307,57 @@ describe("DeltaStreamer", () => {
     );
   });
 
+  test("waits for signal cleanup when the source throws", async () => {
+    let resolveDelta!: (value: boolean) => void;
+    const deltaWrite = new Promise<boolean>((resolve) => {
+      resolveDelta = resolve;
+    });
+    const runMutation = vi
+      .fn()
+      .mockResolvedValueOnce("stream-1")
+      .mockImplementationOnce(() => deltaWrite)
+      .mockResolvedValueOnce(undefined);
+    const abortController = new AbortController();
+    const streamer = new DeltaStreamer<string>(
+      components.agent,
+      { runMutation } as unknown as MutationCtx,
+      { ...defaultTestOptions, abortSignal: abortController.signal },
+      { ...testMetadata, threadId },
+    );
+    const sourceError = new Error("provider aborted");
+    const source = {
+      async *[Symbol.asyncIterator]() {
+        yield "chunk";
+        abortController.abort();
+        throw sourceError;
+      },
+    } as unknown as Parameters<typeof streamer.consumeStream>[0];
+
+    const consuming = streamer.consumeStream(source);
+    let settled = false;
+    void consuming.catch(() => {
+      settled = true;
+    });
+    await vi.waitFor(() => expect(runMutation).toHaveBeenCalledTimes(2));
+    expect(settled).toBe(false);
+
+    resolveDelta(true);
+    await expect(consuming).rejects.toBe(sourceError);
+    expect(runMutation).toHaveBeenNthCalledWith(
+      3,
+      components.agent.streams.abort,
+      { streamId: "stream-1", reason: "abortSignal" },
+    );
+  });
+
   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>(
@@ -271,11 +375,42 @@ 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",
+      },
+    );
+  });
+
+  test("aborts the component stream when file materialization fails", async () => {
+    const materializationFailure = new Error("storage failed");
+    const runMutation = vi
+      .fn()
+      .mockResolvedValueOnce("stream-1")
+      .mockResolvedValueOnce(undefined);
+    const streamer = new DeltaStreamer<string>(
+      components.agent,
+      { runMutation } as unknown as MutationCtx,
+      {
+        ...defaultTestOptions,
+        onAsyncAbort: async () => {},
+        materialize: async () => {
+          throw materializationFailure;
+        },
+      },
+      { ...testMetadata, threadId },
+    );
+
+    await streamer.addParts(["A"]);
+    await expect(streamer.finish()).resolves.toBeUndefined();
+    expect(runMutation).toHaveBeenNthCalledWith(
+      2,
+      components.agent.streams.abort,
+      { streamId: "stream-1", reason: "storage failed" },
     );
   });
 

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,
@@ -204,6 +205,12 @@ export class DeltaStreamer<T> {
     throttleMs: number;
     onAsyncAbort: (reason: string) => Promise<void>;
     compress: ((parts: T[]) => T[]) | null;
+    materialize:
+      | ((parts: T[]) => Promise<{
+          parts: T[];
+          fileRefs: Array<{ url: string; fileId: string }>;
+        }>)
+      | null;
   };
   #nextParts: T[] = [];
   #latestWrite: number = 0;
@@ -223,6 +230,10 @@ export class DeltaStreamer<T> {
       onAsyncAbort: (reason: string) => Promise<void>;
       abortSignal: AbortSignal | undefined;
       compress: ((parts: T[]) => T[]) | null;
+      materialize?: (parts: T[]) => Promise<{
+        parts: T[];
+        fileRefs: Array<{ url: string; fileId: string }>;
+      }>;
     },
     public readonly metadata: {
       threadId: string;
@@ -240,6 +251,7 @@ export class DeltaStreamer<T> {
       throttleMs: config.throttleMs ?? DEFAULT_STREAMING_OPTIONS.throttleMs,
       onAsyncAbort: config.onAsyncAbort,
       compress: config.compress,
+      materialize: config.materialize ?? null,
     };
     this.#nextParts = [];
     this.abortController = new AbortController();
@@ -289,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 &&
@@ -300,8 +315,16 @@ export class DeltaStreamer<T> {
   }
 
   public async consumeStream(stream: AsyncIterableStream<T>) {
-    for await (const chunk of stream) {
-      await this.addParts([chunk]);
+    try {
+      for await (const chunk of stream) {
+        await this.addParts([chunk]);
+      }
+    } catch (error) {
+      // 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(errorToString(error)).catch(() => {});
+      throw error;
     }
     // Skip finish if it will be handled externally (atomically with message save)
     // or if the stream was aborted (e.g., due to a failed delta write).
@@ -327,29 +350,45 @@ 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() {
     if (this.abortController.signal.aborted) {
       return;
     }
-    const delta = this.#createDelta();
-    if (!delta) {
-      return;
-    }
-    this.#latestWrite = Date.now();
     let success: boolean;
     try {
+      const delta = await this.#createDelta();
+      if (!delta) {
+        return;
+      }
+      this.#latestWrite = Date.now();
       success = await this.ctx.runMutation(
         this.component.streams.addDelta,
         delta,
       );
     } catch (e) {
-      await this.#abortDelta(
-        e instanceof Error ? e.message : "unknown error",
-      );
+      await this.#abortDelta(errorToString(e));
       return;
     }
     if (!success) {
@@ -375,21 +414,36 @@ export class DeltaStreamer<T> {
     }
   }
 
-  #createDelta(): StreamDelta | undefined {
+  async #createDelta(): Promise<
+    | (StreamDelta & { fileRefs?: Array<{ url: string; fileId: string }> })
+    | undefined
+  > {
     if (this.#nextParts.length === 0) {
       return undefined;
     }
     const start = this.#cursor;
-    const end = start + this.#nextParts.length;
+    const pendingParts = this.#nextParts;
+    const end = start + pendingParts.length;
     this.#cursor = end;
-    const parts = this.config.compress
-      ? this.config.compress(this.#nextParts)
-      : this.#nextParts;
     this.#nextParts = [];
+    const materialized = this.config.materialize
+      ? await this.config.materialize(pendingParts)
+      : { parts: pendingParts, fileRefs: [] };
+    const parts = this.config.compress
+      ? this.config.compress(materialized.parts)
+      : materialized.parts;
     if (!this.streamId) {
       throw new Error("Creating a delta before the stream is created");
     }
-    return { streamId: this.streamId, start, end, parts };
+    return {
+      streamId: this.streamId,
+      start,
+      end,
+      parts,
+      ...(materialized.fileRefs.length > 0
+        ? { fileRefs: materialized.fileRefs }
+        : {}),
+    };
   }
 
   public async finish() {

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);
-}