@mastra/core 1.2.1-alpha.0 → 1.3.0-alpha.1

package/dist/docs/references/docs-workspace-filesystem.md

@@ -1,5 +1,7 @@
 # Filesystem
 
+**Added in:** `@mastra/core@1.1.0`
+
 Filesystem providers give agents the ability to read, write, and manage files. When you configure a filesystem on a workspace, agents receive tools for file operations.
 
 A filesystem provider handles all file operations for a workspace:

package/dist/docs/references/docs-workspace-overview.md

@@ -1,4 +1,6 @@
-# Workspace
+# Workspaces
+
+**Added in:** `@mastra/core@1.1.0`
 
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents use workspace tools to read and write files, run shell commands, and search indexed content.
 

package/dist/docs/references/docs-workspace-sandbox.md

@@ -1,5 +1,7 @@
 # Sandbox
 
+**Added in:** `@mastra/core@1.1.0`
+
 Sandbox providers give agents the ability to execute shell commands. When you configure a sandbox on a workspace, agents can run commands as part of their tasks.
 
 A sandbox provider executes commands in a controlled environment:

package/dist/docs/references/docs-workspace-search.md

@@ -1,5 +1,7 @@
 # Search and Indexing
 
+**Added in:** `@mastra/core@1.1.0`
+
 Search lets agents find relevant content in indexed workspace files. When an agent needs to answer a question or find information, it can search the indexed content instead of reading every file.
 
 ## How it works

package/dist/docs/references/docs-workspace-skills.md

@@ -1,4 +1,6 @@
-# Skills
+# Workspace Skills
+
+**Added in:** `@mastra/core@1.1.0`
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io) - an open standard for packaging agent capabilities.
 

package/dist/docs/references/reference-agents-getTools.md

