Changelog

@mastra/agent-builder@1.0.0-beta.13

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

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

Major Changes

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

@mastra/arize@1.0.0-beta.13

Patch Changes

• Fixed formatting of model_step, model_chunk, and tool_call spans in Arize Exporter. (#11922)

  Also removed tools output from model_step spans for all exporters.

• Improved tracing by filtering infrastructure chunks from model streams and adding success attribute to tool spans. (#11943)

  Added generic input/output attribute mapping for additional span types in Arize exporter.

@mastra/braintrust@1.0.0-beta.13

Minor Changes

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

Patch Changes

• Fix logFeedback() not working because span_id differs from row id. (#11927)

  Problem: When using BraintrustExporter, user feedback intended for specific agent responses appeared as separate rows in Braintrust rather than being attached to the original generation. The startSpan() call passed spanId: span.id but omitted the event: { id: span.id } parameter, causing Braintrust to auto-generate a different UUID for the row id field.

  Solution: Add event: { id: span.id } to the startSpan() call so that the Mastra span ID is used as both the Braintrust span_id and row id. This allows logFeedback({ id: span.id }) to correctly attach feedback to existing records.

• Fix Thread view truncation in Braintrust when LLM generations include tool calls. (#11984)

  The Braintrust exporter now reconstructs LLM output in OpenAI Chat Completion format by examining child MODEL_STEP and TOOL_CALL spans. This enables Braintrust's Thread view to properly display the full conversation flow including tool calls and their results.

@mastra/clickhouse@1.0.0-beta.10

Patch Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

• Fixed ClickHouse metadata handling to prevent empty string crashes when storing undefined metadata. (#11898)

  What changed:

  • Applied DEFAULT '{}' constraint to metadata columns for both 'text' and 'jsonb' types (previously only 'text')
  • Extended serializeMetadata() and parseMetadata() helpers to resources (previously only threads)
  • ClickHouse-specific issue: undefined values become empty strings in String columns, causing JSON.parse() crashes

  Why ClickHouse needs this:

  • ClickHouse has no native JSON type - both 'text' and 'jsonb' map to String columns
  • When undefined is stored in String columns, it becomes '' (empty string)
  • On retrieval, JSON.parse('') crashes with "Unexpected end of JSON input"

  Impact:

  • Defense-in-depth: database-level DEFAULT '{}' + application-level safe parsing
  • Prevents crashes across all ClickHouse storage domains (threads, resources, scorers, spans, agents)

  Related to #11882

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

Major Changes

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

Patch Changes

• Removes the deprecated threadId and resourceId options from AgentExecutionOptions. These have been deprecated for months in favour of the memory option. (#11897)

  Breaking Changes

  @mastra/core

  The threadId and resourceId options have been removed from agent.generate() and agent.stream(). Use the memory option instead:

  // Before
  await agent.stream('Hello', {
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.stream('Hello', {
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

  @mastra/server

  The threadId, resourceId, and resourceid fields have been removed from the main agent execution body schema. The server now expects the memory option format in request bodies. Legacy routes (/api/agents/:agentId/generate-legacy and /api/agents/:agentId/stream-legacy) continue to support the deprecated fields.

  @mastra/react

  The useChat hook now internally converts threadId to the memory option format when making API calls. No changes needed in component code - the hook handles the conversion automatically.

  @mastra/client-js

  When using the client SDK agent methods, use the memory option instead of threadId/resourceId:

  const agent = client.getAgent('my-agent');
  
  // Before
  await agent.generate({
    messages: [...],
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.generate({
    messages: [...],
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

• Add human-in-the-loop (HITL) support to agent networks (#11678)

  • Add suspend/resume capabilities to agent network
  • Enable auto-resume for suspended network execution via autoResumeSuspendedTools

  agent.resumeNetwork, agent.approveNetworkToolCall, agent.declineNetworkToolCall

@mastra/cloudflare@1.0.0-beta.11

Patch Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

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

Patch Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

@mastra/codemod@0.1.0-beta.6

Patch Changes

• Remove incorrect codemod (#11826)

@mastra/core@1.0.0-beta.22

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

Minor Changes

• Add context parameter to idGenerator to enable deterministic ID generation based on context. (#10964)

  The idGenerator function now receives optional context about what type of ID is being generated and from which Mastra primitive. This allows generating IDs that can be shared with external databases.

  const mastra = new Mastra({
    idGenerator: context => {
      // context.idType: 'thread' | 'message' | 'run' | 'step' | 'generic'
      // context.source: 'agent' | 'workflow' | 'memory'
      // context.entityId: the agent/workflow id
      // context.threadId, context.resourceId, context.role, context.stepType
  
      if (context?.idType === 'message' && context?.threadId) {
        return `msg-${context.threadId}-${Date.now()}`;
      }
      if (context?.idType === 'run' && context?.source === 'agent') {
        return `run-${context.entityId}-${Date.now()}`;
      }
      return crypto.randomUUID();
    },
  });

  Existing idGenerator functions without parameters continue to work since the context is optional.

  Fixes #8131

• Add hideInput and hideOutput options to TracingOptions for protecting sensitive data in traces. (#11969)

  When set to true, these options hide input/output data from all spans in a trace, including child spans. This is useful for protecting sensitive information from being logged to observability platforms.

  const agent = mastra.getAgent('myAgent');
  await agent.generate('Process this sensitive data', {
    tracingOptions: {
      hideInput: true, // Input will be hidden from all spans
      hideOutput: true, // Output will be hidden from all spans
    },
  });

  The options can be used independently (hide only input or only output) or together. The settings are propagated to all child spans via TraceState, ensuring consistent behavior across the entire trace.

  Fixes #10888

• Removed the deprecated AISDKV5OutputStream class from the public API. (#11845)

  What changed: The AISDKV5OutputStream class is no longer exported from @mastra/core. This class was previously used with the format: 'aisdk' option, which has already been removed from .stream() and .generate() methods.

  Who is affected: Only users who were directly importing AISDKV5OutputStream from @mastra/core. If you were using the standard .stream() or .generate() methods without the format option, no changes are needed.

  Migration: If you were importing this class directly, switch to using MastraModelOutput which provides the same streaming functionality:

  // Before
  import { AISDKV5OutputStream } from '@mastra/core';
  
  // After
  import { MastraModelOutput } from '@mastra/core';

• Changed JSON columns from TEXT to JSONB in mastra_threads and mastra_workflow_snapshot tables. (#11853)

  Why this change?

  These were the last remaining columns storing JSON as TEXT. This change aligns them with other tables that already use JSONB, enabling native JSON operators and improved performance. See #8978 for details.

  Columns Changed:

  • mastra_threads.metadata - Thread metadata
  • mastra_workflow_snapshot.snapshot - Workflow run state

  PostgreSQL

  Migration Required - PostgreSQL enforces column types, so existing tables must be migrated. Note: Migration will fail if existing column values contain invalid JSON.

  ALTER TABLE mastra_threads
  ALTER COLUMN metadata TYPE jsonb
  USING metadata::jsonb;
  
  ALTER TABLE mastra_workflow_snapshot
  ALTER COLUMN snapshot TYPE jsonb
  USING snapshot::jsonb;

  LibSQL

  No Migration Required - LibSQL now uses native SQLite JSONB format (added in SQLite 3.45) for ~3x performance improvement on JSON operations. The changes are fully backwards compatible:

  • Existing TEXT JSON data continues to work
  • New data is stored in binary JSONB format
  • Both formats can coexist in the same table
  • All JSON functions (json_extract, etc.) work on both formats

  New installations automatically use JSONB. Existing applications continue to work without any changes.

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

• Add MCP tool annotations and metadata support to ToolAction and Tool (#11841)

  Tools can now surface UI hints like title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint via the mcp.annotations field, and pass arbitrary metadata to MCP clients via mcp._meta. These MCP-specific properties are grouped under the mcp property to clearly indicate they only apply when tools are exposed via MCP.

  import { createTool } from '@mastra/core/tools';
  
  const myTool = createTool({
    id: 'weather',
    description: 'Get weather for a location',
    mcp: {
      annotations: {
        title: 'Weather Lookup',
        readOnlyHint: true,
        destructiveHint: false,
      },
      _meta: { version: '1.0.0' },
    },
    execute: async ({ location }) => fetchWeather(location),
  });

Patch Changes

• Fix dimension mismatch error when switching embedders in SemanticRecall. The processor now properly validates vector index dimensions when an index already exists, preventing runtime errors when switching between embedders with different dimensions (e.g., fastembed 384 dims → OpenAI 1536 dims). (#11893)

• Removes the deprecated threadId and resourceId options from AgentExecutionOptions. These have been deprecated for months in favour of the memory option. (#11897)

  Breaking Changes

  @mastra/core

  The threadId and resourceId options have been removed from agent.generate() and agent.stream(). Use the memory option instead:

  // Before
  await agent.stream('Hello', {
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.stream('Hello', {
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

  @mastra/server

  The threadId, resourceId, and resourceid fields have been removed from the main agent execution body schema. The server now expects the memory option format in request bodies. Legacy routes (/api/agents/:agentId/generate-legacy and /api/agents/:agentId/stream-legacy) continue to support the deprecated fields.

  @mastra/react

  The useChat hook now internally converts threadId to the memory option format when making API calls. No changes needed in component code - the hook handles the conversion automatically.

  @mastra/client-js

  When using the client SDK agent methods, use the memory option instead of threadId/resourceId:

  const agent = client.getAgent('my-agent');
  
  // Before
  await agent.generate({
    messages: [...],
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.generate({
    messages: [...],
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

• Add human-in-the-loop (HITL) support to agent networks (#11678)

  • Add suspend/resume capabilities to agent network
  • Enable auto-resume for suspended network execution via autoResumeSuspendedTools

  agent.resumeNetwork, agent.approveNetworkToolCall, agent.declineNetworkToolCall

• Fixed AI SDK v6 provider tools (like openai.tools.webSearch()) not being invoked correctly. These tools are now properly recognized and executed instead of causing failures or hallucinated tool calls. (#11946)

  Resolves #11781.

• Fixed TokenLimiterProcessor not filtering memory messages when limiting tokens. (#11941)

  Previously, the processor only received the latest user input messages, missing the conversation history from memory. This meant token limiting couldn't filter historical messages to fit within the context window.

  The processor now correctly:

  • Accesses all messages (memory + input) when calculating token budgets
  • Accounts for system messages in the token budget
  • Filters older messages to prioritize recent conversation context

  Fixes #11902

• Fix crash in mastraDBMessageToAIV4UIMessage when content.parts is undefined or null. (#11550)

  This resolves an issue where ModerationProcessor (and other code paths using MessageList.get.*.ui()) would throw TypeError: Cannot read properties of undefined (reading 'length') when processing messages with missing parts array. This commonly occurred when using AI SDK v4 (LanguageModelV1) models with input/output processors.

  The fix adds null coalescing (?? []) to safely handle undefined/null parts in the message conversion method.

• Improved TypeScript type inference for workflow steps. (#11953)

  What changed:

  • Step input/output type mismatches are now caught at compile time when chaining steps with .then()
  • The execute function now properly infers types from inputSchema, outputSchema, stateSchema, and other schema parameters
  • Clearer error messages when step types don't match workflow requirements

  Why:
  Previously, type errors in workflow step chains would only surface at runtime. Now TypeScript validates that each step's input requirements are satisfied by the previous step's output, helping you catch integration issues earlier in development.

• Add response to finish chunk payload for output processor metadata access (#11549)

  When using output processors with streaming, metadata added via processOutputResult is now accessible in the finish chunk's payload.response.uiMessages. This allows clients consuming streams over HTTP (e.g., via /stream/ui) to access processor-added metadata.

  for await (const chunk of stream.fullStream) {
    if (chunk.type === 'finish') {
      const uiMessages = chunk.payload.response?.uiMessages;
      const metadata = uiMessages?.find(m => m.role === 'assistant')?.metadata;
    }
  }

  Fixes #11454

• Fixed formatting of model_step, model_chunk, and tool_call spans in Arize Exporter. (#11922)

  Also removed tools output from model_step spans for all exporters.

• Improved tracing by filtering infrastructure chunks from model streams and adding success attribute to tool spans. (#11943)

  Added generic input/output attribute mapping for additional span types in Arize exporter.

• Fix generateTitle for pre-created threads (#11771)

  • Title generation now works automatically for pre-created threads (via client SDK)
  • When generateTitle: true is configured, titles are generated on the first user message
  • Detection is based on message history: if no existing user messages in memory, it's the first message
  • No metadata flags required - works seamlessly with optimistic UI patterns

  Fixes #11757

• Real-time span export for Inngest workflow engine (#11973)

  • Spans are now exported immediately when created and ended, instead of being batched at workflow completion
  • Added durable span lifecycle hooks (createStepSpan, endStepSpan, errorStepSpan, createChildSpan, endChildSpan, errorChildSpan) that wrap span operations in Inngest's step.run() for memoization
  • Added rebuildSpan() method to reconstruct span objects from exported data after Inngest replay
  • Fixed nested workflow step spans missing output data
  • Spans correctly maintain parent-child relationships across Inngest's durable execution boundaries using tracingIds

• Fixed sub-agents in agent.network() not receiving conversation history. (#11825)

  Sub-agents now have access to previous user messages from the conversation, enabling them to understand context from earlier exchanges. This resolves the issue where sub-agents would respond without knowledge of prior conversation turns.

  Fixes #11468

• Fix TypeScript type narrowing when iterating over typed RequestContext (#10850)

  The set() and get() methods on a typed RequestContext already provide full type safety. However, when iterating with entries(), keys(), values(), or forEach(), TypeScript couldn't narrow the value type based on key checks.

  Now it can:

  const ctx = new RequestContext<{ userId: string; maxTokens: number }>();
  
  // Direct access:
  const tokens = ctx.get('maxTokens'); // number
  
  // Iteration now works too:
  for (const [key, value] of ctx.entries()) {
    if (key === 'maxTokens') {
      value.toFixed(0); // TypeScript knows value is number
    }
  }

@mastra/datadog@1.0.0-beta.3

Patch Changes

• Make Datadog exporter zero-config compatible (#11816)

  The Datadog exporter can now be instantiated without any configuration by reading credentials from environment variables:

  • DD_LLMOBS_ML_APP - ML application name
  • DD_API_KEY - Datadog API key
  • DD_SITE - Datadog site (defaults to datadoghq.com)
  • DD_ENV - Environment name

  // Zero-config usage - reads from environment variables
  const exporter = new DatadogExporter();

• Fixed missing peer dependency warnings for @openfeature/core and @openfeature/server-sdk (#11966)

  Added @openfeature/core and @openfeature/server-sdk as optional peer dependencies to resolve warnings that occur during installation. These are transitive dependencies from dd-trace and are now properly declared.

  Troubleshooting documentation added:

  • Native module ABI mismatch errors (Node.js version compatibility with dd-trace)
  • Bundler externals configuration for dd-trace and native modules

@mastra/deployer@1.0.0-beta.22

Major Changes

• Serve the Mastra Studio from studio folder (previously playground). (#11751)

  The function signature for createNodeServer() changed, playground was renamed to studio:

  await createNodeServer(mastra, { studio: true, swaggerUI: false, tools: {} });

Patch Changes

• Add support for configuring a cloud API endpoint via MASTRA_CLOUD_API_ENDPOINT environment variable. This value is now injected into the playground frontend as window.MASTRA_CLOUD_API_ENDPOINT. (#11887)

• Fix path alias resolution for extended tsconfig files. Reference issue: #11770 (#11788)

@mastra/deployer-cloud@1.0.0-beta.22

Minor Changes

• Renamed Mastra Studio artifact directory from dist/playground to dist/studio to align with updated terminology across the deployer and CLI tools. (#11751)

Patch Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

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

Minor Changes

• Allow configuring wrangler.json properties except main (#11530)

@mastra/dynamodb@1.0.0-beta.10

Minor Changes

• Adds configurable TTL (Time To Live) support for DynamoDBStore, enabling automatic data expiration for different entity types. (#11838)

  Fixes #8185

  Usage:

  import { DynamoDBStore, type DynamoDBStoreConfig } from '@mastra/dynamodb';
  
  const config: DynamoDBStoreConfig = {
    id: 'my-store',
    tableName: 'mastra-table',
    region: 'us-east-1',
    ttl: {
      message: { enabled: true, defaultTtlSeconds: 86400 }, // 1 day
      trace: { enabled: true, defaultTtlSeconds: 604800 }, // 7 days
      workflow_snapshot: { enabled: true, defaultTtlSeconds: 2592000 }, // 30 days
    },
  };
  
  const store = new DynamoDBStore({ name: 'dynamodb', config });

  Key changes:

  • Added ttl configuration option to DynamoDBStoreConfig with per-entity settings
  • Supported entities: thread, message, resource, trace, eval, workflow_snapshot, score
  • Added typed entity data interfaces (ThreadEntityData, MessageEntityData, etc.)
  • Updated documentation with usage examples and AWS setup instructions

Patch Changes

• Fix eval scores not being saved when using DynamoDB storage (#11737)
  Scores from built-in scorers (like hallucination-scorer) were silently failing to save to DynamoDB. Scores now persist correctly with all their metadata.
  Fixes #11693. Add metadata field coverage to score storage tests

@mastra/evals@1.0.0-beta.5

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

@mastra/inngest@1.0.0-beta.2

Major Changes

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

@mastra/inngest@1.0.0-beta.13

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

Patch Changes

• Improved TypeScript type inference for workflow steps. (#11953)

  What changed:

  • Step input/output type mismatches are now caught at compile time when chaining steps with .then()
  • The execute function now properly infers types from inputSchema, outputSchema, stateSchema, and other schema parameters
  • Clearer error messages when step types don't match workflow requirements

  Why:
  Previously, type errors in workflow step chains would only surface at runtime. Now TypeScript validates that each step's input requirements are satisfied by the previous step's output, helping you catch integration issues earlier in development.

• Fix custom error properties being lost through Inngest serialization (#11962)

  Inngest's error serialization only captures standard Error properties (message, name, stack, code, cause). Custom properties like statusCode, responseHeaders, or isRetryable from API/AI SDK errors were being stripped during serialization. Errors are now wrapped with a cause structure that preserves custom properties through the serialization boundary.

• Real-time span export for Inngest workflow engine (#11973)

  • Spans are now exported immediately when created and ended, instead of being batched at workflow completion
  • Added durable span lifecycle hooks (createStepSpan, endStepSpan, errorStepSpan, createChildSpan, endChildSpan, errorChildSpan) that wrap span operations in Inngest's step.run() for memoization
  • Added rebuildSpan() method to reconstruct span objects from exported data after Inngest replay
  • Fixed nested workflow step spans missing output data
  • Spans correctly maintain parent-child relationships across Inngest's durable execution boundaries using tracingIds

• Fix observability tracing for Inngest workflows (#11885)

  • Use SpanCollector to capture span hierarchy during execution and create real spans in the memoized finalize step
  • Fix span timing by using step result startedAt/endedAt (memoized by Inngest) instead of replay-time timestamps
  • Ensures proper parent-child span relationships and accurate durations in traces
  • Multi-replica safe: no shared state needed across server instances

@mastra/laminar@1.0.0-beta.2

Major Changes

• Initial add of @mastra/laminar observability exporter (#11758)

@mastra/lance@1.0.0-beta.11

Patch Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

• Fixed LanceVectorStore failing when used with Memory. (#11828)

  When using LanceVectorStore with @mastra/memory, operations would fail because Memory calls methods without a tableName parameter. The tableName parameter now defaults to indexName when not provided in createIndex, query, and upsert methods, matching the behavior of other vector stores like PgVector.

  Additionally fixed three critical bugs:

  1. Upsert replacing entire table: The upsert method was using mode: 'overwrite' which replaced all rows in the table instead of updating only the specified rows. Now uses LanceDB's mergeInsert for proper upsert semantics (update existing rows, insert new ones).
  2. UpdateVector replacing entire table: The updateVector method had the same issue - using mode: 'overwrite' caused all other rows to be deleted. Now uses mergeInsert to only update the targeted rows.
  3. Query not returning metadata by default: When querying without specifying columns, only the id field was returned, causing metadata to be empty even though filters worked on metadata fields. Now returns all columns by default.

  Fixes #11716

@mastra/langfuse@1.0.0-beta.12

Minor Changes

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

@mastra/langsmith@1.0.0-beta.12

Minor Changes

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

@mastra/libsql@1.0.0-beta.12

Minor Changes

• Changed JSON columns from TEXT to JSONB in mastra_threads and mastra_workflow_snapshot tables. (#11853)

  Why this change?

  These were the last remaining columns storing JSON as TEXT. This change aligns them with other tables that already use JSONB, enabling native JSON operators and improved performance. See #8978 for details.

  Columns Changed:

  • mastra_threads.metadata - Thread metadata
  • mastra_workflow_snapshot.snapshot - Workflow run state

  PostgreSQL

  Migration Required - PostgreSQL enforces column types, so existing tables must be migrated. Note: Migration will fail if existing column values contain invalid JSON.

  ALTER TABLE mastra_threads
  ALTER COLUMN metadata TYPE jsonb
  USING metadata::jsonb;
  
  ALTER TABLE mastra_workflow_snapshot
  ALTER COLUMN snapshot TYPE jsonb
  USING snapshot::jsonb;

  LibSQL

  No Migration Required - LibSQL now uses native SQLite JSONB format (added in SQLite 3.45) for ~3x performance improvement on JSON operations. The changes are fully backwards compatible:

  • Existing TEXT JSON data continues to work
  • New data is stored in binary JSONB format
  • Both formats can coexist in the same table
  • All JSON functions (json_extract, etc.) work on both formats

  New installations automatically use JSONB. Existing applications continue to work without any changes.

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

@mastra/mcp@1.0.0-beta.10

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

Minor Changes

• Expose tool mcp.annotations and mcp._meta in MCPServer listTools response (#11841)

  MCP clients (including OpenAI Apps SDK) now receive tool behavior hints and custom metadata when listing tools. This enables clients to display user-friendly tool titles, show permission indicators, and access arbitrary metadata without additional configuration.

  // Tools with mcp properties are automatically exposed via MCP
  const server = new MCPServer({
    name: 'My Server',
    version: '1.0.0',
    tools: { myTool }, // mcp.annotations and mcp._meta flow through to clients
  });

• Add OAuth 2.1 support for MCP client and server (#11939)

  Client-side OAuth:

  • MCPOAuthClientProvider: Ready-to-use OAuth provider implementation for connecting to OAuth-protected MCP servers
  • Supports dynamic client registration (RFC 7591), PKCE, and token refresh
  • OAuthStorage interface with InMemoryOAuthStorage for token persistence
  • createSimpleTokenProvider helper for testing with pre-configured tokens

  Server-side OAuth middleware:

  • createOAuthMiddleware - Middleware for protecting MCP server endpoints with OAuth
  • Serves Protected Resource Metadata at /.well-known/oauth-protected-resource (RFC 9728)
  • createStaticTokenValidator for simple token validation in development
  • createIntrospectionValidator for production token introspection (RFC 7662)

  Shared utilities:

  • Re-exports OAuth types from the MCP SDK
  • MCPServerOAuthConfig and TokenValidationResult types
  • Helper functions for WWW-Authenticate headers and Protected Resource Metadata generation

@mastra/memory@1.0.0-beta.13

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

Patch Changes

• Fix updateMessages() to sync vector database for semantic recall. Previously, updating a message's content would not update the corresponding vector embeddings, causing semantic recall to return stale results based on old content. (#11842)

@mastra/mongodb@1.0.0-beta.12

Minor Changes

• Add configurable embeddingFieldPath option to MongoDBVector constructor. This allows users to specify custom paths for storing vector embeddings, including nested document paths using dot notation (e.g., text.contentEmbedding). Defaults to 'embedding' for backward compatibility. (#11944)

Patch Changes

• Fix MongoDB scores storage sort logic to use numeric sort values (-1) instead of string values ('desc') for consistency with other MongoDB domains (agents, memory, observability, workflows). (#11729)

• Fix MongoDB connection string parameter naming inconsistency. MongoDBVector now uses uri parameter (correct MongoDB terminology). MongoDBStore now accepts both uri (recommended) and url (deprecated, for backward compatibility). Added clear error messages when connection string is missing. (#11728)

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

@mastra/observability@1.0.0-beta.11

Major Changes

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

Minor Changes

• Add hideInput and hideOutput options to TracingOptions for protecting sensitive data in traces. (#11969)

  When set to true, these options hide input/output data from all spans in a trace, including child spans. This is useful for protecting sensitive information from being logged to observability platforms.

  const agent = mastra.getAgent('myAgent');
  await agent.generate('Process this sensitive data', {
    tracingOptions: {
      hideInput: true, // Input will be hidden from all spans
      hideOutput: true, // Output will be hidden from all spans
    },
  });

  The options can be used independently (hide only input or only output) or together. The settings are propagated to all child spans via TraceState, ensuring consistent behavior across the entire trace.

  Fixes #10888

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

Patch Changes

• feat(spans): implement entity inheritance for child spans (#11914)

  Added tests to verify that child spans inherit entityId and entityName from their parent spans when not explicitly provided. Also included functionality to allow child spans to override these inherited values. This ensures proper entity identification across multiple levels of span hierarchy.

• Improved tracing by filtering infrastructure chunks from model streams and adding success attribute to tool spans. (#11943)

  Added generic input/output attribute mapping for additional span types in Arize exporter.

• Real-time span export for Inngest workflow engine (#11973)

  • Spans are now exported immediately when created and ended, instead of being batched at workflow completion
  • Added durable span lifecycle hooks (createStepSpan, endStepSpan, errorStepSpan, createChildSpan, endChildSpan, errorChildSpan) that wrap span operations in Inngest's step.run() for memoization
  • Added rebuildSpan() method to reconstruct span objects from exported data after Inngest replay
  • Fixed nested workflow step spans missing output data
  • Spans correctly maintain parent-child relationships across Inngest's durable execution boundaries using tracingIds

@mastra/opensearch@1.0.0-beta.4

Minor Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

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

Minor Changes

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

• Export getAttributes and getSpanName GenAI semantic convention helpers (#11890)

  These functions were previously internal but are now exported to support:

  • The new @mastra/sentry exporter which uses them for consistent attribute formatting
  • Custom exporter implementations that want to follow GenAI semantic conventions

Patch Changes

• Fixed formatting of model_step, model_chunk, and tool_call spans in Arize Exporter. (#11922)

  Also removed tools output from model_step spans for all exporters.

@mastra/pg@1.0.0-beta.13

Minor Changes

• Changed JSON columns from TEXT to JSONB in mastra_threads and mastra_workflow_snapshot tables. (#11853)

  Why this change?

  These were the last remaining columns storing JSON as TEXT. This change aligns them with other tables that already use JSONB, enabling native JSON operators and improved performance. See #8978 for details.

  Columns Changed:

  • mastra_threads.metadata - Thread metadata
  • mastra_workflow_snapshot.snapshot - Workflow run state

  PostgreSQL

  Migration Required - PostgreSQL enforces column types, so existing tables must be migrated. Note: Migration will fail if existing column values contain invalid JSON.

  ALTER TABLE mastra_threads
  ALTER COLUMN metadata TYPE jsonb
  USING metadata::jsonb;
  
  ALTER TABLE mastra_workflow_snapshot
  ALTER COLUMN snapshot TYPE jsonb
  USING snapshot::jsonb;

  LibSQL

  No Migration Required - LibSQL now uses native SQLite JSONB format (added in SQLite 3.45) for ~3x performance improvement on JSON operations. The changes are fully backwards compatible:

  • Existing TEXT JSON data continues to work
  • New data is stored in binary JSONB format
  • Both formats can coexist in the same table
  • All JSON functions (json_extract, etc.) work on both formats

  New installations automatically use JSONB. Existing applications continue to work without any changes.

Patch Changes

• Fix listWorkflowRuns failing with "unsupported Unicode escape sequence" error when filtering by status on snapshots containing null characters (\u0000) or unpaired Unicode surrogates (\uD800-\uDFFF). (#11616)

  The fix uses regexp_replace to sanitize problematic escape sequences before casting to JSONB in the WHERE clause, while preserving the original data in the returned results.

• Fixed PostgreSQL migration errors when upgrading from v0.x to v1 (#11633)

  What changed: PostgreSQL storage now automatically adds missing spanId and requestContext columns to the scorers table during initialization, preventing "column does not exist" errors when upgrading from v0.x to v1.0.0.

  Why: Previously, upgrading to v1 could fail with errors like column "requestContext" of relation "mastra_scorers" does not exist if your database was created with an older version.

  Related: #11631

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

• Fixed PostgreSQL storage issues after JSONB migration. (#11906)

  Bug Fixes

  • Fixed clearTable() using incorrect default schema. The method was checking for table existence in the 'mastra' schema instead of PostgreSQL's default 'public' schema, causing table truncation to be skipped and leading to duplicate key violations in tests and production code that uses dangerouslyClearAll().
  • Fixed listWorkflowRuns() status filter failing with "function regexp_replace(jsonb, ...) does not exist" error. After the TEXT to JSONB migration, the query tried to use regexp_replace() directly on a JSONB column. Now casts to text first: regexp_replace(snapshot::text, ...).
  • Added Unicode sanitization when persisting workflow snapshots to handle null characters (\u0000) and unpaired surrogates (\uD800-\uDFFF) that PostgreSQL's JSONB type rejects, preventing "unsupported Unicode escape sequence" errors.

@mastra/pinecone@1.0.0-beta.5

Minor Changes

• Aligned vector store configuration with underlying library APIs, giving you access to all library options directly. (#11742)

  Why this change?

  Previously, each vector store defined its own configuration types that only exposed a subset of the underlying library's options. This meant users couldn't access advanced features like authentication, SSL, compression, or custom headers without creating their own client instances. Now, the configuration types extend the library types directly, so all options are available.

  @mastra/libsql (Breaking)

  Renamed connectionUrl to url to match the @libsql/client API and align with LibSQLStorage.

  // Before
  new LibSQLVector({ id: 'my-vector', connectionUrl: 'file:./db.sqlite' });
  
  // After
  new LibSQLVector({ id: 'my-vector', url: 'file:./db.sqlite' });

  @mastra/opensearch (Breaking)

  Renamed url to node and added support for all OpenSearch ClientOptions including authentication, SSL, and compression.

  // Before
  new OpenSearchVector({ id: 'my-vector', url: 'http://localhost:9200' });
  
  // After
  new OpenSearchVector({ id: 'my-vector', node: 'http://localhost:9200' });
  
  // With authentication (now possible)
  new OpenSearchVector({
    id: 'my-vector',
    node: 'https://localhost:9200',
    auth: { username: 'admin', password: 'admin' },
    ssl: { rejectUnauthorized: false },
  });

  @mastra/pinecone (Breaking)

  Removed environment parameter. Use controllerHostUrl instead (the actual Pinecone SDK field name). Added support for all PineconeConfiguration options.

  // Before
  new PineconeVector({ id: 'my-vector', apiKey: '...', environment: '...' });
  
  // After
  new PineconeVector({ id: 'my-vector', apiKey: '...' });
  
  // With custom controller host (if needed)
  new PineconeVector({ id: 'my-vector', apiKey: '...', controllerHostUrl: '...' });

  @mastra/clickhouse

  Added support for all ClickHouseClientConfigOptions like request_timeout, compression, keep_alive, and database. Existing configurations continue to work unchanged.

  @mastra/cloudflare, @mastra/cloudflare-d1, @mastra/lance, @mastra/libsql, @mastra/mongodb, @mastra/pg, @mastra/upstash

  Improved logging by replacing console.warn with structured logger in workflow storage domains.

  @mastra/deployer-cloud

  Updated internal LibSQLVector configuration for compatibility with the new API.

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

Minor Changes

• Added consistent sizing, radius, and focus effects across all form elements. (#11970)

  New size prop for form elements with unified values:

  • sm (24px)
  • md (32px)
  • lg (40px)

  Components now share a consistent size prop: Button, Input, SelectTrigger, Searchbar, InputField, SelectField, and Combobox.

  // Before - inconsistent props
  <Input customSize="default" />
  <Button size="md" /> // was 24px
  
  // After - unified size prop
  <Input size="md" />
  <Button size="md" /> // now 32px
  <SelectTrigger size="lg" />

  Breaking changes:

  • Input: customSize prop renamed to size
  • Button: size="md" now renders at 32px (was 24px). Use size="sm" for 24px height.

  Other changes:

  • All form elements now use rounded-md radius
  • All form elements now use focus:outline focus:outline-accent1 focus effect
  • Removed button-md and button-lg size tokens (use form-sm, form-md, form-lg instead)

• Added platform-aware navigation filtering using useMastraPlatform hook. Nav links now include an isOnMastraPlatform property that controls visibility based on whether the app is running on Mastra Platform or locally. (#11990)

• consolidate duplicated components between ds and ui directories (#11876)

Patch Changes

• Add Storybook stories for all design system components. Includes stories for 48 components organized by category (Elements, Feedback, Navigation, DataDisplay, Layout, Composite) plus an Icons showcase displaying all 41 icons. (#11921)

• Consolidate UI components into design system folder. Moves all UI primitives from src/components/ui/ to src/ds/components/ to establish a single source of truth for UI components. Import paths updated across the codebase. No API changes - all exports remain the same. (#11886)

• Consolidate Tailwind config as the single source of truth. The playground package now imports the config via a preset export instead of duplicating all theme definitions. (#11916)

• Aligned border, background, and radius styles across Dialog, AlertDialog, Popover, and Select components for visual consistency. All overlay components now use border-border1, bg-surface3, and rounded-md. (#11974)

• Add human-in-the-loop (HITL) support to agent networks (#11678)

  • Add suspend/resume capabilities to agent network
  • Enable auto-resume for suspended network execution via autoResumeSuspendedTools

  agent.resumeNetwork, agent.approveNetworkToolCall, agent.declineNetworkToolCall

• fix(playground-ui): prevent temperature and topP conflict for Anthropic Claude 4.5+ models (#11777)

  • Auto-clear topP for Claude 4.5+ models when both temperature and topP are set
  • Show warning banner when user manually sets both values for restricted models
  • Non-restricted models (OpenAI, Google, Claude 3.5) keep both defaults

  Fixes #11760

• Removed legacy spacing tokens (sm, md, lg) from the design system. These tokens were deprecated aliases that mapped to standard Tailwind spacing values (0.5, 1, 2). All components have been updated to use the standard spacing tokens directly. (#11978)

• Move AutoForm from ds/components to lib/form for better organization (#11915)

• Merge IconColors into Colors object in design tokens. Icon color tokens (icon1 through icon6) are now part of the main Colors export. (#11932)

• Remove legacy colors.mastra from Tailwind config and migrate to design system tokens (Colors, IconColors). (#11925)

• Rollback color of sidebar cloud cta (#11877)

• Remove unused keyframes and animations from tailwind config (#11930)

• Rename icon color tokens to neutral for better semantic naming (#11933)

• Replaced arbitrary Tailwind CSS values with standard utility classes for better consistency and maintainability. (#11965)

  • Changed arbitrary spacing values like gap-[1rem], p-[1.5rem], px-[2rem] to standard classes (gap-4, p-6, px-8)
  • Updated z-index values from z-[1] and z-[100] to standard z-10 and z-50
  • Replaced arbitrary gap values like gap-[6px] with gap-1.5
  • Updated duration values from duration-[1s] to duration-1000

• Replaced arbitrary Tailwind text sizes with semantic design tokens for consistent typography. (#11956)

  Changes:

  • Consolidated font size tokens from 5 fractional rem values to 8 clean sizes
  • Replaced 129 occurrences of arbitrary text-[...] patterns across 44 files
  • Added new header size tokens (header-sm, header-lg, header-xl)

  New token scale:

  • ui-xs: 10px
  • ui-sm: 12px (was 11px)
  • ui-md: 14px (was 12px)
  • ui-lg: 16px (was 13px)
  • header-sm: 18px
  • header-md: 20px (was 16px)
  • header-lg: 24px
  • header-xl: 28px

• Replaced direct clsx imports with the cn utility across all components for consistent Tailwind class merging. (#11938)

• Replace CSS variable colors with design tokens (#11928)

• Removed unused files, dependencies, and exports from playground packages. Deleted orphaned tool-list.tsx and workflow-list.tsx components, removed unused react-code-block dependency, and cleaned up 12 unused exports across object utilities, string helpers, and hooks. (#11979)

• Converted spacing design tokens from pixels to REM units for better accessibility. Spacing now scales with the user's browser font size settings. All existing Tailwind spacing classes (p-4, gap-2, m-8, etc.) continue to work unchanged. (#11968)

• Simplify Storybook configuration by removing Radix UI module resolution hacks and creating a dedicated CSS file for Storybook (#11920)

• Agent's right sidebar is now 30% wide before resizing. It makes it easier to read the information at a first glance (#11803)

@mastra/posthog@1.0.0-beta.12

Minor Changes

• Added TrackingExporter base class with improved handling for: (#11870)

  • Out-of-order span processing: Spans that arrive before their parents are now queued and processed once dependencies are available
  • Delayed cleanup: Trace data is retained briefly after spans end to handle late-arriving updates
  • Memory management: Configurable limits on pending and total traces to prevent memory leaks

  New configuration options on TrackingExporterConfig:

  • earlyQueueMaxAttempts - Max retry attempts for queued events (default: 5)
  • earlyQueueTTLMs - TTL for queued events in ms (default: 30000)
  • traceCleanupDelayMs - Delay before cleaning up completed traces (default: 30000)
  • maxPendingCleanupTraces - Soft cap on traces awaiting cleanup (default: 100)
  • maxTotalTraces - Hard cap on total traces (default: 500)

  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter

@mastra/qdrant@1.0.0-beta.4

Minor Changes

• Added support for creating payload (metadata) indexes in Qdrant (#11839)

  Qdrant Cloud and deployments with strict_mode_config = true require explicit payload indexes for metadata filtering. This release adds two new methods to QdrantVector:

  New exports:

  • PayloadSchemaType - Union type for Qdrant payload schema types ('keyword', 'integer', 'float', 'geo', 'text', 'bool', 'datetime', 'uuid')
  • CreatePayloadIndexParams - Parameters interface for creating payload indexes
  • DeletePayloadIndexParams - Parameters interface for deleting payload indexes

  New methods:

  • createPayloadIndex() - Creates a payload index on a collection field for efficient filtering
  • deletePayloadIndex() - Removes a payload index from a collection field

  Example usage:

  import { QdrantVector } from '@mastra/qdrant';
  
  const qdrant = new QdrantVector({ url: `http://localhost:6333`, id: 'my-store' });
  
  // Create a keyword index for filtering by source
  await qdrant.createPayloadIndex({
    indexName: 'my-collection',
    fieldName: 'source',
    fieldSchema: 'keyword',
  });
  
  // Now filtering works in strict mode environments
  const results = await qdrant.query({
    indexName: 'my-collection',
    queryVector: embeddings,
    filter: { source: 'document-a' },
  });

  Closes #8923

@mastra/rag@2.0.0-beta.7

Major Changes

• Refactor workflow and tool types to remove Zod-specific constraints (#11814)

  Removed Zod-specific type constraints across all workflow implementations and tool types, replacing them with generic types. This ensures type consistency across default, evented, and inngest workflows while preparing for Zod v4 migration.

  Workflow Changes:

  • Removed z.ZodObject<any> and z.ZodType<any> constraints from all workflow generic types
  • Updated method signatures to use TInput and TState directly instead of z.infer<TInput> and z.infer<TState>
  • Aligned conditional types across all workflow implementations using TInput extends unknown pattern
  • Fixed TSteps generic to properly use TEngineType instead of any

  Tool Changes:

  • Removed Zod schema constraints from ToolExecutionContext and related interfaces
  • Simplified type parameters from TSuspendSchema extends ZodLikeSchema to TSuspend and TResume
  • Updated tool execution context types to use generic types

  Type Utilities:

  • Refactored type helpers to work with generic schemas instead of Zod-specific types
  • Updated type extraction utilities for better compatibility

  This change maintains backward compatibility while improving type consistency and preparing for Zod v4 support across all affected packages.

Minor Changes

• Add schema-driven metadata extraction with Zod support (#11833)

  Introduces a new SchemaExtractor that enables extraction of custom structured metadata from document chunks using user-defined Zod schemas. This allows for domain-specific metadata structures (e.g., product details, legal entities, sentiment analysis) to be reliably extracted via LLM structured output.

  • Extract domain-specific metadata using your own Zod schemas (e.g., product details, legal entities, sentiment)
  • Customize extraction behavior with your own LLM model and instructions
  • Organize extracted data by nesting it under custom metadata keys
  • Existing extractors (title, summary, keywords, questions) remain unchanged and fully compatible

  Before (limited to built-in extractors):

  await document.extractMetadata({
    extract: {
      title: true,
      summary: true,
    },
  });

  After (with custom Zod schema):

  import { z } from 'zod';
  
  const productSchema = z.object({
    name: z.string(),
    price: z.number(),
    category: z.string(),
  });
  
  await document.extractMetadata({
    extract: {
      title: true,
      schema: {
        schema: productSchema,
        instructions: 'Extract product details from the document',
        metadataKey: 'product',
      },
    },
  });

  With metadataKey, extracted data is nested under the key:

  {
    title: "Product Document",
    summary: "A comprehensive guide",
    product: {
      name: "Wireless Headphones",
      price: 149.99,
      category: "Electronics"
    }
  }

  Without metadataKey, extracted data is returned inline:

  {
    title: "Product Document",
    summary: "A comprehensive guide",
    name: "Wireless Headphones",
    price: 149.99,
    category: "Electronics"
  }

  Fixes #11799

• Renamed keepSeparator parameter to separatorPosition with a cleaner type. (#11802)

  The keepSeparator parameter had a confusing boolean | 'start' | 'end' type where true was secretly an alias for 'start'. The new separatorPosition parameter uses explicit 'start' | 'end' values, and omitting the parameter discards the separator (previous default behavior).

  Migration

  // Before
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    keepSeparator: true, // or 'start'
  });
  
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    keepSeparator: 'end',
  });
  
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    keepSeparator: false, // or omit entirely
  });
  
  // After
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    separatorPosition: 'start',
  });
  
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    separatorPosition: 'end',
  });
  
  await doc.chunk({
    strategy: 'character',
    separator: '.',
    // omit separatorPosition to discard separator
  });

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

Patch Changes

• Removes the deprecated threadId and resourceId options from AgentExecutionOptions. These have been deprecated for months in favour of the memory option. (#11897)

  Breaking Changes

  @mastra/core

  The threadId and resourceId options have been removed from agent.generate() and agent.stream(). Use the memory option instead:

  // Before
  await agent.stream('Hello', {
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.stream('Hello', {
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

  @mastra/server

  The threadId, resourceId, and resourceid fields have been removed from the main agent execution body schema. The server now expects the memory option format in request bodies. Legacy routes (/api/agents/:agentId/generate-legacy and /api/agents/:agentId/stream-legacy) continue to support the deprecated fields.

  @mastra/react

  The useChat hook now internally converts threadId to the memory option format when making API calls. No changes needed in component code - the hook handles the conversion automatically.

  @mastra/client-js

  When using the client SDK agent methods, use the memory option instead of threadId/resourceId:

  const agent = client.getAgent('my-agent');
  
  // Before
  await agent.generate({
    messages: [...],
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.generate({
    messages: [...],
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

• Add human-in-the-loop (HITL) support to agent networks (#11678)

  • Add suspend/resume capabilities to agent network
  • Enable auto-resume for suspended network execution via autoResumeSuspendedTools

  agent.resumeNetwork, agent.approveNetworkToolCall, agent.declineNetworkToolCall

• Fix text parts incorrectly merging across tool calls (#11783)

  Previously, when an agent produced text before and after a tool call (e.g., "Let me search for that" → tool call → "Here's what I found"), the text parts would be merged into a single part, losing the separation. This fix introduces a textId property to track separate text streams, ensuring each text stream maintains its own text part in the UI message.

  Fixes #11577

@mastra/sentry@1.0.0-beta.2

Major Changes

• Adding @mastra/sentry observability exporter for AI tracing with OpenTelemetry GenAI semantic conventions (#11890)

@mastra/server@1.0.0-beta.22

Major Changes

• Breaking Change: Convert OUTPUT generic from OutputSchema constraint to plain generic (#11741)

  This change removes the direct dependency on Zod typings in the public API by converting all OUTPUT extends OutputSchema generic constraints to plain OUTPUT generics throughout the codebase. This is preparation for moving to a standard schema approach.

  • All generic type parameters previously constrained to OutputSchema (e.g., <OUTPUT extends OutputSchema = undefined>) are now plain generics with defaults (e.g., <OUTPUT = undefined>)
  • Affects all public APIs including Agent, MastraModelOutput, AgentExecutionOptions, and stream/generate methods
  • InferSchemaOutput<OUTPUT> replaced with OUTPUT throughout
  • PartialSchemaOutput<OUTPUT> replaced with Partial<OUTPUT>
  • Schema fields now use NonNullable<OutputSchema<OUTPUT>> instead of OUTPUT directly
  • Added FullOutput<OUTPUT> type representing complete output with all fields
  • Added AgentExecutionOptionsBase<OUTPUT> type
  • getFullOutput() method now returns Promise<FullOutput<OUTPUT>>
  • Agent class now generic: Agent<TAgentId, TTools, TOutput>
  • agent.generate() and agent.stream() methods have updated signatures
  • MastraModelOutput<OUTPUT> no longer requires OutputSchema constraint
  • Network route and streaming APIs updated to use plain OUTPUT generic

  Before:

  const output = await agent.generate<z.ZodType>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  
  **After:**
  const output = await agent.generate<z.infer<typeof mySchema>>({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });
  // Or rely on type inference:
  const output = await agent.generate({
    messages: [...],
    structuredOutput: { schema: mySchema }
  });

Patch Changes

• Removes the deprecated threadId and resourceId options from AgentExecutionOptions. These have been deprecated for months in favour of the memory option. (#11897)

  Breaking Changes

  @mastra/core

  The threadId and resourceId options have been removed from agent.generate() and agent.stream(). Use the memory option instead:

  // Before
  await agent.stream('Hello', {
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.stream('Hello', {
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

  @mastra/server

  The threadId, resourceId, and resourceid fields have been removed from the main agent execution body schema. The server now expects the memory option format in request bodies. Legacy routes (/api/agents/:agentId/generate-legacy and /api/agents/:agentId/stream-legacy) continue to support the deprecated fields.

  @mastra/react

  The useChat hook now internally converts threadId to the memory option format when making API calls. No changes needed in component code - the hook handles the conversion automatically.

  @mastra/client-js

  When using the client SDK agent methods, use the memory option instead of threadId/resourceId:

  const agent = client.getAgent('my-agent');
  
  // Before
  await agent.generate({
    messages: [...],
    threadId: 'thread-123',
    resourceId: 'user-456',
  });
  
  // After
  await agent.generate({
    messages: [...],
    memory: {
      thread: 'thread-123',
      resource: 'user-456',
    },
  });

• Fixed orderBy query parameter parsing for memory endpoints. The listMessages and listThreads endpoints now correctly parse orderBy when passed as a JSON string in URL query parameters, matching the existing behavior for include and filter parameters. (#11767)

• Add human-in-the-loop (HITL) support to agent networks (#11678)

  • Add suspend/resume capabilities to agent network
  • Enable auto-resume for suspended network execution via autoResumeSuspendedTools

  agent.resumeNetwork, agent.approveNetworkToolCall, agent.declineNetworkToolCall

• Fix 'Memory is not initialized' error in playground for agents with sub-agents but no memory (#11780)

  When using agents with sub-agents (e.g., agent networks) but no memory configured, the playground UI would log HTTPException errors when fetching messages for sub-agents without memory.

  Changed GET /api/memory/threads/:threadId/messages to return empty messages { messages: [], uiMessages: [] } instead of throwing 400 error when memory is not configured for the requested agent.

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

Full Changelog: 4290930