feat: prepare VoltAgent 3 next prerelease

.changeset/pre.json

@@ -0,0 +1,64 @@
+{
+  "mode": "pre",
+  "tag": "next",
+  "initialVersions": {
+    "voltagent-example-github-repo-analyzer": "0.1.0",
+    "voltagent-example-github-star-stories": "0.0.0",
+    "voltagent-example-next-js-chatbot-starter-template": "0.1.0",
+    "ai-ad-generator": "0.1.2",
+    "voltagent-example-with-agent-tool": "1.0.0",
+    "assistant-ui-starter": "0.1.2",
+    "voltagent-example-with-chat-sdk": "0.1.0",
+    "voltagent-example-cloudflare-workers": "1.0.0",
+    "voltagent-example-with-composio-mcp": "0.1.0",
+    "voltagent-copilotkit-client": "0.0.1",
+    "voltagent-with-copilotkit-server": "0.0.3",
+    "voltagent-example-with-google-drive-mcp-client": "0.0.0",
+    "with-jwt-auth": "1.0.5",
+    "voltagent-example-with-lancedb": "1.0.0",
+    "example-with-live-evals": "0.0.5",
+    "voltagent-example-with-mcp": "0.1.0",
+    "voltagent-example-with-mcp-elicitation": "0.1.0",
+    "voltagent-example-with-memory-rest-api": "1.0.0",
+    "voltagent-example-with-nestjs": "1.0.0",
+    "voltagent-example-netlify-functions": "1.0.0",
+    "voltagent-example-with-nextjs": "0.1.0",
+    "voltagent-example-with-nextjs-resumable-stream": "0.1.0",
+    "voltagent-example-with-offline-evals": "0.0.0",
+    "voltagent-example-with-planagents": "0.1.0",
+    "voltagent-example-with-rag-chatbot": "0.0.1",
+    "voltagent-example-with-resumable-streams": "1.0.0",
+    "voltagent-example-with-voltops-resumable-streams": "1.0.0",
+    "voltagent-example-with-zapier-mcp": "1.0.0",
+    "@voltagent/a2a-server": "2.0.3",
+    "@voltagent/ag-ui": "1.0.7",
+    "@voltagent/cli": "0.1.21",
+    "@voltagent/cloudflare-d1": "2.1.2",
+    "@voltagent/core": "2.9.0",
+    "create-voltagent-app": "0.2.19",
+    "@voltagent/docs-mcp": "2.0.2",
+    "@voltagent/evals": "2.0.4",
+    "@voltagent/internal": "1.0.3",
+    "@voltagent/langfuse-exporter": "2.0.3",
+    "@voltagent/libsql": "2.1.2",
+    "@voltagent/logger": "2.0.2",
+    "@voltagent/mcp-server": "2.0.2",
+    "@voltagent/postgres": "2.1.2",
+    "@voltagent/rag": "1.0.2",
+    "@voltagent/resumable-streams": "2.0.2",
+    "@voltagent/sandbox-blaxel": "2.1.1",
+    "@voltagent/sandbox-daytona": "2.0.3",
+    "@voltagent/sandbox-e2b": "2.0.3",
+    "@voltagent/scorers": "2.1.0",
+    "@voltagent/sdk": "2.0.3",
+    "@voltagent/server-core": "2.1.19",
+    "@voltagent/server-elysia": "2.0.9",
+    "@voltagent/server-hono": "2.0.14",
+    "@voltagent/serverless-hono": "2.0.12",
+    "@voltagent/supabase": "2.1.3",
+    "@voltagent/vercel-ai-exporter": "2.0.2",
+    "@voltagent/voice": "2.1.0",
+    "@voltagent/voltagent-memory": "1.0.4"
+  },
+  "changesets": ["voltagent-3-next"]
+}

.changeset/voltagent-3-next.md