@@ -26,9 +26,4 @@ await agent.getTools({
 
 ### Options parameters
 
-**requestContext?:** (`RequestContext`): Runtime context for dependency injection and contextual information. (Default: `new RequestContext()`)
-
-## Related
-
-- [Using tools with agents](https://mastra.ai/docs/agents/using-tools)
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
+**requestContext?:** (`RequestContext`): Runtime context for dependency injection and contextual information. (Default: `new RequestContext()`)

package/dist/docs/references/reference-agents-listAgents.md

@@ -1,6 +1,6 @@
 # Agent.listAgents()
 
-The `.listAgents()` method retrieves the sub-agents configured for an agent, resolving them if they're a function. These sub-agents enable the agent to access other agents and perform complex actions.
+The `.listAgents()` method retrieves the subagents configured for an agent, resolving them if they're a function. These subagents enable the agent to access other agents and perform complex actions.
 
 ## Usage example
 

package/dist/docs/references/reference-agents-network.md

@@ -1,7 +1,5 @@
 # Agent.network()
 
-> **Experimental Feature:** This is an experimental API that may change in future versions. The `network()` method enables multi-agent collaboration and workflow orchestration. Use with caution in production environments.
-
 The `.network()` method enables multi-agent collaboration and routing. This method accepts messages and optional execution options.
 
 ## Usage example

package/dist/docs/references/reference-cli-mastra.md

@@ -26,7 +26,24 @@ Start the development server in inspect mode and break at the beginning of the s
 
 #### `--custom-args`
 
-Comma-separated list of custom arguments to pass to the development server. You can pass arguments to the Node.js process, e.g. `--experimental-transform-types`.
+Comma-separated list of custom arguments to pass to the Node.js process, e.g. `--require=newrelic` or `--experimental-transform-types`.
+
+#### `--request-context-presets`
+
+Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. When provided, a dropdown appears in Studio's request context editor, letting you quickly switch between preset configurations.
+
+```bash
+mastra dev --request-context-presets ./presets.json
+```
+
+The file must be a JSON object where each key is a preset name and each value is an object:
+
+```json
+{
+  "development": { "userId": "dev-user", "env": "development" },
+  "production": { "userId": "prod-user", "env": "production" }
+}
+```
 
 ### Configs
 
@@ -90,7 +107,7 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](https://mastra.ai/guides/deployment) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](https://mastra.ai/docs/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
 It accepts [common flags](#common-flags).
 
@@ -134,9 +151,9 @@ The command accepts [common flags](#common-flags) and the following additional f
 
 The path to your built Mastra output directory. Defaults to `.mastra/output`.
 
-#### `--no-telemetry`
+#### `--custom-args`
 
-Disable the [OTEL Tracing](https://mastra.ai/docs/observability/tracing/overview).
+Comma-separated list of custom arguments to pass to the Node.js process, e.g. `--require=newrelic` or `--experimental-transform-types`.
 
 ## `mastra studio`
 
@@ -162,6 +179,14 @@ The port of the Mastra API server to connect to. Defaults to `4111`.
 
 The protocol of the Mastra API server to connect to. Defaults to `http`.
 
+#### `--request-context-presets`
+
+Path to a JSON file containing named [request context](https://mastra.ai/docs/server/request-context) presets. Works the same as the [`mastra dev` flag](#--request-context-presets).
+
+```bash
+mastra studio --request-context-presets ./presets.json
+```
+
 ## `mastra lint`
 
 The `mastra lint` command validates the structure and code of your Mastra project to ensure it follows best practices and is error-free.

package/dist/docs/references/reference-client-js-agents.md

@@ -364,7 +364,7 @@ const agent = await mastraClient.createStoredAgent({
   },
   tools: ["calculator", "weather"],
   workflows: ["data-processing"],
-  agents: ["sub-agent-1"],
+  agents: ["subagent-1"],
   memory: "my-memory",
   scorers: {
     "quality-scorer": {

package/dist/docs/references/reference-configuration.md

@@ -304,7 +304,7 @@ export const mastra = new Mastra({
 
 Tools are reusable functions that agents can use to interact with external systems. Each tool defines inputs, outputs, and execution logic.
 
-Visit the [Tools documentation](https://mastra.ai/docs/tools-mcp/overview) to learn more.
+Visit the [Tools documentation](https://mastra.ai/docs/agents/using-tools) to learn more.
 
 > **Note:** Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.
 

package/dist/docs/references/reference-core-getStoredAgentById.md

@@ -44,7 +44,7 @@ When creating an `Agent` instance from stored configuration, the method resolves
 
 - **Tools**: Resolved from `tools` registered in Mastra config
 - **Workflows**: Resolved from `workflows` registered in Mastra config
-- **Sub-agents**: Resolved from `agents` registered in Mastra config
+- **Subagents**: Resolved from `agents` registered in Mastra config
 - **Memory**: Resolved from `memory` registered in Mastra config
 - **Scorers**: Resolved from `scorers` registered in Mastra config, including sampling configuration
 
@@ -68,7 +68,7 @@ When using `raw: true`, the returned object has the following structure:
 
 **workflows?:** (`Record<string, unknown>`): Workflow references to resolve from registry.
 
-**agents?:** (`Record<string, unknown>`): Sub-agent references to resolve from registry.
+**agents?:** (`Record<string, unknown>`): Subagent references to resolve from registry.
 
 **memory?:** (`Record<string, unknown>`): Memory reference to resolve from registry.
 

package/dist/docs/references/reference-core-listStoredAgents.md

@@ -61,7 +61,7 @@ When creating `Agent` instances (default behavior), each stored agent's configur
 
 - **Tools**: Resolved from `tools` registered in Mastra config
 - **Workflows**: Resolved from `workflows` registered in Mastra config
-- **Sub-agents**: Resolved from `agents` registered in Mastra config
+- **Subagents**: Resolved from `agents` registered in Mastra config
 - **Memory**: Resolved from `memory` registered in Mastra config
 - **Scorers**: Resolved from `scorers` registered in Mastra config
 

package/dist/docs/references/reference-memory-observational-memory.md

@@ -1,5 +1,7 @@
 # Observational Memory
 
+**Added in:** `@mastra/memory@1.1.0`
+
 Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** that watches conversations and creates observations, and a **Reflector** that restructures observations by combining related items, reflecting on overarching patterns, and condensing where possible — maintain an observation log that replaces raw message history as it grows.
 
 ## Usage
@@ -22,17 +24,15 @@ export const agent = new Agent({
 
 ## Configuration
 
-The `observationalMemory` option accepts `true`, `false`, or a configuration object.
-
-Setting `observationalMemory: true` enables it with all defaults. Setting `observationalMemory: false` or omitting it disables it.
+The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set — either at the top level, or on `observation.model` and/or `reflection.model`.
 
 **enabled?:** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to \`true\`. Only \`enabled: false\` explicitly disables it. (Default: `true`)
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with \`observation.model\` or \`reflection.model\` — an error will be thrown if both are set. When using \`observationalMemory: true\`, defaults to \`google/gemini-2.5-flash\`. When passing a config object, this or \`observation.model\`/\`reflection.model\` must be set. Use \`"default"\` to explicitly use the default model (\`google/gemini-2.5-flash\`). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
 
 **scope?:** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**shareTokenBudget?:** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. (Default: `false`)
+**shareTokenBudget?:** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \*\*Note:\*\* \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
 **observation?:** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -40,7 +40,7 @@ Setting `observationalMemory: true` enables it with all defaults. Setting `obser
 
 ### Observation config
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Observer agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`reflection.model\`.
 
 **messageTokens?:** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. (Default: `30000`)
 
@@ -48,14 +48,24 @@ Setting `observationalMemory: true` enables it with all defaults. Setting `obser
 
 **modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. (Default: `{ temperature: 0.3, maxOutputTokens: 100_000 }`)
 
+**bufferTokens?:** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. \`5000\`) or a fraction of \`messageTokens\` (e.g. \`0.25\` = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main \`messageTokens\` threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than \`messageTokens\`. Set to \`false\` to explicitly disable all async buffering (both observation and reflection). (Default: `0.2`)
+
+**bufferActivation?:** (`number`): Ratio (0-1) controlling how much of the message window to retain after activation. For example, \`0.8\` means activate enough to keep only 20% of \`messageTokens\` remaining. Higher values remove more message history per activation. (Default: `0.8`)
+
+**blockAfter?:** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled. (Default: `1.2 (when bufferTokens is set)`)
+
 ### Reflection config
 
-**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. (Default: `'google/gemini-2.5-flash'`)
+**model?:** (`string | LanguageModel | DynamicModel | ModelWithRetries[]`): Model for the Reflector agent. Cannot be set if a top-level \`model\` is also provided. If neither this nor the top-level \`model\` is set, falls back to \`observation.model\`.
 
 **observationTokens?:** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them. (Default: `40000`)
 
 **modelSettings?:** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. (Default: `{ temperature: 0, maxOutputTokens: 100_000 }`)
 
+**bufferActivation?:** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range. (Default: `0.5`)
+
+**blockAfter?:** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled. (Default: `1.2 (when bufferActivation is set)`)
+
 ### Model settings
 
 **temperature?:** (`number`): Temperature for generation. Lower values produce more consistent output. (Default: `0.3`)
@@ -77,6 +87,7 @@ export const agent = new Agent({
   memory: new Memory({
     options: {
       observationalMemory: {
+        model: "google/gemini-2.5-flash",
         scope: "resource",
         observation: {
           messageTokens: 20_000,
@@ -106,6 +117,7 @@ export const agent = new Agent({
         shareTokenBudget: true,
         observation: {
           messageTokens: 20_000,
+          bufferTokens: false, // required when using shareTokenBudget (temporary limitation)
         },
         reflection: {
           observationTokens: 80_000,
@@ -163,6 +175,305 @@ export const agent = new Agent({
 });
 ```
 
+### Async buffering
+
+Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows — when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
+
+The lifecycle is: **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+
+Default settings:
+
+- `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
+- `observation.bufferActivation: 0.8` — on activation, remove enough messages to keep only 20% of the threshold remaining
+- `reflection.bufferActivation: 0.5` — start background reflection at 50% of observation threshold
+
+To customize:
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "my-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5-mini",
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: "google/gemini-2.5-flash",
+        observation: {
+          messageTokens: 30_000,
+          // Buffer every 5k tokens (runs in background)
+          bufferTokens: 5_000,
+          // Activate to retain 30% of threshold
+          bufferActivation: 0.7,
+          // Force synchronous observation at 1.5x threshold
+          blockAfter: 1.5,
+        },
+        reflection: {
+          observationTokens: 60_000,
+          // Start background reflection at 50% of threshold
+          bufferActivation: 0.5,
+          // Force synchronous reflection at 1.2x threshold
+          blockAfter: 1.2,
+        },
+      },
+    },
+  }),
+});
+```
+
+To disable async buffering entirely:
+
+```typescript
+observationalMemory: {
+  model: "google/gemini-2.5-flash",
+  observation: {
+    bufferTokens: false,
+  },
+}
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. Observations and reflections will run synchronously when their thresholds are reached.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'` and is automatically disabled in resource scope.
+
+## Streaming data parts
+
+Observational Memory emits typed data parts during agent execution that clients can use for real-time UI feedback. These are streamed alongside the agent's response.
+
+### `data-om-status`
+
+Emitted once per agent loop step, before model generation. Provides a snapshot of the current memory state, including token usage for both context windows and the state of any async buffered content.
+
+```typescript
+interface DataOmStatusPart {
+  type: 'data-om-status';
+  data: {
+    windows: {
+      active: {
+        /** Unobserved message tokens and the threshold that triggers observation */
+        messages: { tokens: number; threshold: number };
+        /** Observation tokens and the threshold that triggers reflection */
+        observations: { tokens: number; threshold: number };
+      };
+      buffered: {
+        observations: {
+          /** Number of buffered chunks staged for activation */
+          chunks: number;
+          /** Total message tokens across all buffered chunks */
+          messageTokens: number;
+          /** Projected message tokens that would be removed if activation happened now (based on bufferActivation ratio and chunk boundaries) */
+          projectedMessageRemoval: number;
+          /** Observation tokens that will be added on activation */
+          observationTokens: number;
+          /** idle: no buffering in progress. running: background observer is working. complete: chunks are ready for activation. */
+          status: 'idle' | 'running' | 'complete';
+        };
+        reflection: {
+          /** Observation tokens that were fed into the reflector (pre-compression size) */
+          inputObservationTokens: number;
+          /** Observation tokens the reflection will produce on activation (post-compression size) */
+          observationTokens: number;
+          /** idle: no reflection buffered. running: background reflector is working. complete: reflection is ready for activation. */
+          status: 'idle' | 'running' | 'complete';
+        };
+      };
+    };
+    recordId: string;
+    threadId: string;
+    stepNumber: number;
+    /** Increments each time the Reflector creates a new generation */
+    generationCount: number;
+  };
+}
+```
+
+`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result — the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
+
+Clients can derive percentages and post-activation estimates from the raw values:
+
+```typescript
+// Message window usage %
+const msgPercent = status.windows.active.messages.tokens
+  / status.windows.active.messages.threshold;
+
+// Observation window usage %
+const obsPercent = status.windows.active.observations.tokens
+  / status.windows.active.observations.threshold;
+
+// Projected message tokens after buffered observations activate
+// Uses projectedMessageRemoval which accounts for bufferActivation ratio and chunk boundaries
+const postActivation = status.windows.active.messages.tokens
+  - status.windows.buffered.observations.projectedMessageRemoval;
+
+// Reflection compression ratio (when buffered reflection exists)
+const { inputObservationTokens, observationTokens } = status.windows.buffered.reflection;
+if (inputObservationTokens > 0) {
+  const compressionRatio = observationTokens / inputObservationTokens;
+}
+```
+
+### `data-om-observation-start`
+
+Emitted when the Observer or Reflector agent begins processing.
+
+**cycleId:** (`string`): Unique ID for this cycle — shared between start/end/failed markers.
+
+**operationType:** (`'observation' | 'reflection'`): Whether this is an observation or reflection operation.
+
+**startedAt:** (`string`): ISO timestamp when processing started.
+
+**tokensToObserve:** (`number`): Message tokens (input) being processed in this batch.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**threadIds:** (`string[]`): All thread IDs in this batch (for resource-scoped).
+
+**config:** (`ObservationMarkerConfig`): Snapshot of \`messageTokens\`, \`observationTokens\`, and \`scope\` at observation time.
+
+### `data-om-observation-end`
+
+Emitted when observation or reflection completes successfully.
+
+**cycleId:** (`string`): Matches the corresponding \`start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that completed.
+
+**completedAt:** (`string`): ISO timestamp when processing completed.
+
+**durationMs:** (`number`): Duration in milliseconds.
+
+**tokensObserved:** (`number`): Message tokens (input) that were processed.
+
+**observationTokens:** (`number`): Resulting observation tokens (output) after the Observer compressed them.
+
+**observations?:** (`string`): The generated observations text.
+
+**currentTask?:** (`string`): Current task extracted by the Observer.
+
+**suggestedResponse?:** (`string`): Suggested response extracted by the Observer.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-observation-failed`
+
+Emitted when observation or reflection fails. The system falls back to synchronous processing.
+
+**cycleId:** (`string`): Matches the corresponding \`start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+
+**failedAt:** (`string`): ISO timestamp when the failure occurred.
+
+**durationMs:** (`number`): Duration until failure in milliseconds.
+
+**tokensAttempted:** (`number`): Message tokens (input) that were attempted.
+
+**error:** (`string`): Error message.
+
+**observations?:** (`string`): Any partial content available for display.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-buffering-start`
+
+Emitted when async buffering begins in the background. Buffering pre-computes observations or reflections before the main threshold is reached.
+
+**cycleId:** (`string`): Unique ID for this buffering cycle.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation being buffered.
+
+**startedAt:** (`string`): ISO timestamp when buffering started.
+
+**tokensToBuffer:** (`number`): Message tokens (input) being buffered in this cycle.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**threadIds:** (`string[]`): All thread IDs being buffered (for resource-scoped).
+
+**config:** (`ObservationMarkerConfig`): Snapshot of config at buffering time.
+
+### `data-om-buffering-end`
+
+Emitted when async buffering completes. The content is stored but not yet activated in the main context.
+
+**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that was buffered.
+
+**completedAt:** (`string`): ISO timestamp when buffering completed.
+
+**durationMs:** (`number`): Duration in milliseconds.
+
+**tokensBuffered:** (`number`): Message tokens (input) that were buffered.
+
+**bufferedTokens:** (`number`): Observation tokens (output) after the Observer compressed them.
+
+**observations?:** (`string`): The buffered content.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-buffering-failed`
+
+Emitted when async buffering fails. The system falls back to synchronous processing when the threshold is reached.
+
+**cycleId:** (`string`): Matches the corresponding \`buffering-start\` marker.
+
+**operationType:** (`'observation' | 'reflection'`): Type of operation that failed.
+
+**failedAt:** (`string`): ISO timestamp when the failure occurred.
+
+**durationMs:** (`number`): Duration until failure in milliseconds.
+
+**tokensAttempted:** (`number`): Message tokens (input) that were attempted to buffer.
+
+**error:** (`string`): Error message.
+
+**observations?:** (`string`): Any partial content.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+### `data-om-activation`
+
+Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation — no LLM call is involved.
+
+**cycleId:** (`string`): Unique ID for this activation event.
+
+**operationType:** (`'observation' | 'reflection'`): Type of content activated.
+
+**activatedAt:** (`string`): ISO timestamp when activation occurred.
+
+**chunksActivated:** (`number`): Number of buffered chunks activated.
+
+**tokensActivated:** (`number`): Message tokens (input) from activated chunks. For observation activation, these are removed from the message window. For reflection activation, this is the observation tokens that were compressed.
+
+**observationTokens:** (`number`): Resulting observation tokens after activation.
+
+**messagesActivated:** (`number`): Number of messages that were observed via activation.
+
+**generationCount:** (`number`): Current reflection generation count.
+
+**observations?:** (`string`): The activated observations text.
+
+**recordId:** (`string`): The OM record ID.
+
+**threadId:** (`string`): This thread's ID.
+
+**config:** (`ObservationMarkerConfig`): Snapshot of config at activation time.
+
 ## Standalone usage
 
 Most users should use the `Memory` class above. Using `ObservationalMemory` directly is mainly useful for benchmarking, experimentation, or when you need to control processor ordering with other processors (like [guardrails](https://mastra.ai/docs/agents/guardrails)).

package/dist/docs/references/reference-tools-mcp-client.md

@@ -2,8 +2,6 @@
 
 The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
 
-This class replaces the deprecated [`MastraMCPClient`](https://mastra.ai/reference/tools/client).
-
 ## Constructor
 
 Creates a new instance of the MCPClient class.

package/dist/docs/references/reference-workflows-step.md

@@ -84,6 +84,8 @@ const agentStep = createStep(testAgent, {
 
 **execute:** (`(params: ExecuteParams) => Promise<any>`): Async function containing step logic
 
+**metadata:** (`Record<string, any>`): Optional key-value pairs for storing additional step information. Values must be serializable (no functions, circular references, etc.).
+
 ### ExecuteParams
 
 **inputData:** (`z.infer<TStepInput>`): The input data matching the inputSchema

package/dist/docs/references/reference-workflows-workflow-methods-map.md

@@ -5,7 +5,7 @@ The `.map()` method maps output data from a previous step to the input of a subs
 ## Usage example
 
 ```typescript
-workflow.map(async ({ inputData }) => `${inputData.value} - map`
+workflow.map(async ({ inputData }) => `${inputData.value} - map`)
 ```
 
 ## Parameters
@@ -45,7 +45,7 @@ Use `getInitData<typeof workflow>()` to access the initial input data provided t
 ```typescript
 .then(step1)
   .map(async ({ getInitData }) => {
-      console.log(getInitData());
+    console.log(getInitData<any>());
   })
 ```
 

package/dist/docs/references/reference-workspace-filesystem.md

@@ -1,5 +1,7 @@
 # WorkspaceFilesystem
 
+**Added in:** `@mastra/core@1.1.0`
+
 The `WorkspaceFilesystem` interface defines how workspaces interact with file storage.
 
 ## Methods

package/dist/docs/references/reference-workspace-local-filesystem.md

@@ -1,5 +1,7 @@
 # LocalFilesystem
 
+**Added in:** `@mastra/core@1.1.0`
+
 Stores files in a directory on the local filesystem.
 
 > **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).

package/dist/docs/references/reference-workspace-local-sandbox.md

@@ -1,5 +1,7 @@
 # LocalSandbox
 
+**Added in:** `@mastra/core@1.1.0`
+
 Executes commands on the local system.
 
 > **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).

package/dist/docs/references/reference-workspace-sandbox.md

@@ -1,5 +1,7 @@
 # WorkspaceSandbox
 
+**Added in:** `@mastra/core@1.1.0`
+
 The `WorkspaceSandbox` interface defines how workspaces execute commands.
 
 ## Methods

package/dist/docs/references/reference-workspace-workspace-class.md

@@ -1,5 +1,7 @@
 # Workspace Class
 
+**Added in:** `@mastra/core@1.1.0`
+
 The `Workspace` class combines a filesystem and sandbox to provide agents with file storage and command execution capabilities. It also supports BM25 and vector search for indexed content.
 
 ## Usage Example