@mastra/core@1.0.0-beta.21

# Changelog

## [@mastra/ai-sdk@1.0.0-beta.14](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/client-sdks/ai-sdk/CHANGELOG.md)

### Patch Changes

- Add structured output support to agent.network() method. Users can now pass a `structuredOutput` option with a Zod schema to get typed results from network execution. ([#11701](https://github.com/mastra-ai/mastra/pull/11701))

  The stream exposes `.object` (Promise) and `.objectStream` (ReadableStream) getters, and emits `network-object` and `network-object-result` chunk types. The structured output is generated after task completion using the provided schema.

  ```typescript
  const stream = await agent.network('Research AI trends', {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        recommendations: z.array(z.string()),
      }),
    },
  });

  const result = await stream.object;
  // result is typed: { summary: string; recommendations: string[] }
  ```

---

## [@mastra/arize@1.0.0-beta.12](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/arize/CHANGELOG.md)

### Minor Changes

- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))

  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
  - **OTEL Providers**:
    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`, `LAMINAR_TEAM_ID`

  Example usage:

  ```typescript
  // Zero-config - reads from environment variables
  new LangfuseExporter();
  new BraintrustExporter();
  new PosthogExporter();
  new ArizeExporter();
  new OtelExporter({ provider: { signoz: {} } });
  ```

  Explicit configuration still works and takes precedence over environment variables.

---

## [@mastra/braintrust@1.0.0-beta.12](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/braintrust/CHANGELOG.md)

### Minor Changes

- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))

  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
  - **OTEL Providers**:
    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`, `LAMINAR_TEAM_ID`

  Example usage:

  ```typescript
  // Zero-config - reads from environment variables
  new LangfuseExporter();
  new BraintrustExporter();
  new PosthogExporter();
  new ArizeExporter();
  new OtelExporter({ provider: { signoz: {} } });
  ```

  Explicit configuration still works and takes precedence over environment variables.

---

## [@mastra/core@1.0.0-beta.21](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/core/CHANGELOG.md)

### Minor Changes

