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');
  

@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'

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 overloads. All step types now support retry and evaluation configurations.

@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)

@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. ()

@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
      },
    },
  });
  

@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

@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
      },
    },
  });
  

@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)

@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