Changelog

@mastra/ai-sdk@1.0.0-beta.13

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fixed agent network not returning text response when routing agent handles requests without delegation. (#11497)

  What changed:

  • Agent networks now correctly stream text responses when the routing agent decides to handle a request itself instead of delegating to sub-agents, workflows, or tools
  • Added fallback in transformers to ensure text is always returned even if core events are missing

  Why this matters:
  Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.

  Fixes #11219

• Refactor the MessageList class from ~4000 LOC monolith to ~850 LOC with focused, single-responsibility modules. This improves maintainability, testability, and makes the codebase easier to understand. (#11658)

  • Extract message format adapters (AIV4Adapter, AIV5Adapter) for SDK conversions
  • Extract TypeDetector for centralized message format identification
  • Extract MessageStateManager for tracking message sources and persistence
  • Extract MessageMerger for streaming message merge logic
  • Extract StepContentExtractor for step content extraction
  • Extract CacheKeyGenerator for message deduplication
  • Consolidate provider compatibility utilities (Gemini, Anthropic, OpenAI)

  message-list/
  ├── message-list.ts        # Main class (~850 LOC, down from ~4000)
  ├── adapters/              # SDK format conversions
  │   ├── AIV4Adapter.ts     # MastraDBMessage <-> AI SDK V4
  │   └── AIV5Adapter.ts     # MastraDBMessage <-> AI SDK V5
  ├── cache/
  │   └── CacheKeyGenerator.ts  # Deduplication keys
  ├── conversion/
  │   ├── input-converter.ts    # Any format -> MastraDBMessage
  │   ├── output-converter.ts   # MastraDBMessage -> SDK formats
  │   ├── step-content.ts       # Step content extraction
  │   └── to-prompt.ts          # LLM prompt formatting
  ├── detection/
  │   └── TypeDetector.ts       # Format identification
  ├── merge/
  │   └── MessageMerger.ts      # Streaming merge logic
  ├── state/
  │   └── MessageStateManager.ts # Source & persistence tracking
  └── utils/
      └── provider-compat.ts    # Provider-specific fixes
  

• Fix autoresume not working fine in useChat (#11486)

@mastra/arize@1.0.0-beta.11

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/astra@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/auth@1.0.0-beta.2

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/braintrust@1.0.0-beta.11

Minor Changes

• Formats messages in MODEL_GENERATION spans properly so the Thread view renders correctly. (#11613)

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Improves AI SDK message conversion for Braintrust Thread view: (#11673)

  • Adds support for non-text content types (images, files, reasoning) with informative placeholders
  • Handles both AI SDK v4 result and v5 output fields for tool results
  • Gracefully handles empty content arrays and unknown content types
  • Adds comprehensive TypeScript type definitions for message conversion

@mastra/chroma@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/clickhouse@1.0.0-beta.9

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/client-js@1.0.0-beta.20

Minor Changes

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)

  + const run = await workflow.createRun({ runId: '123' });
  - const stream = await run.streamVNext({ inputData: { ... } });
  + const stream = await run.stream({ inputData: { ... } });

• Add initial state input to workflow form in studio (#11560)

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

• Make agentId optional for memory read operations (getThread, listThreads, listMessages) (#11540)

  When workflows use multiple agents sharing the same threadId/resourceId, users can now retrieve threads and messages without specifying an agentId. The server falls back to using storage directly when agentId is not provided.

@mastra/cloudflare@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/cloudflare-d1@1.0.0-beta.9

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/codemod@0.1.0-beta.5

Patch Changes

• Breaking Change: memory.readOnly has been moved to memory.options.readOnly (#11523)

  The readOnly option now lives inside memory.options alongside other memory configuration like lastMessages and semanticRecall.

  Before:

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
      readOnly: true,
    },
  });

  After:

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
      options: {
        readOnly: true,
      },
    },
  });

  Migration: Run the codemod to update your code automatically:

  npx @mastra/codemod@beta v1/memory-readonly-to-options .

  This also fixes issue #11519 where readOnly: true was being ignored and messages were saved to memory anyway.

@mastra/convex@0.1.0-beta.8

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/core@1.0.0-beta.20

Minor Changes

• Deprecate default: { enabled: true } observability configuration (#11674)

  The shorthand default: { enabled: true } configuration is now deprecated and will be removed in a future version. Users should migrate to explicit configuration with DefaultExporter, CloudExporter, and SensitiveDataFilter.

  Before (deprecated):

  import { Observability } from '@mastra/observability';
  
  const mastra = new Mastra({
    observability: new Observability({
      default: { enabled: true },
    }),
  });

  After (recommended):

  import { Observability, DefaultExporter, CloudExporter, SensitiveDataFilter } from '@mastra/observability';
  
  const mastra = new Mastra({
    observability: new Observability({
      configs: {
        default: {
          serviceName: 'mastra',
          exporters: [new DefaultExporter(), new CloudExporter()],
          spanOutputProcessors: [new SensitiveDataFilter()],
        },
      },
    }),
  });

  The explicit configuration makes it clear exactly what exporters and processors are being used, improving code readability and maintainability.

  A deprecation warning will be logged when using the old configuration pattern.

• Fix processor tracing to create individual spans per processor (#11683)

  • Processor spans now correctly show processor IDs (e.g., input processor: validator) instead of combined workflow IDs
  • Each processor in a chain gets its own trace span, improving observability into processor execution
  • Spans are only created for phases a processor actually implements, eliminating empty spans
  • Internal agent calls within processors now properly nest under their processor span
  • Added INPUT_STEP_PROCESSOR and OUTPUT_STEP_PROCESSOR entity types for finer-grained tracing
  • Changed processorType span attribute to processorExecutor with values 'workflow' or 'legacy'

• Add completion validation to agent networks using custom scorers (#11562)

  You can now validate whether an agent network has completed its task by passing MastraScorers to agent.network(). When validation fails, the network automatically retries with feedback injected into the conversation.

  Example: Creating a scorer to verify test coverage

  import { createScorer } from '@mastra/core/evals';
  import { z } from 'zod';
  
  // Create a scorer that checks if tests were written
  const testsScorer = createScorer({
    id: 'tests-written',
    description: 'Validates that unit tests were included in the response',
    type: 'agent',
  }).generateScore({
    description: 'Return 1 if tests are present, 0 if missing',
    outputSchema: z.number(),
    createPrompt: ({ run }) => `
      Does this response include unit tests?
      Response: ${run.output}
      Return 1 if tests are present, 0 if not.
    `,
  });
  
  // Use the scorer with agent.network()
  const stream = await agent.network('Implement a fibonacci function with tests', {
    completion: {
      scorers: [testsScorer],
      strategy: 'all', // all scorers must pass (score >= 0.5)
    },
    maxSteps: 3,
  });

  What this enables:

  • Programmatic completion checks: Define objective criteria for task completion instead of relying on the default LLM-based check
  • Automatic retry with feedback: When a scorer returns score: 0, its reason is injected into the conversation so the network can address the gap on the next iteration
  • Composable validation: Combine multiple scorers with strategy: 'all' (all must pass) or strategy: 'any' (at least one must pass)

  This replaces guesswork with reliable, repeatable validation that ensures agent networks produce outputs meeting your specific requirements.

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Add support for retries and scorers parameters across all createStep overloads.
  (#11495)

  The createStep function now includes support for the retries and scorers fields across all step creation patterns, enabling step-level retry configuration and AI evaluation support for regular steps, agent-based steps, and tool-based steps.

  import { init } from '@mastra/inngest';
  import { z } from 'zod';
  
  const { createStep } = init(inngest);
  
  // 1. Regular step with retries
  const regularStep = createStep({
    id: 'api-call',
    inputSchema: z.object({ url: z.string() }),
    outputSchema: z.object({ data: z.any() }),
    retries: 3, // ← Will retry up to 3 times on failure
    execute: async ({ inputData }) => {
      const response = await fetch(inputData.url);
      return { data: await response.json() };
    },
  });
  
  // 2. Agent step with retries and scorers
  const agentStep = createStep(myAgent, {
    retries: 3,
    scorers: [{ id: 'accuracy-scorer', scorer: myAccuracyScorer }],
  });
  
  // 3. Tool step with retries and scorers
  const toolStep = createStep(myTool, {
    retries: 2,
    scorers: [{ id: 'quality-scorer', scorer: myQualityScorer }],
  });

  This change ensures API consistency across all createStep overloads. All step types now support retry and evaluation configurations.

  This is a non-breaking change - steps without these parameters continue to work exactly as before.

  Fixes #9351

• Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)

  + const run = await workflow.createRun({ runId: '123' });
  - const stream = await run.streamVNext({ inputData: { ... } });
  + const stream = await run.stream({ inputData: { ... } });

• Fix workflow tool not executing when requireApproval is true and tool call is approved (#11538)

• Breaking Change: memory.readOnly has been moved to memory.options.readOnly (#11523)

  The readOnly option now lives inside memory.options alongside other memory configuration like lastMessages and semanticRecall.

  Before:

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
      readOnly: true,
    },
  });

  After:

  agent.stream('Hello', {
    memory: {
      thread: threadId,
      resource: resourceId,
      options: {
        readOnly: true,
      },
    },
  });

  Migration: Run the codemod to update your code automatically:

  npx @mastra/codemod@beta v1/memory-readonly-to-options .

  This also fixes issue #11519 where readOnly: true was being ignored and messages were saved to memory anyway.

• Fix agent runs with multiple steps only showing last text chunk in observability tools (#11672)

  When an agent model executes multiple steps and generates multiple text chunks, the onFinish payload was only receiving the text from the last step instead of all accumulated text. This caused observability tools like Braintrust to only display the final text chunk. The fix now correctly concatenates all text chunks from all steps.

• Fix tool input validation destroying non-plain objects (#11541)

  The convertUndefinedToNull function in tool input validation was treating all objects as plain objects and recursively processing them. For objects like Date, Map, URL, and class instances, this resulted in empty objects {} because they have no enumerable own properties.

  This fix changes the approach to only recurse into plain objects (objects with Object.prototype or null prototype). All other objects (Date, Map, Set, URL, RegExp, Error, custom class instances, etc.) are now preserved as-is.

  Fixes #11502

• Fixed client-side tool invocations not being stored in memory. Previously, tool invocations with state 'call' were filtered out before persistence, which incorrectly removed client-side tools. Now only streaming intermediate states ('partial-call') are filtered. (#11630)

  Fixed a crash when updating working memory with an empty or null update; existing data is now preserved.

• Fixed memory readOnly option not being respected when agents share a RequestContext. Previously, when output processors were resolved, the readOnly check happened too early - before the agent could set its own MastraMemory context. This caused child agents to inherit their parent's readOnly setting when sharing a RequestContext. (#11653)

  The readOnly check is now only done at execution time in each processor's processOutputResult method, allowing proper isolation.

• Fix network validation not seeing previous iteration results in multi-step tasks (#11691)

  The validation LLM was unable to determine task completion for multi-step tasks because it couldn't see what primitives had already executed. Now includes a compact list of completed primitives in the validation prompt.

• Fix provider-executed tools (like openai.tools.webSearch()) not working correctly with AI SDK v6 models. The agent's generate() method was ending prematurely with finishReason: 'tool-calls' instead of completing with a text response after tool execution. (#11622)

  The issue was that V6 provider tools have type: 'provider' while V5 uses type: 'provider-defined'. The tool preparation code now detects the model version and uses the correct type.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

• fix(core): support LanguageModelV3 in MastraModelGateway.resolveLanguageModel (#11489)

• Fixed agent network not returning text response when routing agent handles requests without delegation. (#11497)

  What changed:

  • Agent networks now correctly stream text responses when the routing agent decides to handle a request itself instead of delegating to sub-agents, workflows, or tools
  • Added fallback in transformers to ensure text is always returned even if core events are missing

  Why this matters:
  Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.

  Fixes #11219

• Add initial state input to workflow form in studio (#11560)

• Added missing stream types to @mastra/core/stream for better TypeScript support (#11513)

  New types available:

  • Chunk types: ToolCallChunk, ToolResultChunk, SourceChunk, FileChunk, ReasoningChunk
  • Payload types: ToolCallPayload, ToolResultPayload, TextDeltaPayload, ReasoningDeltaPayload, FilePayload, SourcePayload
  • JSON utilities: JSONValue, JSONObject, JSONArray and readonly variants

  These types are now properly exported, enabling full TypeScript IntelliSense when working with streaming data.

• Refactor the MessageList class from ~4000 LOC monolith to ~850 LOC with focused, single-responsibility modules. This improves maintainability, testability, and makes the codebase easier to understand. (#11658)

  • Extract message format adapters (AIV4Adapter, AIV5Adapter) for SDK conversions
  • Extract TypeDetector for centralized message format identification
  • Extract MessageStateManager for tracking message sources and persistence
  • Extract MessageMerger for streaming message merge logic
  • Extract StepContentExtractor for step content extraction
  • Extract CacheKeyGenerator for message deduplication
  • Consolidate provider compatibility utilities (Gemini, Anthropic, OpenAI)

  message-list/
  ├── message-list.ts        # Main class (~850 LOC, down from ~4000)
  ├── adapters/              # SDK format conversions
  │   ├── AIV4Adapter.ts     # MastraDBMessage <-> AI SDK V4
  │   └── AIV5Adapter.ts     # MastraDBMessage <-> AI SDK V5
  ├── cache/
  │   └── CacheKeyGenerator.ts  # Deduplication keys
  ├── conversion/
  │   ├── input-converter.ts    # Any format -> MastraDBMessage
  │   ├── output-converter.ts   # MastraDBMessage -> SDK formats
  │   ├── step-content.ts       # Step content extraction
  │   └── to-prompt.ts          # LLM prompt formatting
  ├── detection/
  │   └── TypeDetector.ts       # Format identification
  ├── merge/
  │   └── MessageMerger.ts      # Streaming merge logic
  ├── state/
  │   └── MessageStateManager.ts # Source & persistence tracking
  └── utils/
      └── provider-compat.ts    # Provider-specific fixes
  

• Resolve suspendPayload when tripwire is set off in agentic loop to prevent unresolved promises hanging. (#11621)

• Fix OpenAI reasoning model + memory failing on second generate with "missing item" error (#11492)

  When using OpenAI reasoning models with memory enabled, the second agent.generate() call would fail with: "Item 'rs_...' of type 'reasoning' was provided without its required following item."

  The issue was that text-start events contain providerMetadata with the text's itemId (e.g., msg_xxx), but this metadata was not being captured. When memory replayed the conversation, the reasoning part had its rs_ ID but the text part was missing its msg_ ID, causing OpenAI to reject the request.

  The fix adds handlers for text-start (to capture text providerMetadata) and text-end (to clear it and prevent leaking into subsequent parts).

  Fixes #11481

• Fix reasoning content being lost when text-start chunk arrives before reasoning-end (#11494)

  Some model providers (e.g., ZAI/glm-4.6) return streaming chunks where text-start arrives before reasoning-end. Previously, this would clear the accumulated reasoning deltas, resulting in empty reasoning content in the final message. Now text-start is properly excluded from triggering the reasoning state reset, allowing reasoning-end to correctly save the reasoning content.

• Add resumeGenerate method for resuming agent via generate (#11503)
  Add runId and suspendPayload to fullOutput of agent stream
  Default suspendedToolRunId to empty string to prevent null issue

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

• Fix runEvals() to automatically save scores to storage, making them visible in Studio observability. (#11516)

  Previously, runEvals() would calculate scores but not persist them to storage, requiring users to manually implement score saving via the onItemComplete callback. Scores now automatically save when the target (Agent/Workflow) has an associated Mastra instance with storage configured.

  What changed:

  • Scores are now automatically saved to storage after each evaluation run
  • Fixed compatibility with both Agent (getMastraInstance()) and Workflow (.mastra getter)
  • Saved scores include complete context: groundTruth (in additionalContext), requestContext, traceId, and spanId
  • Scores are marked with source: 'TEST' to distinguish them from live scoring

  Migration:
  No action required. The onItemComplete workaround for saving scores can be removed if desired, but will continue to work for custom logic.

  Example:

  const result = await runEvals({
    target: mastra.getWorkflow("myWorkflow"),
    data: [{ input: {...}, groundTruth: {...} }],
    scorers: [myScorer],
  });
  // Scores are now automatically saved and visible in Studio!

• Fix autoresume not working fine in useChat (#11486)

@mastra/couchbase@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/deployer@1.0.0-beta.20

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fixed module resolution failing on Windows with ERR_INVALID_URL_SCHEME errors. Windows absolute paths (e.g., C:\path\to\file) are now correctly skipped during node_modules resolution instead of being treated as package names. (#11639)

• Add Bun runtime detection for bundler platform selection (#11548)

  When running under Bun, the bundler now uses neutral esbuild platform instead of node to preserve Bun-specific globals (like Bun.s3). This fixes compatibility issues where Bun APIs were being incorrectly transformed during the build process.

• Improved file persistence in dev mode. Files created by mastra dev are now saved in the public directory, so you can commit them to version control or ignore them via .gitignore. (#11234)

• Fixed Windows crash where the Mastra dev server failed to start with ERR_UNSUPPORTED_ESM_URL_SCHEME error. The deployer now correctly handles Windows file paths. (#11340)

@mastra/deployer-cloudflare@1.0.0-beta.2

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/deployer-netlify@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/deployer-vercel@1.0.0-beta.2

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/duckdb@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/dynamodb@1.0.0-beta.9

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/elasticsearch@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/evals@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Users no longer need to install the ai package as a peer dependency; this package now includes the necessary types internally. (#11625)

@mastra/express@0.1.0-beta.15

Minor Changes

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fixed inconsistent query parameter handling across server adapters. (#11429)

  What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.

  Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.

  User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.

@mastra/fastembed@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/fastify@0.1.0-beta.15

Minor Changes

• feat: Add Fastify and Koa server adapters (#11568)

  Introduces two new server adapters for Mastra:

  • @mastra/fastify: Enables running Mastra applications on Fastify
  • @mastra/koa: Enables running Mastra applications on Koa

  Both adapters provide full MastraServerBase implementation including route registration, streaming responses, multipart uploads, auth middleware, and MCP transport support.

  Usage

  Fastify

  import Fastify from 'fastify';
  import { MastraServer } from '@mastra/fastify';
  import { mastra } from './mastra';
  
  const app = Fastify();
  const server = new MastraServer({ app, mastra });
  
  await server.init();
  
  app.listen({ port: 4111 });

  Koa

  import Koa from 'koa';
  import bodyParser from 'koa-bodyparser';
  import { MastraServer } from '@mastra/koa';
  import { mastra } from './mastra';
  
  const app = new Koa();
  app.use(bodyParser());
  
  const server = new MastraServer({ app, mastra });
  
  await server.init();
  
  app.listen(4111);

Patch Changes

• Fixed inconsistent query parameter handling across server adapters. (#11429)

  What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.

  Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.

  User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.

@mastra/hono@0.1.0-beta.15

Minor Changes

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fixed inconsistent query parameter handling across server adapters. (#11429)

  What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.

  Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.

  User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.

@mastra/inngest@1.0.0-beta.11

Patch Changes

• Add support for retries and scorers parameters across all createStep overloads.
  (#11495)

  The createStep function now includes support for the retries and scorers fields across all step creation patterns, enabling step-level retry configuration and AI evaluation support for regular steps, agent-based steps, and tool-based steps.

  import { init } from '@mastra/inngest';
  import { z } from 'zod';
  
  const { createStep } = init(inngest);
  
  // 1. Regular step with retries
  const regularStep = createStep({
    id: 'api-call',
    inputSchema: z.object({ url: z.string() }),
    outputSchema: z.object({ data: z.any() }),
    retries: 3, // ← Will retry up to 3 times on failure
    execute: async ({ inputData }) => {
      const response = await fetch(inputData.url);
      return { data: await response.json() };
    },
  });
  
  // 2. Agent step with retries and scorers
  const agentStep = createStep(myAgent, {
    retries: 3,
    scorers: [{ id: 'accuracy-scorer', scorer: myAccuracyScorer }],
  });
  
  // 3. Tool step with retries and scorers
  const toolStep = createStep(myTool, {
    retries: 2,
    scorers: [{ id: 'quality-scorer', scorer: myQualityScorer }],
  });

  This change ensures API consistency across all createStep overloads. All step types now support retry and evaluation configurations.

  This is a non-breaking change - steps without these parameters continue to work exactly as before.

  Fixes #9351

• Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)

  + const run = await workflow.createRun({ runId: '123' });
  - const stream = await run.streamVNext({ inputData: { ... } });
  + const stream = await run.stream({ inputData: { ... } });

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

• Add cron scheduling support to Inngest workflows. Workflows can now be automatically triggered on a schedule by adding a cron property along with optional inputData and initialState: (#11518)

  const workflow = createWorkflow({
    id: 'scheduled-workflow',
    inputSchema: z.object({ value: z.string() }),
    outputSchema: z.object({ result: z.string() }),
    steps: [step1],
    cron: '0 0 * * *', // Run daily at midnight
    inputData: { value: 'scheduled-run' }, // Optional inputData for the scheduled workflow run
    initialState: { count: 0 }, // Optional initialState for the scheduled workflow run
  });

@mastra/koa@0.1.0-beta.15

Minor Changes

• feat: Add Fastify and Koa server adapters (#11568)

  Introduces two new server adapters for Mastra:

  • @mastra/fastify: Enables running Mastra applications on Fastify
  • @mastra/koa: Enables running Mastra applications on Koa

  Both adapters provide full MastraServerBase implementation including route registration, streaming responses, multipart uploads, auth middleware, and MCP transport support.

  Usage

  Fastify

  import Fastify from 'fastify';
  import { MastraServer } from '@mastra/fastify';
  import { mastra } from './mastra';
  
  const app = Fastify();
  const server = new MastraServer({ app, mastra });
  
  await server.init();
  
  app.listen({ port: 4111 });

  Koa

  import Koa from 'koa';
  import bodyParser from 'koa-bodyparser';
  import { MastraServer } from '@mastra/koa';
  import { mastra } from './mastra';
  
  const app = new Koa();
  app.use(bodyParser());
  
  const server = new MastraServer({ app, mastra });
  
  await server.init();
  
  app.listen(4111);

Patch Changes

• Fixed inconsistent query parameter handling across server adapters. (#11429)

  What changed: Query parameters are now processed consistently across all server adapters (Express, Hono, Fastify, Koa). Added internal helper normalizeQueryParams and ParsedRequestParams type to @mastra/server for adapter implementations.

  Why: Different HTTP frameworks handle query parameters differently - some return single strings while others return arrays for repeated params like ?tag=a&tag=b. This caused type inconsistencies that could lead to validation failures in certain adapters.

  User impact: None for typical usage - HTTP endpoints and client SDK behavior are unchanged. If you extend server adapter classes and override getParams or parseQueryParams, update your implementation to use Record<string, string | string[]> for query parameters.

@mastra/lance@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/langfuse@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/langsmith@1.0.0-beta.11

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/libsql@1.0.0-beta.11

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

@mastra/loggers@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/mcp@1.0.0-beta.8

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/memory@1.0.0-beta.11

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fixed client-side tool invocations not being stored in memory. Previously, tool invocations with state 'call' were filtered out before persistence, which incorrectly removed client-side tools. Now only streaming intermediate states ('partial-call') are filtered. (#11630)

  Fixed a crash when updating working memory with an empty or null update; existing data is now preserved.

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

@mastra/mongodb@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/mssql@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

@mastra/observability@1.0.0-beta.10

Minor Changes

• Deprecate default: { enabled: true } observability configuration (#11674)

  The shorthand default: { enabled: true } configuration is now deprecated and will be removed in a future version. Users should migrate to explicit configuration with DefaultExporter, CloudExporter, and SensitiveDataFilter.

  Before (deprecated):

  import { Observability } from '@mastra/observability';
  
  const mastra = new Mastra({
    observability: new Observability({
      default: { enabled: true },
    }),
  });

  After (recommended):

  import { Observability, DefaultExporter, CloudExporter, SensitiveDataFilter } from '@mastra/observability';
  
  const mastra = new Mastra({
    observability: new Observability({
      configs: {
        default: {
          serviceName: 'mastra',
          exporters: [new DefaultExporter(), new CloudExporter()],
          spanOutputProcessors: [new SensitiveDataFilter()],
        },
      },
    }),
  });

  The explicit configuration makes it clear exactly what exporters and processors are being used, improving code readability and maintainability.

  A deprecation warning will be logged when using the old configuration pattern.

• Fix processor tracing to create individual spans per processor (#11683)

  • Processor spans now correctly show processor IDs (e.g., input processor: validator) instead of combined workflow IDs
  • Each processor in a chain gets its own trace span, improving observability into processor execution
  • Spans are only created for phases a processor actually implements, eliminating empty spans
  • Internal agent calls within processors now properly nest under their processor span
  • Added INPUT_STEP_PROCESSOR and OUTPUT_STEP_PROCESSOR entity types for finer-grained tracing
  • Changed processorType span attribute to processorExecutor with values 'workflow' or 'legacy'

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Fix trace-level sampling to sample entire traces instead of individual spans (#11676)

  Previously, sampling decisions were made independently for each span, causing fragmented traces where some spans were sampled and others were not. This defeated the purpose of ratio or custom sampling strategies.

  Now:

  • Sampling decisions are made once at the root span level
  • Child spans inherit the sampling decision from their parent
  • Custom samplers are only called once per trace (for root spans)
  • Either all spans in a trace are sampled, or none are

  Fixes #11504

@mastra/opensearch@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/otel-bridge@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/otel-exporter@1.0.0-beta.11

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/pg@1.0.0-beta.12

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

• Added startExclusive and endExclusive options to dateRange filter for message queries. (#11479)

  What changed: The filter.dateRange parameter in listMessages() and Memory.recall() now supports startExclusive and endExclusive boolean options. When set to true, messages with timestamps exactly matching the boundary are excluded from results.

  Why this matters: Enables cursor-based pagination for chat applications. When new messages arrive during a session, offset-based pagination can skip or duplicate messages. Using endExclusive: true with the oldest message's timestamp as a cursor ensures consistent pagination without gaps or duplicates.

  Example:

  // Get first page
  const page1 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
  });
  
  // Get next page using cursor-based pagination
  const oldestMessage = page1.messages[page1.messages.length - 1];
  const page2 = await memory.recall({
    threadId: 'thread-123',
    perPage: 10,
    orderBy: { field: 'createdAt', direction: 'DESC' },
    filter: {
      dateRange: {
        end: oldestMessage.createdAt,
        endExclusive: true, // Excludes the cursor message
      },
    },
  });

• Fix thread timestamps being returned in incorrect timezone from listThreadsByResourceId (#11498)

  The method was not using the timezone-aware columns (createdAtZ/updatedAtZ), causing timestamps to be interpreted in local timezone instead of UTC. Now correctly uses TIMESTAMPTZ columns with fallback for legacy data.

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

@mastra/pinecone@1.0.0-beta.4

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/playground-ui@7.0.0-beta.20

Patch Changes

• Add missing loading state handlers to TanStack Query hooks. Components now properly show skeleton/loading UI instead of returning null or rendering incomplete states while data is being fetched. (#11681)

• Remove streamVNext, resumeStreamVNext, and observeStreamVNext methods, call stream, resumeStream and observeStream directly (#11499)

  + const run = await workflow.createRun({ runId: '123' });
  - const stream = await run.streamVNext({ inputData: { ... } });
  + const stream = await run.stream({ inputData: { ... } });

• Dedupe Avatar component by removing UI avatar and using DS Avatar with size variants (#11637)

• Consolidate date picker components by removing duplicate DatePicker and Calendar components. DateField now uses the DayPicker wrapper from date-time-picker folder directly. (#11649)

• Consolidate tabs components: remove redundant implementations and add onClose prop support (#11650)

• Use the same Button component every where. Remove duplicates. (#11635)

• Add initial state input to workflow form in studio (#11560)

• Remove unused files and dependencies identified by Knip (#11677)

• Fix react/react-DOM version mismatch. (#11620)

• Adds thread cloning to create independent copies of conversations that can diverge. (#11517)

  // Clone a thread
  const { thread, clonedMessages } = await memory.cloneThread({
    sourceThreadId: 'thread-123',
    title: 'My Clone',
    options: {
      messageLimit: 10, // optional: only copy last N messages
    },
  });
  
  // Check if a thread is a clone
  if (memory.isClone(thread)) {
    const source = await memory.getSourceThread(thread.id);
  }
  
  // List all clones of a thread
  const clones = await memory.listClones('thread-123');

  Includes:

  • Storage implementations for InMemory, PostgreSQL, LibSQL, Upstash
  • API endpoint: POST /api/memory/threads/:threadId/clone
  • Embeddings created for cloned messages (semantic recall)
  • Clone button in playground UI Memory tab

• Display network completion validation results and scorer feedback in the Playground when viewing agent network runs, letting users see pass/fail status and actionable feedback from completion scorers (#11562)

• Unified getWorkflowRunById and getWorkflowRunExecutionResult into a single API that returns WorkflowState with both metadata and execution state. (#11429)

  What changed:

  • getWorkflowRunById now returns a unified WorkflowState object containing metadata (runId, workflowName, resourceId, createdAt, updatedAt) along with processed execution state (status, result, error, payload, steps)
  • Added optional fields parameter to request only specific fields for better performance
  • Added optional withNestedWorkflows parameter to control nested workflow step inclusion
  • Removed getWorkflowRunExecutionResult - use getWorkflowRunById instead (breaking change)
  • Removed /execution-result API endpoints from server (breaking change)
  • Removed runExecutionResult() method from client SDK (breaking change)
  • Removed GetWorkflowRunExecutionResultResponse type from client SDK (breaking change)

  Before:

  // Had to call two different methods for different data
  const run = await workflow.getWorkflowRunById(runId); // Returns raw WorkflowRun with snapshot
  const result = await workflow.getWorkflowRunExecutionResult(runId); // Returns processed execution state

  After:

  // Single method returns everything
  const run = await workflow.getWorkflowRunById(runId);
  // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
  
  // Request only specific fields for better performance (avoids expensive step fetching)
  const status = await workflow.getWorkflowRunById(runId, { fields: ['status'] });
  
  // Skip nested workflow steps for faster response
  const run = await workflow.getWorkflowRunById(runId, { withNestedWorkflows: false });

  Why: The previous API required calling two separate methods to get complete workflow run information. This unification simplifies the API surface and gives users control over performance - fetching all steps (especially nested workflows) can be expensive, so the fields and withNestedWorkflows options let users request only what they need.

@mastra/posthog@1.0.0-beta.10

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/qdrant@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/rag@2.0.0-beta.5

Minor Changes

• Add dynamic vectorStore resolver support for multi-tenant applications (#11542)

  The vectorStore option in createVectorQueryTool and createGraphRAGTool now accepts a resolver function in addition to static instances. This enables multi-tenant setups where each tenant has isolated data in separate PostgreSQL schemas.

  Also improves providerOptions type safety by using MastraEmbeddingOptions types instead of a generic Record type.

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

@mastra/react-hooks@0.1.0-beta.20

Patch Changes

• Fix TypeScript errors during build declaration generation (#11682)

  Updated test file toUIMessage.test.ts to match current @mastra/core types:

  • Changed error property from string to Error object (per StepFailure type)
  • Added missing resumeSchema property to tool-call-approval payloads (per ToolCallApprovalPayload type)
  • Added zod as peer/dev dependency for test type support

• Fixed agent network not returning text response when routing agent handles requests without delegation. (#11497)

  What changed:

  • Agent networks now correctly stream text responses when the routing agent decides to handle a request itself instead of delegating to sub-agents, workflows, or tools
  • Added fallback in transformers to ensure text is always returned even if core events are missing

  Why this matters:
  Previously, when using toAISdkV5Stream or networkRoute() outside of the Mastra Studio UI, no text content was returned when the routing agent handled requests directly. This fix ensures consistent behavior across all API routes.

  Fixes #11219

• Display network completion validation results and scorer feedback in the Playground when viewing agent network runs, letting users see pass/fail status and actionable feedback from completion scorers (#11562)

@mastra/s3vectors@1.0.0-beta.3

Patch Changes

• Add embedded documentation support for Mastra packages (#11472)

  Mastra packages now include embedded documentation in the published npm package under dist/docs/. This enables coding agents and AI assistants to understand and use the framework by reading documentation directly from node_modules.

  Each package includes:

  • SKILL.md - Entry point explaining the package's purpose and capabilities
  • SOURCE_MAP.json - Machine-readable index mapping exports to types and implementation files
  • Topic folders - Conceptual documentation organized by feature area

  Documentation is driven by the packages frontmatter field in MDX files, which maps docs to their corresponding packages. CI validation ensures all docs include this field.

Note: Release notes were truncated due to GitHub's 125,000 character limit. See the full changelog details at the link below.

Full Changelog: b3e7a74