- Add structured output support to agent.network() method. Users can now pass a `structuredOutput` option with a Zod schema to get typed results from network execution. ([#11701](https://github.com/mastra-ai/mastra/pull/11701))

  The stream exposes `.object` (Promise) and `.objectStream` (ReadableStream) getters, and emits `network-object` and `network-object-result` chunk types. The structured output is generated after task completion using the provided schema.

  ```typescript
  const stream = await agent.network('Research AI trends', {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        recommendations: z.array(z.string()),
      }),
    },
  });

  const result = await stream.object;
  // result is typed: { summary: string; recommendations: string[] }
  ```

### Patch Changes

- Add additional context to workflow `onFinish` and `onError` callbacks ([#11705](https://github.com/mastra-ai/mastra/pull/11705))

  The `onFinish` and `onError` lifecycle callbacks now receive additional properties:
  - `runId` - The unique identifier for the workflow run
  - `workflowId` - The workflow's identifier
  - `resourceId` - Optional resource identifier (if provided when creating the run)
  - `getInitData()` - Function that returns the initial input data passed to the workflow
  - `mastra` - The Mastra instance (if workflow is registered with Mastra)
  - `requestContext` - Request-scoped context data
  - `logger` - The workflow's logger instance
  - `state` - The workflow's current state object

  ```typescript
  const workflow = createWorkflow({
    id: 'order-processing',
    inputSchema: z.object({ orderId: z.string() }),
    outputSchema: z.object({ status: z.string() }),
    options: {
      onFinish: async ({ runId, workflowId, getInitData, logger, state, mastra }) => {
        const inputData = getInitData();
        logger.info(`Workflow ${workflowId} run ${runId} completed`, {
          orderId: inputData.orderId,
          finalState: state,
        });

        // Access other Mastra components if needed
        const agent = mastra?.getAgent('notification-agent');
      },
      onError: async ({ runId, workflowId, error, logger, requestContext }) => {
        logger.error(`Workflow ${workflowId} run ${runId} failed: ${error?.message}`);
        // Access request context for additional debugging
        const userId = requestContext.get('userId');
      },
    },
  });
  ```

- Make initialState optional in studio ([#11744](https://github.com/mastra-ai/mastra/pull/11744))

- Refactor: consolidate duplicate applyMessages helpers in workflow.ts ([#11688](https://github.com/mastra-ai/mastra/pull/11688))
  - Added optional `defaultSource` parameter to `ProcessorRunner.applyMessagesToMessageList` to support both 'input' and 'response' default sources
  - Removed 3 duplicate inline `applyMessages` helper functions from workflow.ts (in input, outputResult, and outputStep phases)
  - All phases now use the shared `ProcessorRunner.applyMessagesToMessageList` static method

  This is an internal refactoring with no changes to external behavior.

- Cache processor instances in MastraMemory to preserve embedding cache across calls ([#11720](https://github.com/mastra-ai/mastra/pull/11720))
  Fixed issue where getInputProcessors() and getOutputProcessors() created new processor instances on each call, causing the SemanticRecall embedding cache to be discarded. Processor instances (SemanticRecall, WorkingMemory, MessageHistory) are now cached and reused, reducing unnecessary embedding API calls and improving latency.
  Also added cache invalidation when setStorage(), setVector(), or setEmbedder() are called to ensure processors use updated dependencies.
  Fixes #11455

---

## [@mastra/datadog@1.0.0-beta.2](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/datadog/CHANGELOG.md)

### Minor Changes

- Added a Datadog LLM Observability exporter for Mastra applications. ([#11305](https://github.com/mastra-ai/mastra/pull/11305))

  This exporter integrates with Datadog's LLM Observability product to provide comprehensive tracing and monitoring for AI/LLM applications built with Mastra.
  - **LLM Observability Integration**: Exports traces to Datadog's dedicated LLM Observability product
  - **Dual Mode Support**: Works with direct HTTPS (agentless) or through a local Datadog Agent
  - **Span Type Mapping**: Automatically maps Mastra span types to Datadog LLMObs kinds (llm, agent, tool, workflow, task)
  - **Message Formatting**: LLM inputs/outputs are formatted as message arrays for proper visualization in Datadog
  - **Token Metrics**: Captures inputTokens, outputTokens, totalTokens, reasoningTokens, and cached tokens
  - **Error Tracking**: Error spans include detailed error info (message, ID, domain, category)
  - **Hierarchical Traces**: Tree-based span emission preserves parent-child relationships

  Required settings:
  - `mlApp`: Groups traces under an ML application name (required)
  - `apiKey`: Datadog API key (required for agentless mode)

  Optional settings:
  - `site`: Datadog site (datadoghq.com, datadoghq.eu, us3.datadoghq.com)
  - `agentless`: true for direct HTTPS (default), false for local agent
  - `service`, `env`: APM tagging
  - `integrationsEnabled`: Enable dd-trace auto-instrumentation (default: false)

  ```typescript
  import { Mastra } from '@mastra/core';
  import { Observability } from '@mastra/observability';
  import { DatadogExporter } from '@mastra/datadog';

  const mastra = new Mastra({
    observability: new Observability({
      configs: {
        datadog: {
          serviceName: 'my-service',
          exporters: [
            new DatadogExporter({
              mlApp: 'my-llm-app',
              apiKey: process.env.DD_API_KEY,
            }),
          ],
        },
      },
    }),
  });
  ```

  This is an initial experimental beta release. Breaking changes may occur in future versions as the API evolves.

---

## [@mastra/inngest@1.0.0-beta.12](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/workflows/inngest/CHANGELOG.md)

### Minor Changes

- Added `createServe` factory function to support multiple web framework adapters for Inngest workflows. ([#11667](https://github.com/mastra-ai/mastra/pull/11667))

  Previously, the `serve` function only supported Hono. Now you can use any framework adapter provided by the Inngest package (Express, Fastify, Koa, Next.js, and more).

  **Before (Hono only)**

  ```typescript
  import { serve } from '@mastra/inngest';

  // Only worked with Hono
  app.all('/api/inngest', c => serve({ mastra, inngest })(c));
  ```

  **After (any framework)**

  ```typescript
  import { createServe } from '@mastra/inngest';
  import { serve as expressAdapter } from 'inngest/express';
  import { serve as fastifyAdapter } from 'inngest/fastify';

  // Express
  app.use('/api/inngest', createServe(expressAdapter)({ mastra, inngest }));

  // Fastify
  fastify.route({
    method: ['GET', 'POST', 'PUT'],
    url: '/api/inngest',
    handler: createServe(fastifyAdapter)({ mastra, inngest }),
  });
  ```

  The existing `serve` export remains available for backward compatibility with Hono.

  Fixes #10053

### Patch Changes

- Add additional context to workflow `onFinish` and `onError` callbacks ([#11705](https://github.com/mastra-ai/mastra/pull/11705))

  The `onFinish` and `onError` lifecycle callbacks now receive additional properties:
  - `runId` - The unique identifier for the workflow run
  - `workflowId` - The workflow's identifier
  - `resourceId` - Optional resource identifier (if provided when creating the run)
  - `getInitData()` - Function that returns the initial input data passed to the workflow
  - `mastra` - The Mastra instance (if workflow is registered with Mastra)
  - `requestContext` - Request-scoped context data
  - `logger` - The workflow's logger instance
  - `state` - The workflow's current state object

  ```typescript
  const workflow = createWorkflow({
    id: 'order-processing',
    inputSchema: z.object({ orderId: z.string() }),
    outputSchema: z.object({ status: z.string() }),
    options: {
      onFinish: async ({ runId, workflowId, getInitData, logger, state, mastra }) => {
        const inputData = getInitData();
        logger.info(`Workflow ${workflowId} run ${runId} completed`, {
          orderId: inputData.orderId,
          finalState: state,
        });

        // Access other Mastra components if needed
        const agent = mastra?.getAgent('notification-agent');
      },
      onError: async ({ runId, workflowId, error, logger, requestContext }) => {
        logger.error(`Workflow ${workflowId} run ${runId} failed: ${error?.message}`);
        // Access request context for additional debugging
        const userId = requestContext.get('userId');
      },
    },
  });
  ```

---

## [@mastra/langfuse@1.0.0-beta.11](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/langfuse/CHANGELOG.md)

### Minor Changes

- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))

  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
  - **OTEL Providers**:
    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`, `LAMINAR_TEAM_ID`

  Example usage:

  ```typescript
  // Zero-config - reads from environment variables
  new LangfuseExporter();
  new BraintrustExporter();
  new PosthogExporter();
  new ArizeExporter();
  new OtelExporter({ provider: { signoz: {} } });
  ```

  Explicit configuration still works and takes precedence over environment variables.

---

## [@mastra/mcp-docs-server@1.0.0-beta.21](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/mcp-docs-server/CHANGELOG.md)

### Minor Changes

- feat(mcp-docs-server): add embedded docs MCP tools ([#11532](https://github.com/mastra-ai/mastra/pull/11532))

  Adds 5 new MCP tools to read embedded documentation from installed @mastra/\* packages:
  - listInstalledMastraPackages: Discover packages with embedded docs
  - readMastraSourceMap: Read export mappings from SOURCE_MAP.json
  - findMastraExport: Get type definitions and implementation for specific exports
  - readMastraEmbeddedDocs: Read topic documentation
  - searchMastraEmbeddedDocs: Search across all embedded docs

  These tools enable AI coding agents to understand Mastra packages by reading documentation directly from node_modules.

---

## [@mastra/otel-exporter@1.0.0-beta.12](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/otel-exporter/CHANGELOG.md)

### Minor Changes

- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))

  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
  - **OTEL Providers**:
    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`, `LAMINAR_TEAM_ID`

  Example usage:

  ```typescript
  // Zero-config - reads from environment variables
  new LangfuseExporter();
  new BraintrustExporter();
  new PosthogExporter();
  new ArizeExporter();
  new OtelExporter({ provider: { signoz: {} } });
  ```

  Explicit configuration still works and takes precedence over environment variables.

---

## [@mastra/playground-ui@7.0.0-beta.21](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/playground-ui/CHANGELOG.md)

### Patch Changes

- Replace deprecated client.getTraces with a client.listTraces ([#11711](https://github.com/mastra-ai/mastra/pull/11711))

- Make initialState optional in studio ([#11744](https://github.com/mastra-ai/mastra/pull/11744))

---

## [@mastra/posthog@1.0.0-beta.11](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/observability/posthog/CHANGELOG.md)

### Minor Changes

- feat(observability): add zero-config environment variable support for all exporters ([#11686](https://github.com/mastra-ai/mastra/pull/11686))

  All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
  - **Langfuse**: `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL`
  - **Braintrust**: `BRAINTRUST_API_KEY`, `BRAINTRUST_ENDPOINT`
  - **PostHog**: `POSTHOG_API_KEY`, `POSTHOG_HOST`
  - **Arize/Phoenix**: `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, `ARIZE_PROJECT_NAME`, `PHOENIX_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`
  - **OTEL Providers**:
    - Dash0: `DASH0_API_KEY`, `DASH0_ENDPOINT`, `DASH0_DATASET`
    - SigNoz: `SIGNOZ_API_KEY`, `SIGNOZ_REGION`, `SIGNOZ_ENDPOINT`
    - New Relic: `NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_ENDPOINT`
    - Traceloop: `TRACELOOP_API_KEY`, `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT`
    - Laminar: `LMNR_PROJECT_API_KEY`, `LAMINAR_ENDPOINT`, `LAMINAR_TEAM_ID`

  Example usage:

  ```typescript
  // Zero-config - reads from environment variables
  new LangfuseExporter();
  new BraintrustExporter();
  new PosthogExporter();
  new ArizeExporter();
  new OtelExporter({ provider: { signoz: {} } });
  ```

  Explicit configuration still works and takes precedence over environment variables.

---

## [@mastra/rag@2.0.0-beta.6](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/rag/CHANGELOG.md)

### Patch Changes

- Remove unnecessary `ai` package peer dependency to enable compatibility with AI SDK v6. The rag package doesn't directly use the ai package, so this peer dependency was unnecessarily constraining version compatibility. ([#11724](https://github.com/mastra-ai/mastra/pull/11724))

---

## [@mastra/schema-compat@1.0.0-beta.6](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/schema-compat/CHANGELOG.md)

### Patch Changes

- Fix oneOf schema conversion generating invalid JavaScript ([#11626](https://github.com/mastra-ai/mastra/pull/11626))

  The upstream json-schema-to-zod library generates TypeScript syntax (`reduce<z.ZodError[]>`) when converting oneOf schemas. This TypeScript generic annotation fails when evaluated at runtime with Function(), causing schema resolution to fail.

  The fix removes TypeScript generic syntax from the generated output, producing valid JavaScript that can be evaluated at runtime. This resolves issues where MCP tools with oneOf in their output schemas would fail validation.

---

## [@mastra/server@1.0.0-beta.21](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/server/CHANGELOG.md)

### Patch Changes

- Replace deprecated client.getTraces with a client.listTraces ([#11711](https://github.com/mastra-ai/mastra/pull/11711))

- Fix query parameter parsing for complex nested optional types ([#11711](https://github.com/mastra-ai/mastra/pull/11711))

  Fixes an issue where complex query parameters (like `startedAt` and `endedAt` date range filters) would fail with "Expected object, received string" errors when using the `listTraces` API.

  The fix addresses two issues:
  - Properly unwraps all layers of nested optional/nullable types (e.g., from `.partial()` on already-optional fields)
  - Ensures compatibility with both zod v3 and v4

---

## [create-mastra@1.0.0-beta.14](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/create-mastra/CHANGELOG.md)

### Patch Changes

- Replace deprecated client.getTraces with a client.listTraces ([#11711](https://github.com/mastra-ai/mastra/pull/11711))

- Make initialState optional in studio ([#11744](https://github.com/mastra-ai/mastra/pull/11744))

---

## [mastra@1.0.0-beta.14](https://github.com/mastra-ai/mastra/blob/8edb59796838fbece6868afc558af4c3581c0e9b/packages/cli/CHANGELOG.md)

### Patch Changes

- Replace deprecated client.getTraces with a client.listTraces ([#11711](https://github.com/mastra-ai/mastra/pull/11711))

- Make initialState optional in studio ([#11744](https://github.com/mastra-ai/mastra/pull/11744))

---


---

**Full Changelog**: [`8edb597`](https://github.com/mastra-ai/mastra/commit/8edb59796838fbece6868afc558af4c3581c0e9b)