@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/guides/migrations/upgrade-to-v1/client.md

@@ -0,0 +1,337 @@
+# Client SDK
+
+Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.
+
+## Changed
+
+### `messages` is now identical to `@mastra/core/agent` syntax
+
+The `messages` argument is now the first argument of the `generate`, `stream` and `network` method calls, similar to the NodeJS version in `@mastra/core/agent`.
+
+To migrate, move `messages` to the first argument of the method call:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+-  await agent.generate({
+-    messages: [...]
++  await agent.generate([...], {
+  });
+
+-  await agent.stream({
+-    messages: [...]
++  await agent.stream([...], {
+  });
+
+-  await agent.network({
+-    messages: [...]
++  await agent.network([...], {
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@beta v1/client-msg-function-args .
+> ```
+
+### `threadId` and `resourceId` to `memory` option
+
+The `threadId` and `resourceId` options have been removed from agent method calls. Use the `memory` option instead, which provides a cleaner API for memory configuration. This applies to both `@mastra/client-js` and `@mastra/react` packages.
+
+To migrate, move `threadId` and `resourceId` into the `memory` option:
+
+**Using `@mastra/client-js`:**
+
+```diff
+const agent = client.getAgent('my-agent');
+
+  await agent.generate([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+
++  await agent.stream([...], {
+-   threadId: 'thread-123',
+-   resourceId: 'user-456',
++   memory: {
++     thread: 'thread-123',
++     resource: 'user-456',
++   },
+  });
+```
+
+#### Using `@mastra/react` `useChat` hook
+
+The `useChat` hook internally passes the memory option when you provide a `threadId`. No changes are needed in your component code if you're using the hook's built-in memory handling. However, if you were manually passing options to `sendMessage`, update them accordingly:
+
+```diff
+const { sendMessage } = useChat({ agentId: 'my-agent' });
+
+  await sendMessage({
+    message: 'Hello',
+    mode: 'stream',
+-   threadId: 'thread-123',
++   threadId: 'thread-123', // Still works - internally converted to memory option
+  });
+```
+
+The `memory` option also supports passing thread metadata when creating new threads:
+
+```typescript
+await agent.generate([...], {
+  memory: {
+    thread: {
+      id: 'thread-123',
+      title: 'Support conversation',
+      metadata: { category: 'billing' },
+    },
+    resource: 'user-456',
+  },
+});
+```
+
+### Client SDK types from `Get*` to `List*`
+
+Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.
+
+To migrate, update type imports to use the new naming pattern.
+
+```diff
+- import type {
+-   GetWorkflowRunsParams,
+-   GetWorkflowRunsResponse,
+-   GetMemoryThreadParams,
+- } from '@mastra/client-js';
++ import type {
++   ListWorkflowRunsParams,
++   ListWorkflowRunsResponse,
++   ListMemoryThreadsParams,
++ } from '@mastra/client-js';
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-sdk-types .
+> ```
+
+### Pagination parameters from `offset/limit` to `page/perPage`
+
+All client SDK methods that used `offset/limit` now use `page/perPage`. This change provides a more intuitive pagination model aligned with web pagination patterns.
+
+To migrate, update pagination parameters in all client SDK method calls. Example:
+
+```diff
+client.memory.listMessages({
+    threadId: 'thread-123',
+-   offset: 0,
+-   limit: 20,
++   page: 0,
++   perPage: 20,
+  });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-offset-limit .
+> ```
+
+### `getMemoryThread` parameter structure
+
+The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.
+
+To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.
+
+```diff
+- const thread = await client.getMemoryThread(threadId, agentId);
++ const thread = await client.getMemoryThread({ threadId, agentId });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-get-memory-thread .
+> ```
+
+### Unified `runById` API for workflow runs
+
+The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.
+
+The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.
+
+```diff
+const workflow = client.getWorkflow('my-workflow');
+
+- // Previously: runById returned raw WorkflowRun with snapshot
+- const run = await workflow.runById(runId, requestContext);
+- // Separately: runExecutionResult returned processed execution state
+- const result = await workflow.runExecutionResult(runId);
+
++ // Now: Single method returns unified WorkflowState
++ const run = await workflow.runById(runId, {
++   requestContext,  // Optional request context
++   fields: ['status', 'result'],  // Optional: request only specific fields
++   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
++ });
++ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
+```
+
+## Removed
+
+### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type
+
+The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.
+
+To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.
+
+```diff
+- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const result = await workflow.runExecutionResult(runId);
+
++ const workflow = client.getWorkflow('my-workflow');
++ const result = await workflow.runById(runId);
++ // Or with options for performance optimization:
++ const result = await workflow.runById(runId, {
++   fields: ['status', 'result'],  // Only fetch specific fields
++   withNestedWorkflows: false,     // Skip expensive nested workflow data
++ });
+```
+
+### `toAISdkFormat` function
+
+The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.
+
+To migrate, use `toAISdkStream()` instead.
+
+```diff
+- import { toAISdkFormat } from '@mastra/ai-sdk';
+- const stream = toAISdkFormat(agentStream, { from: 'agent' });
++ import { toAISdkStream } from '@mastra/ai-sdk';
++ const stream = toAISdkStream(agentStream, { from: 'agent' });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/client-to-ai-sdk-format .
+> ```
+
+### Network memory methods
+
+Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.
+
+To migrate, use regular memory APIs instead of network memory.
+
+```diff
+- import { MastraClient } from '@mastra/client-js';
+-
+- const client = new MastraClient({ baseUrl: '...' });
+- const networkThread = client.networkMemory.getThread('thread-id');
+- const networkThread = client.memory.networkThread('thread-id', 'network-id');
+- await networkThread.get();
+- await networkThread.getMessages();
+
++ // Use regular memory thread APIs instead
++ const client = new MastraClient({ baseUrl: '...' });
++ const thread = client.memory.getThread('thread-id');
++ await thread.get();
++ const messages = await thread.listMessages();
+```
+
+### Watch-related types
+
+Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.
+
+To migrate, use workflow streaming APIs instead of watch.
+
+```diff
+- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
+-
+- const workflow = client.getWorkflow('my-workflow');
+- const run = await workflow.createRun();
+- await run.watch((event: WatchEvent) => {
+-   console.log('Event:', event);
+- });
+
++ const workflow = client.getWorkflow('my-workflow');
++ const run = await workflow.createRun();
++ const stream = await run.stream({ inputData: { ... } });
++ for await (const chunk of stream) {
++   console.log('Event:', chunk);
++ }
+```
+
+### Run-related methods cannot be called directly on workflow instance
+
+Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using `createRun()` method.
+
+```diff
+- const result = await workflow.start({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const result = await run.start({ inputData: { ... } });
+```
+
+```diff
+- const result = await workflow.stream({ runId: '123', inputData: { ... } });
++ const run = await workflow.createRun({ runId: '123' });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
+
+The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.
+
+To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.
+
+```diff
++ const run = await workflow.createRun({ runId: '123' });
+- const stream = await run.streamVNext({ inputData: { ... } });
++ const stream = await run.stream({ inputData: { ... } });
+```
+
+### Deprecated stream endpoints
+
+Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.
+
+To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.
+
+```diff
+- const response = await fetch('/api/agents/my-agent/stream/vnext', {
+-   method: 'POST',
+-   body: JSON.stringify({ messages: [...] }),
+- });
+
++ const response = await fetch('/api/agents/my-agent/stream', {
++   method: 'POST',
++   body: JSON.stringify({ messages: [...] }),
++ });
++
++ // Or use @mastra/ai-sdk for UI message transformations
+```
+
+### Network memory API endpoints
+
+Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.
+
+To migrate, use regular memory API endpoints.
+
+```diff
+- const networkThread = await fetch('/api/memory/network/threads/thread-123');
++ const thread = await fetch('/api/memory/threads/thread-123');
+```
+
+### Eval-related client SDK types
+
+Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.
+
+To migrate, use the new scorers API instead of legacy evals.

package/.docs/guides/migrations/upgrade-to-v1/deployment.md

@@ -0,0 +1,37 @@
+# Deployment
+
+The `CloudflareDeployer` configuration has been updated to use standard `wrangler.json` property names.
+
+## Changed
+
+### CloudflareDeployer uses standard wrangler.json property names
+
+The `CloudflareDeployer` constructor now accepts standard `wrangler.json` property names instead of custom camelCase variants. This change aligns the deployer with Cloudflare's official configuration format and provides access to all wrangler configuration options.
+
+Deprecated fields are automatically migrated at runtime with console warnings, but you should update your code to use the new field names.
+
+```diff
+const deployer = new CloudflareDeployer({
+-   projectName: 'my-worker',
++   name: 'my-worker',
+-   d1Databases: [
++   d1_databases: [
+      {
+        binding: 'DB',
+        database_name: 'my-db',
+        database_id: 'xxx',
+      },
+    ],
+-   kvNamespaces: [
++   kv_namespaces: [
+      {
+        binding: 'KV',
+        id: 'yyy',
+      },
+    ],
+  });
+```
+
+The `workerNamespace` field has been removed as it is no longer used.
+
+For all available configuration options, see the [Wrangler configuration documentation](https://developers.cloudflare.com/workers/wrangler/configuration/).

package/.docs/guides/migrations/upgrade-to-v1/evals.md

@@ -0,0 +1,239 @@
+# Evals & Scorers
+
+The evaluation API has been consolidated on the new scorers system with updated naming conventions and configuration requirements.
+
+## Changed
+
+### `getScorers` to `listScorers`
+
+The `getScorers()` method has been renamed to `listScorers()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
+
+To migrate, replace all calls to `getScorers()` with `listScorers()`.
+
+```diff
+- const scorers = mastra.getScorers();
++ const scorers = mastra.listScorers();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+
+### `runExperiment` to `runEvals`
+
+The `runExperiment()` function has been renamed to `runEvals()`. This change provides clearer naming that better describes the evaluation functionality.
+
+To migrate, update function calls from `runExperiment` to `runEvals`.
+
+```diff
+- import { createScorer, runExperiment } from '@mastra/core/evals';
++ import { createScorer, runEvals } from '@mastra/core/evals';
+  import { myAgent } from './agents/my-agent';
+
+  const scorer = createScorer({
+    id: 'helpfulness-scorer',
+    // ...
+  });
+
+- const result = await runExperiment({ target: myAgent, scorers: [scorer], data: inputs });
++ const result = await runEvals({ target: myAgent, scorers: [scorer], data: inputs });
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/evals-run-experiment .
+> ```
+
+### `getScorerByName` to `getScorerById`
+
+The `getScorerByName()` method has been renamed to `getScorerById()`. Scorers now require an `id` field instead of `name`. This change aligns with the broader API pattern of using `id` for entity identification.
+
+To migrate, update method calls and scorer configuration to use `id` instead of `name`.
+
+```diff
+const scorer = createScorer({
+-   name: 'helpfulness-scorer',
++   id: 'helpfulness-scorer',
+    // ...
+  });
+
+- const scorer = mastra.getScorerByName('helpfulness-scorer');
++ const scorer = mastra.getScorerById('helpfulness-scorer');
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/evals-scorer-by-name .
+> ```
+
+### Scorer configuration from `name` to `id`
+
+Scorers now require an `id` field instead of `name`. The `name` field is now optional. This change provides consistency with other Mastra entities.
+
+To migrate, update scorer definitions to use `id` as the required field.
+
+```diff
+const scorer = createScorer({
+-   name: 'helpfulness-scorer',
++   id: 'helpfulness-scorer',
++   name: 'Helpfulness Scorer', // optional
+    // ...
+  });
+```
+
+### Storage score APIs to `listScoresBy*` pattern
+
+Score storage APIs have been renamed to follow the `listScoresBy*` pattern. This change aligns with the broader storage API naming conventions.
+
+To migrate, update score query methods to use the new naming pattern.
+
+```diff
+- const scores = await storage.getScores({ scorerName: 'helpfulness-scorer' });
++ const scores = await storage.listScoresByScorerId({
++   scorerId: 'helpfulness-scorer',
++ });
+
+// Also available:
+// - listScoresByRunId
+// - listScoresByEntityId
+// - listScoresBySpan
+```
+
+### Prebuilt scorer imports to `scorers/prebuilt` path
+
+Prebuilt scorer imports have been consolidated under a single `@mastra/evals/scorers/prebuilt` path instead of separate `scorers/llm` and `scorers/code` paths. This change simplifies imports and provides a clearer organization of prebuilt scorers.
+
+To migrate, update import statements to use the new `scorers/prebuilt` path.
+
+```diff
+// LLM-based scorers
+- import { createHallucinationScorer } from '@mastra/evals/scorers/llm';
+- import { createFaithfulnessScorer } from '@mastra/evals/scorers/llm';
++ import { createHallucinationScorer } from '@mastra/evals/scorers/prebuilt';
++ import { createFaithfulnessScorer } from '@mastra/evals/scorers/prebuilt';
+
+  // Code-based scorers
+- import { createContentSimilarityScorer } from '@mastra/evals/scorers/code';
+- import { createCompletenessScorer } from '@mastra/evals/scorers/code';
++ import { createContentSimilarityScorer } from '@mastra/evals/scorers/prebuilt';
++ import { createCompletenessScorer } from '@mastra/evals/scorers/prebuilt';
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/evals-prebuilt-imports .
+> ```
+
+### Scorer message types from `UIMessage` to `MastraDBMessage`
+
+Scorer input and output types now use `MastraDBMessage[]` instead of `UIMessage`. This change aligns scorers with the database-persisted message format for consistency across the framework.
+
+To migrate, update scorer implementations to use `MastraDBMessage` types and access message content through the nested `content` structure.
+
+```diff
+import type {
+    ScorerRunInputForAgent,
+    ScorerRunOutputForAgent
+  } from '@mastra/core/evals';
+
+- // ScorerRunInputForAgent uses UIMessage[]
+- const inputMessages: UIMessage[] = run.input.inputMessages;
++ // ScorerRunInputForAgent now uses MastraDBMessage[]
++ import type { MastraDBMessage } from '@mastra/core/agent';
++ const inputMessages: MastraDBMessage[] = run.input.inputMessages;
+```
+
+### Message content structure to nested format
+
+Tool invocations and text content are now accessed through a nested `content` object structure instead of being flat properties on the message. This change provides better type safety and aligns with the database message format.
+
+To migrate, access tool invocations via `message.content.toolInvocations` and text via `message.content.content` or use the `getTextContentFromMastraDBMessage()` helper.
+
+```diff
++ import { getTextContentFromMastraDBMessage } from '@mastra/evals';
++
+  const run = await scorer.run(testRun);
+
+  // Accessing text content
+- const text = message.content;
++ const text = getTextContentFromMastraDBMessage(message);
++ // or directly: message.content.content
+
+  // Accessing tool invocations
+- const toolCalls = message.toolInvocations;
++ const toolCalls = message.content.toolInvocations;
+```
+
+## Removed
+
+### Legacy evals code
+
+Legacy evals code has been removed from `@mastra/core`. This includes legacy evaluation metrics, scorer/judge modules, and hook-based automatic evaluation code. This change simplifies the codebase by removing outdated evaluation approaches.
+
+To migrate, use the new evals/scorers API in `@mastra/core/evals` or `@mastra/evals`.
+
+```diff
+- // Legacy evals APIs
++ import { createScorer, runEvals } from '@mastra/core/evals';
++
++ const scorer = createScorer({
++   id: 'my-scorer',
++   // Use new scorer API
++ });
+```
+
+### Agent `TMetrics` generic parameter
+
+The `TMetrics` generic parameter has been removed from `AgentConfig` and the `Agent` constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system. This change simplifies the Agent type signature.
+
+To migrate, remove the `TMetrics` generic parameter and configure scorers using the scorers API.
+
+```diff
+- const agent = new Agent<AgentId, Tools, Metrics>({
++ const agent = new Agent<AgentId, Tools>({
+    // ...
+  });
+```
+
+### Evals-related type exports
+
+Several evals-related type exports have been removed including `DeprecatedOutputOptions`, `Metric`, and processor option types. These types are now internal or have been replaced by the new scorers API. This change reduces API surface area.
+
+To migrate, remove references to these removed types and use the new scorers API.
+
+```diff
+- import type {
+-   DeprecatedOutputOptions,
+-   Metric,
+-   LanguageDetectorOptions,
+-   ModerationOptions,
+- } from '@mastra/core';
++ // Use new scorers API types
++ import type { Scorer } from '@mastra/core/evals';
+```
+
+### `createUIMessage` test helper
+
+The `createUIMessage()` test helper has been removed and replaced with `createTestMessage()`. The new helper creates `MastraDBMessage` objects with the nested content structure and supports optional tool invocations. This change aligns test utilities with the new message format.
+
+To migrate, replace `createUIMessage()` calls with `createTestMessage()` and update to use `MastraDBMessage` types.
+
+```diff
+- import { createUIMessage } from '@mastra/evals';
++ import { createTestMessage } from '@mastra/evals';
+
+  // Creating test messages
+- const message = createUIMessage({
+-   id: 'test-1',
++ const message = createTestMessage({
++   id: 'test-1', // optional, defaults to 'test-message'
+    role: 'user',
+    content: 'Hello',
+    toolInvocations: [], // optional
+  });
+```