@convex-dev/agent 0.6.0-alpha.0 → 0.6.0-beta.0

package/src/client/streaming.ts

@@ -210,6 +210,9 @@ export class DeltaStreamer<T> {
   #ongoingWrite: Promise<void> | undefined;
   #cursor: number = 0;
   public abortController: AbortController;
+  // When true, the stream will be finished externally (e.g., atomically via addMessages)
+  // and consumeStream should skip calling finish().
+  #finishedExternally: boolean = false;
 
   constructor(
     public readonly component: AgentComponent,
@@ -241,16 +244,25 @@ export class DeltaStreamer<T> {
     this.abortController = new AbortController();
     if (config.abortSignal) {
       config.abortSignal.addEventListener("abort", async () => {
-        if (this.abortController.signal.aborted) {
-          return;
-        }
-        if (this.streamId) {
+        try {
+          if (this.abortController.signal.aborted) {
+            return;
+          }
           this.abortController.abort();
-          await this.#ongoingWrite;
-          await this.ctx.runMutation(this.component.streams.abort, {
-            streamId: this.streamId,
-            reason: "abortSignal",
-          });
+          // Wait for in-flight stream creation before trying to abort it
+          if (this.#creatingStreamIdPromise) {
+            await this.#creatingStreamIdPromise;
+          }
+          if (this.streamId) {
+            await this.#ongoingWrite;
+            await this.ctx.runMutation(this.component.streams.abort, {
+              streamId: this.streamId,
+              reason: "abortSignal",
+            });
+          }
+        } catch {
+          // Best-effort cleanup — the stream will be garbage-collected
+          // by the 10-minute timeout if this fails.
         }
       });
     }
@@ -259,17 +271,16 @@ export class DeltaStreamer<T> {
   // Avoid race conditions by only creating once
   #creatingStreamIdPromise: Promise<string> | undefined;
   public async getStreamId() {
-    if (this.streamId) {
-      return this.streamId;
-    }
-    if (this.#creatingStreamIdPromise) {
-      return this.#creatingStreamIdPromise;
+    if (!this.streamId) {
+      if (!this.#creatingStreamIdPromise) {
+        this.#creatingStreamIdPromise = this.ctx.runMutation(
+          this.component.streams.create,
+          this.metadata,
+        );
+      }
+      this.streamId = await this.#creatingStreamIdPromise;
     }
-    this.#creatingStreamIdPromise = this.ctx.runMutation(
-      this.component.streams.create,
-      this.metadata,
-    );
-    this.streamId = await this.#creatingStreamIdPromise;
+    return this.streamId;
   }
 
   public async addParts(parts: T[]) {
@@ -290,7 +301,30 @@ export class DeltaStreamer<T> {
     for await (const chunk of stream) {
       await this.addParts([chunk]);
     }
-    await this.finish();
+    // 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).
+    // Aborted streams are cleaned up via streams.abort (called by the abort
+    // signal handler), so we don't need to call finish() for them.
+    if (!this.#finishedExternally && !this.abortController.signal.aborted) {
+      await this.finish();
+    }
+  }
+
+  /**
+   * Mark the stream as being finished externally (e.g., atomically via addMessages).
+   * When called, consumeStream() will skip calling finish() since it will be
+   * handled elsewhere in the same mutation as message saving.
+   */
+  public markFinishedExternally(): void {
+    this.#finishedExternally = true;
+  }
+
+  /**
+   * 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();
   }
 
   async #sendDelta() {
@@ -317,7 +351,7 @@ export class DeltaStreamer<T> {
         e instanceof Error ? e.message : "unknown error",
       );
       this.abortController.abort();
-      throw e;
+      return;
     }
     // Now that we've sent the delta, check if we need to send another one.
     if (
@@ -353,7 +387,10 @@ export class DeltaStreamer<T> {
       return;
     }
     await this.#ongoingWrite;
-    await this.#sendDelta();
+    await this.#sendDelta(); // #sendDelta checks aborted internally
+    if (this.abortController.signal.aborted) {
+      return;
+    }
     await this.ctx.runMutation(this.component.streams.finish, {
       streamId: this.streamId,
     });
@@ -410,16 +447,15 @@ export function compressTextStreamParts(
       } else {
         compressed.push(part);
       }
+    } else if (part.type === "file") {
+      compressed.push({
+        type: "file",
+        file: {
+          ...part.file,
+          uint8Array: undefined as unknown as Uint8Array,
+        },
+      });
     } else {
-      if (part.type === "file") {
-        compressed.push({
-          type: "file",
-          file: {
-            ...part.file,
-            uint8Array: undefined as unknown as Uint8Array,
-          },
-        });
-      }
       compressed.push(part);
     }
   }

package/src/client/types.ts

@@ -46,6 +46,14 @@ import type {
 import type { StreamingOptions } from "./streaming.js";
 import type { ComponentApi } from "../component/_generated/component.js";
 
+/**
+ * Type-level check that ensures models are from AI SDK v6.
+ * If a v5 model (LanguageModelV2) is passed, TypeScript will show the error message string.
+ */
+type AssertAISDKv6<T> = T extends { specificationVersion: "v3" }
+  ? T
+  : "⚠️ @convex-dev/agent v0.6.0 requires AI SDK v6. Update your dependencies: npm install ai@^6.0.35 @ai-sdk/openai@^3.0.10 (or other provider). See: node_modules/@convex-dev/agent/MIGRATION.md";
+
 export type AgentPrompt = {
   /**
    * System message to include in the prompt. Overwrites Agent instructions.
@@ -91,23 +99,17 @@ export type AgentPrompt = {
 export type Config = {
   /**
    * The LLM model to use for generating / streaming text and objects.
-   * e.g.
+   * Requires AI SDK v6 (@ai-sdk/* packages v3.x).
+   *
+   * @example
    * import { openai } from "@ai-sdk/openai"
    * const myAgent = new Agent(components.agent, {
    *   languageModel: openai.chat("gpt-4o-mini"),
+   * })
    */
-  languageModel?: LanguageModel;
+  languageModel?: AssertAISDKv6<LanguageModel>;
   /**
-   * The model to use for text embeddings. Optional.
-   * If specified, it will use this for generating vector embeddings
-   * of chats, and can opt-in to doing vector search for automatic context
-   * on generateText, etc.
-   * e.g.
-   * import { openai } from "@ai-sdk/openai"
-   * const myAgent = new Agent(components.agent, {
-   *   ...
-   *   textEmbeddingModel: openai.embedding("text-embedding-3-small")
-   * @deprecated — Use embeddingModel instead.
+   * @deprecated Use `embeddingModel` instead.
    */
   textEmbeddingModel?: EmbeddingModel;
   /**

package/src/component/_generated/component.ts

@@ -154,6 +154,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             vectors: Array<Array<number> | null>;
           };
           failPendingSteps?: boolean;
+          finishStreamId?: string;
           hideFromUserIdSearch?: boolean;
           messages: Array<{
             error?: string;
@@ -1420,22 +1421,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                           toolName: string;
                           type: "tool-call";
                         }
-                        | {
-                            args: any;
-                            input?: any;
-                            providerExecuted?: boolean;
-                            providerMetadata?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            providerOptions?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            toolCallId: string;
-                            toolName: string;
-                            type: "tool-call";
-                          }
+                      | {
+                          args: any;
+                          input?: any;
+                          providerExecuted?: boolean;
+                          providerMetadata?: Record<
+                            string,
+                            Record<string, any>
+                          >;
+                          providerOptions?: Record<string, Record<string, any>>;
+                          toolCallId: string;
+                          toolName: string;
+                          type: "tool-call";
+                        }
                       | {
                           args?: any;
                           experimental_content?: Array<
@@ -2533,22 +2531,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                           toolName: string;
                           type: "tool-call";
                         }
-                        | {
-                            args: any;
-                            input?: any;
-                            providerExecuted?: boolean;
-                            providerMetadata?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            providerOptions?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            toolCallId: string;
-                            toolName: string;
-                            type: "tool-call";
-                          }
+                      | {
+                          args: any;
+                          input?: any;
+                          providerExecuted?: boolean;
+                          providerMetadata?: Record<
+                            string,
+                            Record<string, any>
+                          >;
+                          providerOptions?: Record<string, Record<string, any>>;
+                          toolCallId: string;
+                          toolName: string;
+                          type: "tool-call";
+                        }
                       | {
                           args?: any;
                           experimental_content?: Array<
@@ -3054,22 +3049,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                           toolName: string;
                           type: "tool-call";
                         }
-                        | {
-                            args: any;
-                            input?: any;
-                            providerExecuted?: boolean;
-                            providerMetadata?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            providerOptions?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            toolCallId: string;
-                            toolName: string;
-                            type: "tool-call";
-                          }
+                      | {
+                          args: any;
+                          input?: any;
+                          providerExecuted?: boolean;
+                          providerMetadata?: Record<
+                            string,
+                            Record<string, any>
+                          >;
+                          providerOptions?: Record<string, Record<string, any>>;
+                          toolCallId: string;
+                          toolName: string;
+                          type: "tool-call";
+                        }
                       | {
                           args?: any;
                           experimental_content?: Array<
@@ -4063,22 +4055,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                           toolName: string;
                           type: "tool-call";
                         }
-                        | {
-                            args: any;
-                            input?: any;
-                            providerExecuted?: boolean;
-                            providerMetadata?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            providerOptions?: Record<
-                              string,
-                              Record<string, any>
-                            >;
-                            toolCallId: string;
-                            toolName: string;
-                            type: "tool-call";
-                          }
+                      | {
+                          args: any;
+                          input?: any;
+                          providerExecuted?: boolean;
+                          providerMetadata?: Record<
+                            string,
+                            Record<string, any>
+                          >;
+                          providerOptions?: Record<string, Record<string, any>>;
+                          toolCallId: string;
+                          toolName: string;
+                          type: "tool-call";
+                        }
                       | {
                           args?: any;
                           experimental_content?: Array<

package/src/component/messages.ts

@@ -39,7 +39,7 @@ import {
   vVectorId,
 } from "./vector/tables.js";
 import { changeRefcount } from "./files.js";
-import { getStreamingMessagesWithMetadata } from "./streams.js";
+import { getStreamingMessagesWithMetadata, finishHandler } from "./streams.js";
 import { partial } from "convex-helpers/validators";
 
 function publicMessage(message: Doc<"messages">): MessageDoc {
@@ -141,6 +141,9 @@ const addMessagesArgs = {
   // if set to true, these messages will not show up in text or vector search
   // results for the userId
   hideFromUserIdSearch: v.optional(v.boolean()),
+  // If provided, finish this stream atomically with the message save.
+  // This prevents UI flickering from separate mutations (issue #181).
+  finishStreamId: v.optional(v.id("streamingMessages")),
 };
 export const addMessages = mutation({
   args: addMessagesArgs,
@@ -161,6 +164,8 @@ async function addMessagesHandler(
   const {
     embeddings,
     failPendingSteps,
+    // Destructured separately to exclude from `...rest` (used in addMessages args, not message fields)
+    finishStreamId,
     messages,
     promptMessageId,
     pendingMessageId,
@@ -274,7 +279,7 @@ async function addMessagesHandler(
         order: pendingMessage.order,
         stepOrder: pendingMessage.stepOrder,
       });
-      toReturn.push(pendingMessage);
+      toReturn.push((await ctx.db.get(pendingMessage._id))!);
       continue;
     }
     if (message.message.role === "user") {
@@ -303,6 +308,11 @@ async function addMessagesHandler(
     // TODO: delete the associated stream data for the order/stepOrder
     toReturn.push((await ctx.db.get(messageId))!);
   }
+  // Atomically finish the stream if requested, preventing UI flickering
+  // from separate mutations for message save and stream finish (issue #181).
+  if (finishStreamId) {
+    await finishHandler(ctx, { streamId: finishStreamId });
+  }
   return { messages: toReturn.map(publicMessage) };
 }
 

package/src/deltas.ts

@@ -124,7 +124,6 @@ export async function deriveUIMessagesFromDeltas(
         blankUIMessage(streamMessage, threadId),
         parts,
       );
-      // TODO: this fails on partial tool calls
       messages.push(uiMessage);
     } else {
       const [uiMessages] = deriveUIMessagesFromTextStreamParts(

package/src/mapping.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import {
   guessMimeType,
   serializeDataOrUrl,
@@ -7,6 +7,7 @@ import {
   toModelMessage,
   serializeContent,
   toModelMessageContent,
+  autoDenyUnresolvedApprovals,
 } from "./mapping.js";
 import { api } from "./component/_generated/api.js";
 import type { AgentComponent, ActionCtx } from "./client/types.js";
@@ -257,4 +258,145 @@ describe("mapping", () => {
     expect(content).toHaveLength(1);
     expect((content as unknown[])[0]).toMatchObject(approvalResponse);
   });
+
+  describe("autoDenyUnresolvedApprovals", () => {
+    test("returns messages unchanged when no unresolved approvals", () => {
+      const messages = [
+        { role: "user" as const, content: "hello" },
+        {
+          role: "assistant" as const,
+          content: [
+            { type: "tool-call", toolCallId: "tc1", toolName: "a", input: {} },
+            { type: "tool-approval-request", approvalId: "ap1", toolCallId: "tc1" },
+          ],
+        },
+        {
+          role: "tool" as const,
+          content: [
+            { type: "tool-approval-response", approvalId: "ap1", approved: true },
+          ],
+        },
+      ] as any;
+
+      const result = autoDenyUnresolvedApprovals(messages);
+      expect(result).toBe(messages); // same reference, no changes
+    });
+
+    test("injects synthetic denial for a single unresolved approval", () => {
+      const messages = [
+        { role: "user" as const, content: "hello" },
+        {
+          role: "assistant" as const,
+          content: [
+            { type: "tool-call", toolCallId: "tc1", toolName: "a", input: {} },
+            { type: "tool-approval-request", approvalId: "ap1", toolCallId: "tc1" },
+          ],
+        },
+        { role: "user" as const, content: "new message" },
+      ] as any;
+
+      const result = autoDenyUnresolvedApprovals(messages);
+      expect(result).toHaveLength(4); // original 3 + 1 synthetic tool message
+      // Synthetic denial should be inserted right after the assistant message (index 1)
+      expect(result[2].role).toBe("tool");
+      const denialContent = result[2].content as any[];
+      expect(denialContent).toHaveLength(1);
+      expect(denialContent[0].type).toBe("tool-approval-response");
+      expect(denialContent[0].approvalId).toBe("ap1");
+      expect(denialContent[0].approved).toBe(false);
+      expect(denialContent[0].reason).toBe("auto-denied: new generation started");
+      // The new user message should follow
+      expect(result[3].role).toBe("user");
+      expect(result[3].content).toBe("new message");
+    });
+
+    test("groups multiple unresolved approvals from the same step into a single synthetic message", () => {
+      const messages = [
+        {
+          role: "assistant" as const,
+          content: [
+            { type: "tool-call", toolCallId: "tc1", toolName: "a", input: {} },
+            { type: "tool-call", toolCallId: "tc2", toolName: "b", input: {} },
+            { type: "tool-approval-request", approvalId: "ap1", toolCallId: "tc1" },
+            { type: "tool-approval-request", approvalId: "ap2", toolCallId: "tc2" },
+          ],
+        },
+      ] as any;
+
+      const result = autoDenyUnresolvedApprovals(messages);
+      expect(result).toHaveLength(2); // assistant + 1 synthetic tool message
+      expect(result[1].role).toBe("tool");
+      const denialContent = result[1].content as any[];
+      expect(denialContent).toHaveLength(2);
+      expect(denialContent[0].approvalId).toBe("ap1");
+      expect(denialContent[0].approved).toBe(false);
+      expect(denialContent[1].approvalId).toBe("ap2");
+      expect(denialContent[1].approved).toBe(false);
+    });
+
+    test("only auto-denies unresolved approvals, leaves resolved ones alone", () => {
+      const messages = [
+        {
+          role: "assistant" as const,
+          content: [
+            { type: "tool-call", toolCallId: "tc1", toolName: "a", input: {} },
+            { type: "tool-call", toolCallId: "tc2", toolName: "b", input: {} },
+            { type: "tool-approval-request", approvalId: "ap1", toolCallId: "tc1" },
+            { type: "tool-approval-request", approvalId: "ap2", toolCallId: "tc2" },
+          ],
+        },
+        {
+          role: "tool" as const,
+          content: [
+            { type: "tool-approval-response", approvalId: "ap1", approved: true },
+          ],
+        },
+        { role: "user" as const, content: "next question" },
+      ] as any;
+
+      const result = autoDenyUnresolvedApprovals(messages);
+      // Should inject a denial for ap2 (unresolved) after the assistant message
+      expect(result).toHaveLength(4); // assistant + existing tool + synthetic denial + user
+      // The synthetic denial is inserted after the assistant (index 0)
+      expect(result[0].role).toBe("assistant");
+      expect(result[1].role).toBe("tool"); // synthetic denial for ap2
+      const denialContent = result[1].content as any[];
+      expect(denialContent).toHaveLength(1);
+      expect(denialContent[0].approvalId).toBe("ap2");
+      expect(denialContent[0].approved).toBe(false);
+      // Original tool message (ap1 response) follows
+      expect(result[2].role).toBe("tool");
+      const originalToolContent = result[2].content as any[];
+      expect(originalToolContent[0].approvalId).toBe("ap1");
+      expect(originalToolContent[0].approved).toBe(true);
+      // User message last
+      expect(result[3].role).toBe("user");
+    });
+
+    test("emits console.warn for each auto-denied approval", () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const messages = [
+        {
+          role: "assistant" as const,
+          content: [
+            { type: "tool-call", toolCallId: "tc1", toolName: "a", input: {} },
+            { type: "tool-call", toolCallId: "tc2", toolName: "b", input: {} },
+            { type: "tool-approval-request", approvalId: "ap1", toolCallId: "tc1" },
+            { type: "tool-approval-request", approvalId: "ap2", toolCallId: "tc2" },
+          ],
+        },
+      ] as any;
+
+      autoDenyUnresolvedApprovals(messages);
+
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("ap1"),
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("ap2"),
+      );
+      warnSpy.mockRestore();
+    });
+  });
 });