@convex-dev/agent 0.6.0-alpha.0 → 0.6.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,
@@ -259,17 +262,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 +292,28 @@ 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)
+    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 +340,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 +376,13 @@ export class DeltaStreamer<T> {
       return;
     }
     await this.#ongoingWrite;
+    if (this.abortController.signal.aborted) {
+      return;
+    }
     await this.#sendDelta();
+    if (this.abortController.signal.aborted) {
+      return;
+    }
     await this.ctx.runMutation(this.component.streams.finish, {
       streamId: this.streamId,
     });

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

package/src/mapping.ts

@@ -139,6 +139,97 @@ export function docsToModelMessages(messages: MessageDoc[]): ModelMessage[] {
     .map(toModelMessage);
 }
 
+/**
+ * Scan messages for unresolved `tool-approval-request` parts and inject
+ * synthetic `tool-approval-response` denials so that the AI SDK receives
+ * a complete history (every tool-call has a corresponding result or denial).
+ *
+ * This handles the case where a user sends a new message instead of
+ * resolving pending approvals — the old approvals are auto-denied rather
+ * than silently dropped.
+ */
+export function autoDenyUnresolvedApprovals(
+  messages: ModelMessage[],
+): ModelMessage[] {
+  // Collect all approval requests: approvalId → { toolCallId, messageIndex }
+  const requests = new Map<
+    string,
+    { toolCallId: string; messageIndex: number }
+  >();
+  // Collect all resolved approval IDs
+  const resolvedIds = new Set<string>();
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!Array.isArray(msg.content)) continue;
+    for (const part of msg.content as any[]) {
+      if (part.type === "tool-approval-request") {
+        requests.set(part.approvalId, {
+          toolCallId: part.toolCallId,
+          messageIndex: i,
+        });
+      } else if (part.type === "tool-approval-response") {
+        resolvedIds.add(part.approvalId);
+      }
+    }
+  }
+
+  // Find unresolved approvals
+  const unresolved: Array<{
+    approvalId: string;
+    toolCallId: string;
+    messageIndex: number;
+  }> = [];
+  for (const [approvalId, info] of requests) {
+    if (!resolvedIds.has(approvalId)) {
+      unresolved.push({ approvalId, ...info });
+    }
+  }
+
+  if (unresolved.length === 0) {
+    return messages;
+  }
+
+  // Group unresolved approvals by the assistant message index they came from
+  const byMessageIndex = new Map<
+    number,
+    Array<{ approvalId: string; toolCallId: string }>
+  >();
+  for (const entry of unresolved) {
+    console.warn(
+      `Auto-denying unresolved tool approval ${entry.approvalId} ` +
+        `(toolCallId: ${entry.toolCallId}): new generation started`,
+    );
+    let group = byMessageIndex.get(entry.messageIndex);
+    if (!group) {
+      group = [];
+      byMessageIndex.set(entry.messageIndex, group);
+    }
+    group.push(entry);
+  }
+
+  // Build result by inserting synthetic denial messages after each relevant
+  // assistant message
+  const result: ModelMessage[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    result.push(messages[i]);
+    const group = byMessageIndex.get(i);
+    if (group) {
+      result.push({
+        role: "tool",
+        content: group.map((entry) => ({
+          type: "tool-approval-response" as const,
+          approvalId: entry.approvalId,
+          approved: false,
+          reason: "auto-denied: new generation started",
+        })),
+      });
+    }
+  }
+
+  return result;
+}
+
 export function serializeUsage(usage: LanguageModelUsage): Usage {
   return {
     promptTokens: usage.inputTokens ?? 0,
@@ -211,6 +302,16 @@ export async function serializeNewMessagesInStep<TOOLS extends ToolSet>(
   component: AgentComponent,
   step: StepResult<TOOLS>,
   model: ModelOrMetadata | undefined,
+  /**
+   * If provided, these are the new response messages for this step
+   * (pre-sliced by the caller). When not provided, falls back to the
+   * existing heuristic of slicing the last 1-2 messages.
+   *
+   * This is needed for tool approval flows where the SDK adds extra
+   * messages (e.g. approval tool-results) at the beginning of
+   * responseMessages that the old slice(-1/-2) logic would miss.
+   */
+  newResponseMessages?: ModelMessage[],
 ): Promise<{ messages: MessageWithMetadata[] }> {
   // If there are tool results, there's another message with the tool results
   // ref: https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/to-response-messages.ts#L120
@@ -228,13 +329,21 @@ export async function serializeNewMessagesInStep<TOOLS extends ToolSet>(
     sources: hasToolMessage ? undefined : step.sources,
   } satisfies Omit<MessageWithMetadata, "message" | "text" | "fileIds">;
   const toolFields = { sources: step.sources };
+
+  // Determine which messages to serialize for this step
+  let messagesToSerialize: ModelMessage[];
+  if (newResponseMessages) {
+    messagesToSerialize = newResponseMessages;
+  } else if (hasToolMessage) {
+    messagesToSerialize = step.response.messages.slice(-2);
+  } else if (step.content.length) {
+    messagesToSerialize = step.response.messages.slice(-1);
+  } else {
+    messagesToSerialize = [{ role: "assistant" as const, content: [] }];
+  }
+
   const messages: MessageWithMetadata[] = await Promise.all(
-    (hasToolMessage
-      ? step.response.messages.slice(-2)
-      : step.content.length
-        ? step.response.messages.slice(-1)
-        : [{ role: "assistant" as const, content: [] }]
-    ).map(async (msg): Promise<MessageWithMetadata> => {
+    messagesToSerialize.map(async (msg): Promise<MessageWithMetadata> => {
       const { message, fileIds } = await serializeMessage(ctx, component, msg);
       return parse(vMessageWithMetadata, {
         message,

package/src/react/useDeltaStreams.ts

@@ -83,6 +83,12 @@ export function useDeltaStreams<
             ),
           );
 
+  // When no active streams remain, clear the stale state so we stop
+  // returning old streaming UIMessages.
+  if (streamMessages !== undefined && streamMessages.length === 0) {
+    state.deltaStreams = undefined;
+  }
+
   // Get the deltas for all the active streams, if any.
   const cursorQuery = useQuery(
     query,