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

package/MIGRATION.md

@@ -0,0 +1,153 @@
+# Migration Guide: v0.3.x to v0.6.0 (AI SDK v6)
+
+This guide helps you upgrade from @convex-dev/agent v0.3.x to v0.6.0.
+
+## Step 1: Update dependencies
+
+Update all AI SDK packages **together** to avoid peer dependency conflicts:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
+```
+
+### Official AI SDK providers
+
+Update your AI SDK provider packages to v3.x:
+```bash
+# For OpenAI
+npm install @ai-sdk/openai@^3.0.10
+
+# For Anthropic
+npm install @ai-sdk/anthropic@^3.0.13
+
+# For Groq
+npm install @ai-sdk/groq@^3.0.8
+
+# For Google (Gemini)
+npm install @ai-sdk/google@^3.0.8
+```
+
+### Third-party providers
+
+Third-party providers also need updates to be compatible with AI SDK v6:
+
+```bash
+# For OpenRouter
+npm install @openrouter/ai-sdk-provider@^2.0.0
+
+# For other providers, check their documentation for AI SDK v6 compatibility
+```
+
+### Handling dependency conflicts
+
+If you see peer dependency warnings or errors, try updating all packages at once:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/openai@^3.0.10 @openrouter/ai-sdk-provider@^2.0.0
+```
+
+If you still have conflicts, you can use `--force` as a last resort:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 --force
+```
+
+> **Note**: Using `--force` can lead to inconsistent dependency trees. After using it, verify your app works correctly and consider running `npm dedupe` to clean up.
+
+## Step 2: Update tool definitions
+
+Replace `parameters` with `inputSchema`:
+
+```typescript
+// Before (v5)
+const myTool = createTool({
+  description: "My tool",
+  parameters: z.object({ query: z.string() }),
+  execute: async (ctx, args) => { ... }
+})
+
+// After (v6)
+const myTool = createTool({
+  description: "My tool",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async (ctx, input, options) => { ... }
+})
+```
+
+## Step 3: Update Agent config (if using embeddings)
+
+```typescript
+// Before
+new Agent(components.agent, {
+  textEmbeddingModel: openai.embedding("text-embedding-3-small")
+})
+
+// After
+new Agent(components.agent, {
+  embeddingModel: openai.embedding("text-embedding-3-small")
+})
+```
+
+## Step 4: Update maxSteps (optional)
+
+```typescript
+// Before
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  maxSteps: 5
+})
+
+// After (maxSteps still works, but stopWhen is preferred)
+import { stepCountIs } from "ai"
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  stopWhen: stepCountIs(5)
+})
+```
+
+## Step 5: Verify
+
+```bash
+npm run typecheck
+npm test
+```
+
+## Common Issues
+
+### EmbeddingModelV2 vs EmbeddingModelV3 type errors
+Ensure all `@ai-sdk/*` packages are updated to v3.x. Older versions use AI SDK v5 types.
+
+### Tool `args` vs `input`
+AI SDK v6 renamed `args` to `input` in tool calls. The library maintains backwards compatibility, but you may see this in types.
+
+### `mimeType` vs `mediaType`
+AI SDK v6 renamed `mimeType` to `mediaType`. Backwards compatibility is maintained.
+
+### Peer dependency conflicts
+
+If you see errors like:
+```
+npm error ERESOLVE unable to resolve dependency tree
+npm error peer ai@"^5.0.0" from @openrouter/ai-sdk-provider@1.0.3
+```
+
+This means a third-party provider needs updating. Common solutions:
+
+1. **Update the provider** to a version compatible with AI SDK v6
+2. **Check npm** for the latest version: `npm view @openrouter/ai-sdk-provider versions`
+3. **Use `--force`** if a compatible version isn't available yet (temporary workaround)
+
+### Third-party provider compatibility
+
+| Provider | AI SDK v5 (ai@5.x) | AI SDK v6 (ai@6.x) |
+|----------|-------------------|-------------------|
+| @openrouter/ai-sdk-provider | v1.x | v2.x |
+| @ai-sdk/openai | v1.x-v2.x | v3.x |
+| @ai-sdk/anthropic | v1.x-v2.x | v3.x |
+| @ai-sdk/groq | v1.x-v2.x | v3.x |
+| @ai-sdk/google | v1.x-v2.x | v3.x |
+
+## More Information
+
+- [AI SDK v6 Migration Guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0)
+- [Convex Agent Documentation](https://docs.convex.dev/agents)

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/agent/issues"
   },
-  "version": "0.6.0-alpha.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -41,7 +41,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "MIGRATION.md"
   ],
   "exports": {
     "./package.json": "./package.json",
@@ -84,6 +85,7 @@
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.13",
+    "@ai-sdk/google": "^3.0.30",
     "@ai-sdk/groq": "^3.0.8",
     "@ai-sdk/openai": "^3.0.10",
     "@ai-sdk/provider": "^3.0.3",

package/src/UIMessages.ts

@@ -396,6 +396,54 @@ function createAssistantUIMessage<
     ? ("streaming" as const)
     : lastMessage.status;
 
+<<<<<<< Updated upstream
+=======
+  // Extract approval parts from raw message content for UI rendering
+  type ApprovalPart =
+    | { type: "tool-approval-request"; approvalId: string; toolCallId: string }
+    | {
+        type: "tool-approval-response";
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+      };
+  const approvalParts: ApprovalPart[] = [];
+
+  // Extract execution-denied tool results from raw content for UI rendering
+  // (these are converted to text format for provider compatibility in start.ts)
+  type ExecutionDeniedInfo = {
+    toolCallId: string;
+    reason?: string;
+  };
+  const executionDeniedResults: ExecutionDeniedInfo[] = [];
+
+  for (const message of group) {
+    const rawContent = message.message?.content;
+    if (Array.isArray(rawContent)) {
+      for (const part of rawContent) {
+        if (
+          part.type === "tool-approval-request" ||
+          part.type === "tool-approval-response"
+        ) {
+          approvalParts.push(part as ApprovalPart);
+        }
+        // Check for execution-denied in tool-result outputs
+        if (
+          part.type === "tool-result" &&
+          typeof part.output === "object" &&
+          part.output !== null &&
+          (part.output as { type?: string }).type === "execution-denied"
+        ) {
+          executionDeniedResults.push({
+            toolCallId: part.toolCallId as string,
+            reason: (part.output as { reason?: string }).reason,
+          });
+        }
+      }
+    }
+  }
+
+>>>>>>> Stashed changes
   // Collect all parts from all messages
   const allParts: UIMessage<METADATA, DATA_PARTS, TOOLS>["parts"] = [];
 
@@ -477,6 +525,12 @@ function createAssistantUIMessage<
           break;
         }
         case "tool-result": {
+<<<<<<< Updated upstream
+=======
+          // Note: execution-denied outputs are handled separately via pre-extraction
+          // from raw content (converted to text format for providers in start.ts).
+          // See executionDeniedResults processing at the end of this function.
+>>>>>>> Stashed changes
           const typedPart = contentPart as unknown as ToolResultPart & {
             output: { type: string; value?: unknown; reason?: string };
           };
@@ -642,6 +696,87 @@ function createAssistantUIMessage<
     }
   }
 
+<<<<<<< Updated upstream
+=======
+  // Final output states that should not be overwritten by approval processing
+  const finalStates = new Set([
+    "output-available",
+    "output-error",
+    "output-denied",
+  ]);
+
+  // Process approval parts to update tool call states
+  for (const approvalPart of approvalParts) {
+    if (approvalPart.type === "tool-approval-request") {
+      const toolCallPart = allParts.find(
+        (part) =>
+          "toolCallId" in part && part.toolCallId === approvalPart.toolCallId,
+      ) as ToolUIPart | undefined;
+
+      if (toolCallPart) {
+        // Always set approval info (needed for response matching), but only
+        // update state if not in a final state
+        (toolCallPart as ToolUIPart & { approval?: object }).approval = {
+          id: approvalPart.approvalId,
+        };
+        if (!finalStates.has(toolCallPart.state)) {
+          toolCallPart.state = "approval-requested";
+        }
+      }
+    } else if (approvalPart.type === "tool-approval-response") {
+      const toolCallPart = allParts.find(
+        (part) =>
+          "approval" in part &&
+          (part as ToolUIPart & { approval?: { id: string } }).approval?.id ===
+            approvalPart.approvalId,
+      ) as ToolUIPart | undefined;
+
+      if (toolCallPart) {
+        // Always update approval info, but only update state if not in a final state
+        (toolCallPart as ToolUIPart & { approval?: object }).approval = {
+          id: approvalPart.approvalId,
+          approved: approvalPart.approved,
+          reason: approvalPart.reason,
+        };
+        if (!finalStates.has(toolCallPart.state)) {
+          if (approvalPart.approved) {
+            toolCallPart.state = "approval-responded";
+          } else {
+            toolCallPart.state = "output-denied";
+          }
+        }
+      }
+    }
+  }
+
+  // Process execution-denied results to update tool call states
+  for (const denied of executionDeniedResults) {
+    const toolCallPart = allParts.find(
+      (part) =>
+        "toolCallId" in part && part.toolCallId === denied.toolCallId,
+    ) as ToolUIPart | undefined;
+
+    if (toolCallPart) {
+      toolCallPart.state = "output-denied";
+      if (!("approval" in toolCallPart) || !toolCallPart.approval) {
+        (toolCallPart as ToolUIPart & { approval?: object }).approval = {
+          id: "",
+          approved: false,
+          reason: denied.reason,
+        };
+      } else {
+        const approval = (
+          toolCallPart as ToolUIPart & {
+            approval: { approved?: boolean; reason?: string };
+          }
+        ).approval;
+        approval.approved = false;
+        approval.reason = denied.reason;
+      }
+    }
+  }
+
+>>>>>>> Stashed changes
   return {
     ...common,
     role: "assistant",

package/src/client/approval.test.ts

@@ -0,0 +1,350 @@
+import { describe, expect, test } from "vitest";
+import { Agent, createTool } from "./index.js";
+import type {
+  DataModelFromSchemaDefinition,
+  ApiFromModules,
+  ActionBuilder,
+  MutationBuilder,
+} from "convex/server";
+import { anyApi, actionGeneric, mutationGeneric } from "convex/server";
+import { v } from "convex/values";
+import { defineSchema } from "convex/server";
+import { stepCountIs, type LanguageModelUsage } from "ai";
+import { components, initConvexTest } from "./setup.test.js";
+import { z } from "zod/v4";
+import { mockModel } from "./mockModel.js";
+import type { UsageHandler } from "./types.js";
+
+const schema = defineSchema({});
+type DataModel = DataModelFromSchemaDefinition<typeof schema>;
+const action = actionGeneric as ActionBuilder<DataModel, "public">;
+const mutation = mutationGeneric as MutationBuilder<DataModel, "public">;
+
+// Tool that always requires approval
+const deleteFileTool = createTool({
+  description: "Delete a file",
+  inputSchema: z.object({ filename: z.string() }),
+  needsApproval: () => true,
+  execute: async (_ctx, input) => `Deleted: ${input.filename}`,
+});
+
+// Track usage handler calls to verify the full flow is exercised
+const usageCalls: LanguageModelUsage[] = [];
+const testUsageHandler: UsageHandler = async (_ctx, args) => {
+  usageCalls.push(args.usage);
+};
+
+function getApprovalIdFromSavedMessages(
+  savedMessages:
+    | Array<{
+        message?: { content: unknown };
+      }>
+    | undefined,
+): string {
+  const approvalRequest = savedMessages
+    ?.flatMap((savedMessage) =>
+      Array.isArray(savedMessage.message?.content)
+        ? savedMessage.message.content
+        : [],
+    )
+    .find((part) => {
+      const maybeApproval = part as { type?: unknown };
+      return maybeApproval.type === "tool-approval-request";
+    }) as { approvalId?: unknown } | undefined;
+  if (typeof approvalRequest?.approvalId !== "string") {
+    throw new Error("No approval request found in saved messages");
+  }
+  return approvalRequest.approvalId;
+}
+
+// --- Agents (separate mock model instances to avoid shared callIndex) ---
+
+const approvalAgent = new Agent(components.agent, {
+  name: "approval-test",
+  instructions: "You delete files when asked.",
+  tools: { deleteFile: deleteFileTool },
+  languageModel: mockModel({
+    contentSteps: [
+      // Step 1: model makes a tool call (LanguageModelV3 uses `input` as JSON string)
+      [
+        {
+          type: "tool-call",
+          toolCallId: "tc-approve",
+          toolName: "deleteFile",
+          input: JSON.stringify({ filename: "test.txt" }),
+        },
+      ],
+      // Step 2: after tool execution, model responds with text
+      [{ type: "text", text: "Done! I deleted test.txt." }],
+    ],
+  }),
+  stopWhen: stepCountIs(5),
+  usageHandler: testUsageHandler,
+});
+
+const denialAgent = new Agent(components.agent, {
+  name: "denial-test",
+  instructions: "You delete files when asked.",
+  tools: { deleteFile: deleteFileTool },
+  languageModel: mockModel({
+    contentSteps: [
+      [
+        {
+          type: "tool-call",
+          toolCallId: "tc-deny",
+          toolName: "deleteFile",
+          input: JSON.stringify({ filename: "secret.txt" }),
+        },
+      ],
+      [{ type: "text", text: "OK, I won't delete that file." }],
+    ],
+  }),
+  stopWhen: stepCountIs(5),
+  usageHandler: testUsageHandler,
+});
+
+// --- Test helpers ---
+
+export const testApproveFlow = action({
+  args: {},
+  handler: async (ctx) => {
+    const { thread } = await approvalAgent.createThread(ctx, { userId: "u1" });
+
+    // Step 1: Generate text — model returns tool call, SDK sees needsApproval → stops
+    const result1 = await thread.generateText({
+      prompt: "Delete test.txt",
+    });
+
+    const approvalId = getApprovalIdFromSavedMessages(result1.savedMessages);
+
+    // Step 2: Approve the tool call
+    const { messageId } = await ctx.runMutation(
+      anyApi["approval.test"].submitApprovalForApprovalAgent,
+      { threadId: thread.threadId, approvalId },
+    );
+
+    // Step 3: Continue generation — SDK executes tool, model responds
+    const result2 = await thread.generateText({
+      promptMessageId: messageId,
+    });
+
+    // Verify thread has all messages persisted
+    const allMessages = await approvalAgent.listMessages(ctx, {
+      threadId: thread.threadId,
+      paginationOpts: { cursor: null, numItems: 20 },
+    });
+
+    return {
+      approvalId,
+      firstText: result1.text,
+      secondText: result2.text,
+      firstSavedCount: result1.savedMessages?.length ?? 0,
+      secondSavedCount: result2.savedMessages?.length ?? 0,
+      totalThreadMessages: allMessages.page.length,
+      threadMessageRoles: allMessages.page.map((m) => m.message?.role),
+      usageCallCount: usageCalls.length,
+      // Verify usage data includes detail fields (AI SDK v6)
+      lastUsage: usageCalls.at(-1),
+    };
+  },
+});
+
+export const testDenyFlow = action({
+  args: {},
+  handler: async (ctx) => {
+    const { thread } = await denialAgent.createThread(ctx, { userId: "u2" });
+
+    // Step 1: Generate — model returns tool call, approval requested
+    const result1 = await thread.generateText({
+      prompt: "Delete secret.txt",
+    });
+
+    const approvalId = getApprovalIdFromSavedMessages(result1.savedMessages);
+
+    // Step 2: Deny the tool call
+    const { messageId } = await ctx.runMutation(
+      anyApi["approval.test"].submitDenialForDenialAgent,
+      {
+        threadId: thread.threadId,
+        approvalId,
+        reason: "This file is important",
+      },
+    );
+
+    // Step 3: Continue generation — SDK creates execution-denied, model responds
+    const result2 = await thread.generateText({
+      promptMessageId: messageId,
+    });
+
+    // Verify thread state
+    const allMessages = await denialAgent.listMessages(ctx, {
+      threadId: thread.threadId,
+      paginationOpts: { cursor: null, numItems: 20 },
+    });
+
+    return {
+      approvalId,
+      firstText: result1.text,
+      secondText: result2.text,
+      totalThreadMessages: allMessages.page.length,
+      threadMessageRoles: allMessages.page.map((m) => m.message?.role),
+      usageCallCount: usageCalls.length,
+      lastUsage: usageCalls.at(-1),
+    };
+  },
+});
+
+export const testApproveFlowWithInterveningMessage = action({
+  args: {},
+  handler: async (ctx) => {
+    const { thread } = await approvalAgent.createThread(ctx, { userId: "u3" });
+
+    const result1 = await thread.generateText({
+      prompt: "Delete test.txt",
+    });
+    const approvalId = getApprovalIdFromSavedMessages(result1.savedMessages);
+
+    const approvalRequest = (
+      await approvalAgent.listMessages(ctx, {
+        threadId: thread.threadId,
+        paginationOpts: { cursor: null, numItems: 20 },
+      })
+    ).page.find((m) => {
+      const content = m.message?.content;
+      return (
+        Array.isArray(content) &&
+        content.some(
+          (p) =>
+            p.type === "tool-approval-request" && p.approvalId === approvalId,
+        )
+      );
+    });
+    if (!approvalRequest) {
+      throw new Error("Approval request message not found");
+    }
+
+    const intervening = await approvalAgent.saveMessage(ctx, {
+      threadId: thread.threadId,
+      prompt: "Intervening user message",
+      skipEmbeddings: true,
+    });
+
+    const { messageId } = await ctx.runMutation(
+      anyApi["approval.test"].submitApprovalForApprovalAgent,
+      { threadId: thread.threadId, approvalId },
+    );
+
+    const result2 = await thread.generateText({
+      promptMessageId: messageId,
+    });
+
+    const allMessages = await approvalAgent.listMessages(ctx, {
+      threadId: thread.threadId,
+      paginationOpts: { cursor: null, numItems: 40 },
+    });
+    const approvalResponse = allMessages.page.find((m) => m._id === messageId);
+    if (!approvalResponse) {
+      throw new Error("Saved approval response message not found");
+    }
+
+    return {
+      secondText: result2.text,
+      approvalResponseOrder: approvalResponse.order,
+      approvalRequestId: approvalRequest._id,
+      approvalRequestOrder: approvalRequest.order,
+      interveningOrder: intervening.message.order,
+    };
+  },
+});
+
+export const submitApprovalForApprovalAgent = mutation({
+  args: { threadId: v.string(), approvalId: v.string(), reason: v.optional(v.string()) },
+  handler: async (ctx, { threadId, approvalId, reason }) => {
+    return approvalAgent.approveToolCall(ctx, { threadId, approvalId, reason });
+  },
+});
+
+export const submitDenialForDenialAgent = mutation({
+  args: { threadId: v.string(), approvalId: v.string(), reason: v.optional(v.string()) },
+  handler: async (ctx, { threadId, approvalId, reason }) => {
+    return denialAgent.denyToolCall(ctx, { threadId, approvalId, reason });
+  },
+});
+
+const testApi: ApiFromModules<{
+  fns: {
+    testApproveFlow: typeof testApproveFlow;
+    testDenyFlow: typeof testDenyFlow;
+    testApproveFlowWithInterveningMessage: typeof testApproveFlowWithInterveningMessage;
+    submitApprovalForApprovalAgent: typeof submitApprovalForApprovalAgent;
+    submitDenialForDenialAgent: typeof submitDenialForDenialAgent;
+  };
+}>["fns"] = anyApi["approval.test"] as any;
+
+describe("Tool Approval Workflow", () => {
+  test("approve: generate → approval request → approve → tool executes → final text", async () => {
+    usageCalls.length = 0;
+    const t = initConvexTest(schema);
+    const result = await t.action(testApi.testApproveFlow, {});
+
+    expect(result.approvalId).toBeDefined();
+    // First call produces no text (just a tool call)
+    expect(result.firstText).toBe("");
+    // Second call produces the final text
+    expect(result.secondText).toBe("Done! I deleted test.txt.");
+    // First call: user message + assistant (tool-call + approval-request)
+    expect(result.firstSavedCount).toBeGreaterThanOrEqual(2);
+    // Second call: tool-result + assistant text
+    expect(result.secondSavedCount).toBeGreaterThanOrEqual(1);
+    // Thread should have (ascending): user, assistant(tool-call+approval),
+    // tool(approval-response), tool(tool-result), assistant(text)
+    // listMessages returns descending order:
+    expect(result.threadMessageRoles).toEqual([
+      "assistant", // final text
+      "tool", // tool-result
+      "tool", // approval-response
+      "assistant", // tool-call + approval-request
+      "user", // prompt
+    ]);
+    // Usage handler should be called for each generateText call
+    expect(result.usageCallCount).toBeGreaterThanOrEqual(2);
+    // Usage data should include AI SDK v6 detail fields
+    expect(result.lastUsage).toBeDefined();
+    expect(result.lastUsage!.inputTokenDetails).toBeDefined();
+    expect(result.lastUsage!.outputTokenDetails).toBeDefined();
+  });
+
+  test("deny: generate → approval request → deny → model acknowledges denial", async () => {
+    usageCalls.length = 0;
+    const t = initConvexTest(schema);
+    const result = await t.action(testApi.testDenyFlow, {});
+
+    expect(result.approvalId).toBeDefined();
+    expect(result.firstText).toBe("");
+    expect(result.secondText).toBe("OK, I won't delete that file.");
+    // Same message ordering as approve flow:
+    // user, assistant(tool-call+approval), tool(denial-response),
+    // tool(execution-denied result), assistant(text)
+    expect(result.threadMessageRoles).toEqual([
+      "assistant",
+      "tool",
+      "tool",
+      "assistant",
+      "user",
+    ]);
+    // Usage handler exercised
+    expect(result.usageCallCount).toBeGreaterThanOrEqual(2);
+    expect(result.lastUsage!.inputTokenDetails).toBeDefined();
+    expect(result.lastUsage!.outputTokenDetails).toBeDefined();
+  });
+
+  test("approve remains valid with an intervening thread message", async () => {
+    usageCalls.length = 0;
+    const t = initConvexTest(schema);
+    const result = await t.action(testApi.testApproveFlowWithInterveningMessage, {});
+
+    expect(result.secondText).toBe("Done! I deleted test.txt.");
+    expect(result.approvalResponseOrder).toBe(result.approvalRequestOrder);
+    expect(result.interveningOrder).toBeGreaterThan(result.approvalResponseOrder);
+  });
+});