@mastra/mcp-docs-server 1.2.15-alpha.1 → 1.2.15-alpha.6

package/.docs/docs/agents/a2a.md

@@ -2,7 +2,7 @@
 
 # A2A (Agent-to-Agent)
 
-Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+Mastra supports version 0.3.0 of the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
 
 A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 
@@ -57,6 +57,18 @@ A2A represents work as messages and tasks. Messages carry text, file, or structu
 
 Tasks are stateful units of work with IDs and lifecycle states. Clients can follow long-running work and send follow-up turns. They can also cancel work or resubscribe after a disconnect.
 
+## Protocol versions
+
+Mastra supports A2A Protocol v0.3 and v1.0 on the same agent card and execution URLs. The `A2A-Version` request header selects the wire protocol:
+
+- Missing, empty, or `0.3`: Uses the existing v0.3 API.
+- `1.0`: Uses the v1.0 API.
+- Any other value: Returns a `VersionNotSupported` protocol error.
+
+Existing `A2AAgent` and `MastraClient.getA2A()` integrations continue to use v0.3. Use `MastraClient.getA2AV1()` for v1.0 requests. The v1 client sends `A2A-Version: 1.0` automatically and adds the `tasks/list` operation.
+
+Import v1.0 protocol types and codecs from `@mastra/core/a2a/v1`. The existing `@mastra/core/a2a/client` export remains on v0.3.
+
 ## Get started
 
 A2A has two common paths in Mastra:
@@ -155,6 +167,33 @@ for await (const event of updates) {
 }
 ```
 
+### Use the v1.0 client
+
+Use `getA2AV1()` to opt into the A2A v1.0 wire protocol. The protocol package provides codecs for creating v1 request values from JSON-shaped input:
+
+```typescript
+import { ListTasksRequest } from '@mastra/core/a2a/v1'
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'https://agent.example.com',
+})
+
+const a2a = client.getA2AV1('weather-agent')
+const response = await a2a.listTasks(
+  ListTasksRequest.fromJSON({
+    contextId: 'customer-support',
+    pageSize: 20,
+  }),
+)
+
+for (const task of response.tasks) {
+  console.log(task.id, task.status)
+}
+```
+
+The v1.0 client supports `getAgentCard()`, `sendMessage()`, `sendMessageStream()`, `getTask()`, `listTasks()`, `cancelTask()`, and `resubscribeTask()`.
+
 ## Configure subagent calls
 
 `A2AAgent` accepts request options for authenticated or constrained environments:
@@ -176,6 +215,38 @@ const remoteWeatherAgent = new A2AAgent({
 
 You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
 
+## Human-in-the-loop
+
+A2A models human-in-the-loop (HITL) work with the `input-required` task state. When a task pauses for input, the client provides the missing input by sending a follow-up message with the same `taskId`, and the server continues the task.
+
+Mastra maps its agent suspension model to this state in both directions:
+
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/api/.well-known/booking-agent/agent-card.json',
+})
+
+const result = await agent.generate('Book a flight to Paris', { runId: 'run-1' })
+
+if (result.finishReason === 'suspended') {
+  // Inspect result.suspendPayload, collect input from a human,
+  // then resume the remote task.
+  const resumed = await agent.resumeGenerate({ approved: true }, { runId: 'run-1' })
+  console.log(resumed.text)
+}
+```
+
+Follow-up messages for an `input-required` task can carry the resume data as a structured data part, or as JSON or plain text in a text part.
+
+When a resumed run requires additional input, the task returns to `input-required` and the flow repeats. Resuming a suspended run requires storage configured on the Mastra server so the suspended run state can be restored across requests.
+
+> **Note:** A2A task records live in an in-memory store, so a paused task can only be resumed by the same server process that suspended it. A server restart or a horizontally scaled deployment without sticky routing loses the task record, and a follow-up message fails with a task-not-found error.
+
 ## Push notifications
 
 Mastra supports A2A push notifications for remote agents that advertise `capabilities.pushNotifications`. Use push notifications when a client can't keep a stream open, or when a long-running task should update a callback URL after the original request ends.