@@ -0,0 +1,247 @@
+---
+"@voltagent/a2a-server": major
+"@voltagent/ag-ui": major
+"@voltagent/cli": major
+"@voltagent/cloudflare-d1": major
+"@voltagent/core": major
+"@voltagent/docs-mcp": major
+"@voltagent/evals": major
+"@voltagent/internal": major
+"@voltagent/langfuse-exporter": major
+"@voltagent/libsql": major
+"@voltagent/logger": major
+"@voltagent/mcp-server": major
+"@voltagent/postgres": major
+"@voltagent/rag": major
+"@voltagent/resumable-streams": major
+"@voltagent/sandbox-blaxel": major
+"@voltagent/sandbox-daytona": major
+"@voltagent/sandbox-e2b": major
+"@voltagent/scorers": major
+"@voltagent/sdk": major
+"@voltagent/server-core": major
+"@voltagent/server-elysia": major
+"@voltagent/server-hono": major
+"@voltagent/serverless-hono": major
+"@voltagent/supabase": major
+"@voltagent/vercel-ai-exporter": major
+"@voltagent/voice": major
+"@voltagent/voltagent-memory": major
+"create-voltagent-app": major
+---
+
+Release the first VoltAgent 3 prerelease on the `next` channel.
+
+VoltAgent 3 aligns the framework with AI SDK v7, moves the published packages to an ESM-only runtime boundary, and requires Node.js 22 or later. This release keeps the core agent, memory, tool, workflow, guardrail, observability, server, MCP, A2A, AG-UI, and storage features available, while tightening the public API around AI SDK-compatible names and call shapes.
+
+### Install from the next channel
+
+```bash
+pnpm add @voltagent/core@next @voltagent/server-hono@next @voltagent/logger@next
+pnpm add ai@^7 @ai-sdk/openai@^4 zod@^4
+```
+
+If your app uses additional VoltAgent packages, keep all `@voltagent/*` packages on the same major/prerelease line:
+
+```bash
+pnpm add @voltagent/postgres@next @voltagent/supabase@next @voltagent/voice@next
+```
+
+### Runtime requirements
+
+VoltAgent 3 requires Node.js 22+ and ESM imports.
+
+```json
+{
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  }
+}
+```
+
+Before:
+
+```js
+const { Agent } = require("@voltagent/core");
+const { openai } = require("@ai-sdk/openai");
+```
+
+After:
+
+```ts
+import { Agent } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+```
+
+### AI SDK v7 alignment
+
+Upgrade `ai` and provider packages to AI SDK v7-compatible versions:
+
+```bash
+pnpm add ai@^7 @ai-sdk/provider-utils@^5
+pnpm add @ai-sdk/openai@^4
+```
+
+Common provider package upgrades:
+
+| Package                     | Version for AI SDK v7 |
+| --------------------------- | --------------------- |
+| `@ai-sdk/openai`            | `^4`                  |
+| `@ai-sdk/anthropic`         | `^4`                  |
+| `@ai-sdk/google`            | `^4`                  |
+| `@ai-sdk/azure`             | `^4`                  |
+| `@ai-sdk/groq`              | `^4`                  |
+| `@ai-sdk/mistral`           | `^4`                  |
+| `@ai-sdk/openai-compatible` | `^3`                  |
+| `@ai-sdk/amazon-bedrock`    | `^5`                  |
+| `@ai-sdk/google-vertex`     | `^5`                  |
+
+### Zod 4-only
+
+VoltAgent 3 requires Zod 4. The framework packages now use `zod@^4` peer ranges, examples and templates install Zod 4, and the old Zod 3 JSON Schema/OpenAPI compatibility fallback has been removed.
+
+```bash
+pnpm add zod@^4
+```
+
+### Agent usage
+
+The object-style call shape is the preferred API. AI SDK generation options stay at the top level, while VoltAgent runtime concerns live under `voltagent`.
+
+```ts
+const result = await agent.generateText({
+  prompt: "Summarize this support ticket",
+  temperature: 0.2,
+  maxOutputTokens: 500,
+  voltagent: {
+    memory: {
+      userId: "user-123",
+      conversationId: "ticket-456",
+    },
+    context: {
+      requestId: "req-789",
+    },
+  },
+});
+```
+
+The same shape works for streaming:
+
+```ts
+const result = await agent.streamText({
+  prompt: "Write a short release note",
+  stopWhen: isStepCount(5),
+  voltagent: {
+    memory: {
+      userId: "user-123",
+      conversationId: "release-456",
+    },
+  },
+});
+
+for await (const part of result.stream) {
+  if (part.type === "text-delta") {
+    process.stdout.write(part.text);
+  }
+}
+```
+
+`fullStream` remains as a deprecated compatibility alias during the transition, but new code should use `stream`.
+
+### Tool usage
+
+VoltAgent now accepts AI SDK-style tool sets directly, so projects can use `tool()` without wrapping every tool in `createTool`.
+
+```ts
+import { Agent, tool } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { z } from "zod";
+
+const agent = new Agent({
+  name: "Weather Agent",
+  model: openai("gpt-4o-mini"),
+  tools: {
+    getWeather: tool({
+      description: "Get the weather for a city",
+      inputSchema: z.object({
+        city: z.string(),
+      }),
+      execute: async ({ city }) => {
+        return { city, forecast: "Sunny", temperature: 72 };
+      },
+    }),
+  },
+});
+```
+
+VoltAgent-specific tool metadata is available through the `voltagent` namespace, so existing framework features can be used with AI SDK-style tools:
+
+```ts
+const refundCustomer = tool({
+  description: "Refund a customer order",
+  inputSchema: z.object({
+    orderId: z.string(),
+    reason: z.string(),
+  }),
+  execute: async ({ orderId, reason }) => {
+    return issueRefund(orderId, reason);
+  },
+  voltagent: {
+    name: "refundCustomer",
+    purpose: "Issue customer refunds",
+  },
+});
+```
+
+`createTool` remains available for existing tools and for codebases that prefer the VoltAgent-native helper.
+
+### Tool approval
+
+AI SDK native `toolApproval` is forwarded through VoltAgent agent calls.
+
+```ts
+const result = await agent.streamText({
+  prompt: "Refund order order_123 if it is eligible",
+  toolApproval: {
+    refundCustomer: "user-approval",
+  },
+});
+```
+
+Use call-level `toolApproval` for new per-request approval flows. Use `voltagent.needsApproval` only when approval should be static tool metadata or part of an existing VoltAgent approval/tool-policy flow. If both are provided, call-level `toolApproval` takes precedence.
+
+### Structured output
+
+Prefer AI SDK v7-style `output` over `experimental_output`.
+
+```ts
+import { Output } from "ai";
+import { z } from "zod";
+
+const result = await agent.generateText({
+  prompt: "Extract the customer profile",
+  output: Output.object({
+    schema: z.object({
+      name: z.string(),
+      plan: z.enum(["free", "pro", "enterprise"]),
+    }),
+  }),
+});
+
+console.log(result.output);
+```
+
+`generateObject` and `streamObject` remain as deprecated compatibility wrappers. For new code, use `generateText` or `streamText` with `output`.
+
+### Migration checklist
+
+1. Upgrade local development, CI, and production to Node.js 22 or later.
+2. Set `"type": "module"` and replace CommonJS `require()` calls with ESM imports.
+3. Upgrade all `@voltagent/*` packages together from the `next` channel.
+4. Upgrade `ai` to `^7` and AI SDK provider packages to their v7-compatible majors.
+5. Upgrade `zod` to `^4`.
+6. Replace `stepCountIs` with `isStepCount`.
+7. Prefer `result.stream` over `result.fullStream`.
+8. Prefer `output` over `experimental_output`.
+9. Prefer object-style agent calls for new code, with VoltAgent runtime options under `voltagent`.

.github/workflows/prerelease.yml

@@ -36,7 +36,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: "pnpm"
       - name: Install Dependencies
         run: pnpm install
@@ -63,7 +63,7 @@ jobs:
       - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: "pnpm"
       - name: Install Dependencies
         run: pnpm install
@@ -111,7 +111,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'pnpm'
 
       - name: Creating .npmrc
@@ -151,6 +151,18 @@ jobs:
         env:
           DATABASE_URL: postgresql://test:test@localhost:5432/voltagent_test
 
+      - name: Verify Changesets prerelease mode
+        run: |
+          node <<'NODE'
+          const pre = require("./.changeset/pre.json");
+
+          if (pre.mode !== "pre" || pre.tag !== "next") {
+            throw new Error(
+              'Expected Changesets prerelease mode with tag "next". Run "pnpm changeset pre enter next" on the next branch before publishing.',
+            );
+          }
+          NODE
+
       - name: Create Release Pull Request or Publish to npm
         id: changesets
         uses: changesets/action@v1