@@ -192,7 +263,9 @@ await a2a.setTaskPushNotificationConfig({
 })
 ```
 
-Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, or `input-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+Mastra Server sends the current task snapshot to registered callbacks when the task reaches `completed`, `failed`, `canceled`, `rejected`, `input-required`, or `auth-required`. Push notification delivery is best-effort. Protect callback URLs, validate notification tokens, and avoid exposing internal network targets as push notification destinations.
+
+Push notification configurations are stored in memory and must be registered again after a server restart.
 
 ## Sign and verify agent cards
 

package/.docs/docs/agents/processors.md

@@ -544,6 +544,8 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
+Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+
 #### Customize the cache key
 
 Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):

package/.docs/docs/agents/skills.md

@@ -123,7 +123,21 @@ export const agent = new Agent({
 })
 ```
 
-The resolver function receives `{ requestContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+The resolver function receives `{ requestContext, tracingContext }` and returns a `SkillInput[]` array or a `Promise<SkillInput[]>`.
+
+The resolver runs once per `RequestContext`. During an agent execution it runs inside a `resolve-skills` span, and `tracingContext.currentSpan` lets you create child spans for your own work, the same way tools do. The resolver also runs on metadata reads such as `agent.listSkills()` and the server's agent endpoints, where no span exists and `tracingContext.currentSpan` is `undefined`, so keep it fast and guard any span usage:
+
+```typescript
+skills: async ({ requestContext, tracingContext }) => {
+  const span = tracingContext?.currentSpan?.createChildSpan({
+    type: 'generic',
+    name: 'entitlements-lookup',
+  })
+  const skills = await fetchSkillsFor(requestContext.get('userId'))
+  span?.end()
+  return skills
+}
+```
 
 See [Request Context](https://mastra.ai/docs/server/request-context) for more on using request context with agents and workflows.
 

package/.docs/docs/capabilities/subagents.md

@@ -104,11 +104,29 @@ const stream = await parentAgent.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                               |
-| ------------- | ----------------------------------------- |
-| `primitiveId` | The ID of the subagent being delegated to |
-| `prompt`      | The prompt the parent agent is sending    |
-| `iteration`   | Current iteration number                  |
+| Property         | Description                                       |
+| ---------------- | ------------------------------------------------- |
+| `primitiveId`    | The ID of the subagent being delegated to         |
+| `prompt`         | The prompt the parent agent is sending            |
+| `iteration`      | Current iteration number                          |
+| `requestContext` | The request context the subagent run will receive |
+
+### Request context at the delegation boundary
+
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+
+```typescript
+const stream = await parentAgent.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationStart: async context => {
+      context.requestContext.set('audience', 'technical')
+    },
+  },
+})
+```
+
+The subagent reads these entries in its tools and dynamic configuration, such as `instructions: ({ requestContext }) => ...`. See [Request Context](https://mastra.ai/docs/server/request-context) for details. Values must be JSON-serializable to work with durable agents.
 
 ### `onDelegationComplete`
 

package/.docs/docs/connections/overview.md

@@ -0,0 +1,94 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Connections overview
+
+Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
+
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+
+## When to use connections
+
+Use connections when you need to:
+
+- Delegate work to an agent running in another service or runtime.
+- Run a coding agent against a project workspace.
+- Add a provider-native agent without replacing its SDK runtime or agent loop.
+- Connect agents to external tools and resources or publish Mastra capabilities to other systems.
+
+## Get started
+
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+
+**A2A**:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const agent = new A2AAgent({
+  url: 'https://agent.example.com/.well-known/agent-card.json',
+})
+
+const result = await agent.generate('Summarize the latest report')
+console.log(result.text)
+```
+
+**ACP**:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+const agent = new AcpAgent({
+  id: 'coding-agent',
+  description: 'Inspects and edits code',
+  command: 'claude',
+  args: ['--acp'],
+  persistSession: false,
+})
+
+const result = await agent.generate('Review this project')
+console.log(result.text)
+```
+
+**SDK agents**:
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const agent = new OpenAISDKAgent({
+  id: 'openai-agent',
+  description: 'Answers project questions',
+  sdkOptions: {
+    name: 'Project assistant',
+    model: 'gpt-5',
+  },
+})
+
+const result = await agent.generate('Explain agent loops in one sentence')
+console.log(result.text)
+```
+
+**MCP**:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const client = new MCPClient({
+  id: 'wikipedia-client',
+  servers: {
+    wikipedia: {
+      command: 'npx',
+      args: ['-y', 'wikipedia-mcp'],
+    },
+  },
+})
+
+try {
+  const tools = await client.listTools()
+  console.log(Object.keys(tools))
+} finally {
+  await client.disconnect()
+}
+```

package/.docs/docs/datasets/running-experiments.md

@@ -58,6 +58,24 @@ const summary = await dataset.startExperiment({
 
 Each item's `input` is passed directly to `agent.generate()`, so it must be a `string`, `string[]`, or `CoreMessage[]`.
 
+#### Memory-enabled agents
+
+When the target agent has its own memory and the request context carries a resource id (`MASTRA_RESOURCE_ID_KEY`, set by auth middleware, the experiment or item `requestContext`, or the Studio **Run Experiment** form), the experiment runner injects a fresh memory thread for each item. A resource id in the request context means "run as this resource": each item's conversation persists as a thread under that resource, and retried items get a new thread per attempt so earlier failed attempts can't leak into the retry's context.
+
+Injected threads are tagged so you can map them back to the run: thread metadata carries the `experimentId` and the dataset item's id as `experimentItemId`. No thread title is generated for them.
+
+Because the threads belong to the caller's resource, resource-scoped memory features both read and write that resource's state during the run:
+
+- Resource-scoped working memory updates persist to the resource, and later items in the run see updates made by earlier items.
+- Resource-scoped semantic recall can surface the resource's prior conversations to the experiment, and experiment transcripts become recallable in that resource's later conversations.
+
+This is useful when you want to evaluate an agent against a real user's accumulated context. If you don't want experiment runs touching real user state, run the experiment with a dedicated evaluation resource id instead.
+
+Thread injection is skipped in the following cases:
+
+- If the request context also sets `MASTRA_THREAD_ID_KEY`, the runner uses that thread as-is, so every item (and retry) shares the same conversation.
+- If the agent has no memory, or the request context has no resource id, the run is memoryless and nothing is persisted.
+
 ### Registered workflow
 
 Point to a workflow registered on your Mastra instance:

package/.docs/docs/evals/overview.md

@@ -75,7 +75,7 @@ export const evaluatedAgent = new Agent({
 
 ### Adding scorers to workflow steps
 
-You can also add scorers to individual workflow steps to evaluate outputs at specific points in your process:
+You can also add scorers to individual workflow steps to evaluate outputs at specific points in your process. Each scorer receives that step's own input and output, so you can measure quality at each step instead of only scoring the final answer:
 
 ```typescript
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -83,22 +83,34 @@ import { z } from "zod";
 import { customStepScorer } from "../scorers/custom-step-scorer";
 
 const contentStep = createStep({
+  id: "content-step",
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ content: z.string() }),
   scorers: {
     customStepScorer: {
       scorer: customStepScorer(),
       sampling: {
         type: "ratio",
         rate: 1, // Score every step execution
-      }
-    }
+      },
+    },
+  },
+  execute: async ({ inputData }) => {
+    return { content: await generateContent(inputData.topic) };
   },
 });
 
-export const contentWorkflow = createWorkflow({ ... })
+export const contentWorkflow = createWorkflow({
+  id: "content-workflow",
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({ content: z.string() }),
+})
   .then(contentStep)
   .commit();
 ```
 
+For the step-level `scorers` API, see the [Step class reference](https://mastra.ai/reference/workflows/step).
+
 ### How live evaluations work
 
 **Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. This ensures your AI systems maintain their performance while still being monitored.

package/.docs/docs/harness/agent-controller.md

@@ -322,6 +322,10 @@ const controller = new AgentController({
       if (thread.isDM) return message.author.userId
       return defaultResourceId
     },
+    onSessionStart: async ({ session, thread }) => {
+      const plan = await billing.planFor(thread.resourceId)
+      await session.model.switch({ modelId: plan.modelId })
+    },
   },
 })
 
@@ -339,6 +343,8 @@ Point each platform webhook at the controller-specific route:
 
 Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
 
+Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. Use it to apply a model, memory settings, or session state that a channel session would otherwise miss. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 
 See [Channels](https://mastra.ai/docs/capabilities/channels/overview) for adapter setup and platform-specific webhook configuration.

package/.docs/docs/harness/overview.md

@@ -0,0 +1,26 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Harness overview
+
+A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
+
+In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
+
+[`AgentController`](https://mastra.ai/docs/harness/agent-controller) is a harness designed for interactive agent applications. It extends the base [`Agent`](https://mastra.ai/docs/agents/overview) loop with isolated sessions for each user or task, persistent threads and state, switchable modes and models, tool permissions and approvals, subagent orchestration, and streams for events and display state.
+
+Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
+
+## When to use a harness
+
+Choose a starting point based on what the agent needs. You may use one capability or several.
+
+| If you want to                                                                        | Start here                                                                      | Why                                                                               |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Keep a run available through client disconnects or server restarts                    | [Durable Agents](https://mastra.ai/docs/long-running-agents/durable-agents)     | Persist run state and let clients reconnect to its stream.                        |
+| Run slow tools, workflows, or subagents without blocking                              | [Background Tasks](https://mastra.ai/docs/long-running-agents/background-tasks) | Finish work asynchronously and return its result to the agent.                    |
+| Keep an agent working until it reaches an objective                                   | [Goals](https://mastra.ai/docs/long-running-agents/goals)                       | Evaluate a thread-scoped objective until it's complete or reaches its run budget. |
+| Start work automatically at recurring times                                           | [Schedules](https://mastra.ai/docs/long-running-agents/schedules)               | Start isolated runs or send prompts into an existing thread on a cron schedule.   |
+| Add context, redirect active work, or wake an idle thread                             | [Signals](https://mastra.ai/docs/long-running-agents/signals)                   | Deliver input now or hold it for the next turn.                                   |
+| React to changes in GitHub, Slack, continuous integration, or another external system | [Signal Providers](https://mastra.ai/docs/long-running-agents/signal-providers) | Track subscriptions and forward matching events to agent threads.                 |
+| Build an interactive product with sessions, modes, state, approvals, and events       | [AgentController](https://mastra.ai/docs/harness/agent-controller)              | Host isolated sessions around a shared agent runtime.                             |
+| Let users steer, queue follow-up work, or stop an interactive run                     | [AgentController](https://mastra.ai/docs/harness/agent-controller)              | Expose run controls through each session.                                         |

package/.docs/docs/index.md

@@ -132,7 +132,7 @@ npm create mastra@latest
 **pnpm**:
 
 ```bash
-pnpm create mastra
+pnpm create mastra@latest
 ```
 
 **Yarn**:

package/.docs/docs/mcp/overview.md

@@ -142,6 +142,16 @@ requireToolApproval: ({ toolName }) => toolName.startsWith('delete_')
 
 Treat tool annotations from servers you don't control as untrusted hints. Visit [tool approval](https://mastra.ai/reference/tools/mcp-client) for the callback context and security guidance.
 
+### Security
+
+MCP servers run code and return content on your agent's behalf, so configure them with the same care as any other external dependency:
+
+- **Stdio subprocess environment**: subprocesses inherit only the MCP SDK's curated environment whitelist (for example `PATH` and `HOME` on POSIX), not the full parent environment. Set `inheritDefaultEnv: false` on a server to pass only the variables you list in `env`.
+- **Outbound host restriction**: when HTTP server URLs come from untrusted configuration, set `allowedHosts` to restrict which hosts the client will contact. On the default fetch path this also blocks redirect hops before they're sent; a custom `fetch` gets its final response URL validated after the request runs, so it must enforce redirect policy itself when preventing outbound contact is required.
+- **Tool response trust**: tool results are untrusted model input. Use [input and output processors](https://mastra.ai/docs/agents/processors) to inspect or sanitize content before it reaches the model, and `requireToolApproval` to gate sensitive tools.
+
+Visit the [MCPClient security reference](https://mastra.ai/reference/tools/mcp-client) for enforcement details of each option.
+
 ### MCP registries
 
 Registries provide hosted or packaged MCP servers. The client configuration above works with registry endpoints and commands.

package/.docs/docs/observability/feedback.md

@@ -33,6 +33,22 @@ await mastra.observability.addFeedback({
 })
 ```
 
+## Find the trace for a message
+
+Feedback is usually collected against a message a user has already read, so you need the `traceId` for that message. Assistant messages carry it in `content.metadata`, both in the stream result and when the message is recalled later from memory:
+
+```typescript
+const agent = mastra.getAgent('weatherAgent')
+const memory = await agent.getMemory()
+
+const { messages } = await memory!.recall({ threadId, perPage: false })
+
+const message = messages.find(m => m.id === messageId)
+const traceId = message?.content.metadata?.traceId
+```
+
+The value is the same trace the run reports as `traceId` on its result, so feedback collected at generation time and feedback collected later against a stored message anchor to the same trace. Messages produced while tracing is disabled have no `traceId`.
+
 ## Create feedback
 
 Every `createFeedback()` requires `feedbackType` and `value`. Add `traceId` or `spanId` when the feedback should be anchored to a trace or a specific span. Use `feedbackSource` as optional string metadata, such as `user`, `qa`, `studio`, or `system`.

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -393,16 +393,17 @@ Use Custom UI when you want to:
 
 Mastra streams data to the frontend as "parts" within messages. Each part has a `type` that determines how to render it. The `@mastra/ai-sdk` package transforms Mastra streams into AI SDK-compatible [UI Message DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart).
 
-| Data Part Type       | Source                  | Description                                                                        |
-| -------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
-| `tool-{toolKey}`     | AI SDK built-in         | Tool invocation with states: `input-available`, `output-available`, `output-error` |
-| `data-workflow`      | `workflowRoute()`       | Workflow execution state snapshots with step status and final outputs              |
-| `data-workflow-step` | `workflowRoute()`       | Workflow step delta with the full payload for the changed step                     |
-| `data-network`       | `networkRoute()`        | Agent network execution with ordered steps and outputs                             |
-| `data-tool-agent`    | Nested agent in tool    | Agent output streamed from within a tool's `execute()`                             |
-| `data-tool-workflow` | Nested workflow in tool | Workflow output streamed from within a tool's `execute()`                          |
-| `data-tool-network`  | Nested network in tool  | Network output streamed from within a tool's `execute()`                           |
-| `data-{custom}`      | `writer.custom()`       | Custom events for progress indicators, status updates, etc.                        |
+| Data Part Type         | Source                  | Description                                                                        |
+| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `tool-{toolKey}`       | AI SDK built-in         | Tool invocation with states: `input-available`, `output-available`, `output-error` |
+| `data-workflow`        | `workflowRoute()`       | Workflow execution state snapshots with step status and final outputs              |
+| `data-workflow-step`   | `workflowRoute()`       | Workflow step delta with the full payload for the changed step                     |
+| `data-network`         | `networkRoute()`        | Agent network execution with ordered steps and outputs                             |
+| `data-tool-agent`      | Nested agent in tool    | Compact nested-agent snapshot while the current step is still running              |
+| `data-tool-agent-step` | Nested agent in tool    | Full nested-agent step payload emitted when a nested step finishes                 |
+| `data-tool-workflow`   | Nested workflow in tool | Workflow output streamed from within a tool's `execute()`                          |
+| `data-tool-network`    | Nested network in tool  | Network output streamed from within a tool's `execute()`                           |
+| `data-{custom}`        | `writer.custom()`       | Custom events for progress indicators, status updates, etc.                        |
 
 ### Rendering tool outputs
 
@@ -1256,7 +1257,7 @@ For a complete implementation, see the [workflow-suspend-resume example](https:/
 
 ### Nested agent streams in tools
 
-Tools can call agents internally and stream the agent's output back to the UI. This creates `data-tool-agent` parts that can be rendered alongside the tool's final output.
+Tools can call agents internally and stream the agent's output back to the UI. This creates compact `data-tool-agent` snapshots while the nested step is still running, `data-tool-agent-step` parts when a nested step finishes, and one full `data-tool-agent` snapshot when the nested run finishes.
 
 The pattern uses:
 
@@ -1315,13 +1316,13 @@ export const forecastAgent = new Agent({
 
 **Frontend**:
 
-Handle `data-tool-agent` parts to display the nested agent's streamed output.
+Handle `data-tool-agent` parts for the live snapshot and `data-tool-agent-step` parts for the completed nested step payload.
 
 ```typescript
 import { useChat } from '@ai-sdk/react'
 import { DefaultChatTransport } from 'ai'
 import { useState } from 'react'
-import type { AgentDataPart } from '@mastra/ai-sdk'
+import type { AgentDataPart, AgentStepDataPart } from '@mastra/ai-sdk'
 
 export function NestedAgentChat() {
   const [input, setInput] = useState('')
@@ -1361,6 +1362,15 @@ export function NestedAgentChat() {
                 </div>
               )
             }
+            if (part.type === 'data-tool-agent-step') {
+              const { data } = part as AgentStepDataPart
+              return (
+                <div key={index} className="nested-agent-step">
+                  <strong>Completed nested step {data.stepIndex + 1}</strong>
+                  {data.step.text && <p>{data.step.text}</p>}
+                </div>
+              )
+            }
             return null
           })}
         </div>
@@ -1373,7 +1383,8 @@ export function NestedAgentChat() {
 Key points:
 
 - Piping `fullStream` to `context.writer` creates `data-tool-agent` parts
-- The `AgentDataPart` has `id` (on the part) and `data.text` (the agent's streamed text)
+- Read `data-tool-agent-step` when you need the full payload for the nested step that just finished
+- The `AgentDataPart` has `id` (on the part) and `data.text` (the current nested-agent text snapshot)
 - The tool still returns its own output after the stream completes
 
 For a complete implementation, see the [tool-nested-streams example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/tool-nested-streams.tsx) in UI Dojo.

package/.docs/guides/getting-started/quickstart.md

@@ -27,7 +27,7 @@ npm create mastra@latest
 **pnpm**:
 
 ```bash
-pnpm create mastra
+pnpm create mastra@latest
 ```
 
 **Yarn**:

package/.docs/models/gateways/neon.md

@@ -2,7 +2,7 @@
 
 # ![Neon logo](https://models.dev/logos/neon.svg)Neon
 
-Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 36 models through Mastra's model router.
+Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 42 models through Mastra's model router.
 
 Learn more in the [Neon documentation](https://neon.com/docs).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "neon/claude-haiku-4-5"
+  model: "neon/claude-fable-5"
 });
 ```
 
@@ -33,37 +33,43 @@ NEON_AI_GATEWAY_TOKEN=your-gateway-key
 
 | Model                         |
 | ----------------------------- |
+| `claude-fable-5`              |
 | `claude-haiku-4-5`            |
 | `claude-opus-4-1`             |
 | `claude-opus-4-5`             |
 | `claude-opus-4-6`             |
 | `claude-opus-4-7`             |
 | `claude-opus-4-8`             |
-| `claude-sonnet-4`             |
+| `claude-opus-5`               |
 | `claude-sonnet-4-5`           |
 | `claude-sonnet-4-6`           |
-| `gemini-2-5-flash`            |
-| `gemini-2-5-pro`              |
+| `claude-sonnet-5`             |
 | `gemini-3-1-flash-lite`       |
 | `gemini-3-1-pro`              |
 | `gemini-3-5-flash`            |
+| `gemini-3-5-flash-lite`       |
+| `gemini-3-6-flash`            |
 | `gemini-3-flash`              |
-| `gemini-3-pro`                |
 | `gemma-3-12b`                 |
+| `glm-5-2`                     |
 | `gpt-5`                       |
 | `gpt-5-1`                     |
-| `gpt-5-1-codex-max`           |
-| `gpt-5-1-codex-mini`          |
 | `gpt-5-2`                     |
-| `gpt-5-2-codex`               |
 | `gpt-5-3-codex`               |
 | `gpt-5-4`                     |
 | `gpt-5-4-mini`                |
 | `gpt-5-4-nano`                |
+| `gpt-5-5`                     |
+| `gpt-5-5-pro`                 |
+| `gpt-5-6-luna`                |
+| `gpt-5-6-sol`                 |
+| `gpt-5-6-terra`               |
 | `gpt-5-mini`                  |
 | `gpt-5-nano`                  |
 | `gpt-oss-120b`                |
 | `gpt-oss-20b`                 |
+| `inkling`                     |
+| `kimi-k3`                     |
 | `llama-4-maverick`            |
 | `meta-llama-3-1-8b-instruct`  |
 | `meta-llama-3-3-70b-instruct` |

package/.docs/models/gateways/netlify.md

@@ -2,7 +2,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 67 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 66 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -84,7 +84,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-5.2-2025-12-11`                 |
 | `openai/gpt-5.2-pro`                        |
 | `openai/gpt-5.2-pro-2025-12-11`             |
-| `openai/gpt-5.3-chat-latest`                |
 | `openai/gpt-5.3-codex`                      |
 | `openai/gpt-5.4`                            |
 | `openai/gpt-5.4-2026-03-05`                 |