@mastra/mcp-docs-server 1.2.1-alpha.2 → 1.2.1-alpha.4

package/.docs/guides/concepts/streaming.md

@@ -0,0 +1,317 @@
+# Streaming
+
+Mastra supports real-time, incremental responses from agents and workflows, allowing users to see output as it’s generated instead of waiting for completion. This is useful for chat, long-form content, multi-step workflows, or any scenario where immediate feedback matters.
+
+## Getting started
+
+Mastra's streaming API adapts based on your model version:
+
+- **`.stream()`**: For V2 models, supports **AI SDK v5** and later (`LanguageModelV2`).
+- **`.streamLegacy()`**: For V1 models, supports **AI SDK v4** (`LanguageModelV1`).
+
+## Streaming with agents
+
+You can pass a single string for basic prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+
+### Using `Agent.stream()`
+
+A `textStream` breaks the response into chunks as it's generated, allowing output to stream progressively instead of arriving all at once. Iterate over the `textStream` using a `for await` loop to inspect each stream chunk.
+
+```typescript
+const testAgent = mastra.getAgent('testAgent')
+
+const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
+
+> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
+
+### Output from `Agent.stream()`
+
+The output streams the generated response from the agent.
+
+```text
+Of course!
+To help you organize your day effectively, I need a bit more information.
+Here are some questions to consider:
+...
+```
+
+### Agent stream properties
+
+An agent stream provides access to various response properties:
+
+- **`stream.textStream`**: A readable stream that emits text chunks.
+- **`stream.text`**: Promise that resolves to the full text response.
+- **`stream.finishReason`**: The reason the agent stopped streaming.
+- **`stream.usage`**: Token usage information.
+
+### AI SDK v5+ Compatibility
+
+AI SDK v5 (and later) uses `LanguageModelV2` for the model providers. If you are getting an error that you are using an AI SDK v4 model you will need to upgrade your model package to the next major version.
+
+For integration with AI SDK v5+, use the `toAISdkV5Stream()` utility from `@mastra/ai-sdk` to convert Mastra streams to AI SDK-compatible format:
+
+```typescript
+import { toAISdkV5Stream } from '@mastra/ai-sdk'
+
+const testAgent = mastra.getAgent('testAgent')
+
+const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
+
+// Convert to AI SDK v5+ compatible stream
+const aiSDKStream = toAISdkV5Stream(stream, { from: 'agent' })
+```
+
+For converting messages to AI SDK v5+ format, use the `toAISdkV5Messages()` utility from `@mastra/ai-sdk/ui`:
+
+```typescript
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+
+const messages = [{ role: 'user', content: 'Hello' }]
+const aiSDKMessages = toAISdkV5Messages(messages)
+```
+
+## Streaming with workflows
+
+Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRun()`.
+
+### Using `Run.stream()`
+
+The `stream()` method returns a `ReadableStream` of events directly.
+
+```typescript
+const run = await testWorkflow.createRun()
+
+const stream = await run.stream({
+  inputData: {
+    value: 'initial data',
+  },
+})
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+> **Info:** Visit [Run.stream()](https://mastra.ai/reference/streaming/workflows/stream) for more information.
+
+### Output from `Run.stream()`
+
+The event structure includes `runId` and `from` at the top level, making it easier to identify and track workflow runs without digging into the payload.
+
+```typescript
+{
+  type: 'workflow-start',
+  runId: '1eeaf01a-d2bf-4e3f-8d1b-027795ccd3df',
+  from: 'WORKFLOW',
+  payload: {
+    stepName: 'step-1',
+    args: { value: 'initial data' },
+    stepCallId: '8e15e618-be0e-4215-a5d6-08e58c152068',
+    startedAt: 1755121710066,
+    status: 'running'
+  }
+}
+```
+
+### Workflow stream properties
+
+A workflow stream provides access to various response properties:
+
+- **`stream.status`**: The status of the workflow run.
+- **`stream.result`**: The result of the workflow run.
+- **`stream.usage`**: The total token usage of the workflow run.
+
+Streaming from agents or workflows provides real-time visibility into either the LLM’s output or the status of a workflow run. This feedback can be passed directly to the user, or used within applications to handle workflow status more effectively, creating a smoother and more responsive experience.
+
+Events emitted from agents or workflows represent different stages of generation and execution, such as when a run starts, when text is produced, or when a tool is invoked.
+
+## Event types
+
+Below is a complete list of events emitted from `.stream()`. Depending on whether you’re streaming from an **agent** or a **workflow**, only a subset of these events will occur:
+
+- **start**: Marks the beginning of an agent or workflow run.
+- **step-start**: Indicates a workflow step has begun execution.
+- **text-delta**: Incremental text chunks as they're generated by the LLM.
+- **tool-call**: When the agent decides to use a tool, including the tool name and arguments.
+- **tool-result**: The result returned from tool execution.
+- **step-finish**: Confirms that a specific step has fully finalized, and may include metadata like the finish reason for that step.
+- **finish**: When the agent or workflow completes, including usage statistics.
+
+## Inspecting agent streams
+
+Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
+
+```typescript
+const testAgent = mastra.getAgent('testAgent')
+
+const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
+
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+> **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
+
+### Example agent output
+
+Below is an example of events that may be emitted. Each event always includes a `type` and can include additional fields like `from` and `payload`.
+
+```typescript
+{
+  type: 'start',
+  from: 'AGENT',
+  // ..
+}
+{
+  type: 'step-start',
+  from: 'AGENT',
+  payload: {
+    messageId: 'msg-cdUrkirvXw8A6oE4t5lzDuxi',
+    // ...
+  }
+}
+{
+  type: 'tool-call',
+  from: 'AGENT',
+  payload: {
+    toolCallId: 'call_jbhi3s1qvR6Aqt9axCfTBMsA',
+    toolName: 'testTool'
+    // ..
+  }
+}
+```
+
+## Writer API
+
+The `writer` API is shared by tools and workflow steps — see the Tools and Workflows docs for feature-specific examples.
+
+## Agent using tool
+
+Agent streaming can be combined with tool calls, allowing tool outputs to be written directly into the agent’s streaming response. This makes it possible to surface tool activity as part of the overall interaction.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { testTool } from '../tools/test-tool'
+
+export const testAgent = new Agent({
+  id: 'test-agent',
+  name: 'Test Agent',
+  instructions: 'You are a weather agent.',
+  model: 'openai/gpt-5.5',
+  tools: { testTool },
+})
+```
+
+### Using `context.writer`
+
+The `context.writer` object is available in a tool's `execute()` function and can be used to emit custom events, data, or values into the active stream. This enables tools to provide intermediate results or status updates while execution is still in progress.
+
+> **Warning:** You must `await` the call to `writer.write()` or else you will lock the stream and get a `WritableStream is locked` error.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+
+export const testTool = createTool({
+  execute: async (inputData, context) => {
+    const { value } = inputData
+
+    await context?.writer?.write({
+      type: 'custom-event',
+      status: 'pending',
+    })
+
+    const response = await fetch()
+
+    await context?.writer?.write({
+      type: 'custom-event',
+      status: 'success',
+    })
+
+    return {
+      value: '',
+    }
+  },
+})
+```
+
+You can also use `writer.custom()` to emit top-level stream chunks. This is useful when integrating with UI frameworks.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+
+export const testTool = createTool({
+  execute: async (inputData, context) => {
+    const { value } = inputData
+
+    await context?.writer?.custom({
+      type: 'data-tool-progress',
+      status: 'pending',
+    })
+
+    const response = await fetch()
+
+    await context?.writer?.custom({
+      type: 'data-tool-progress',
+      status: 'success',
+    })
+
+    return {
+      value: '',
+    }
+  },
+})
+```
+
+### Transient data chunks
+
+By default, `data-*` chunks emitted with `writer.custom()` are persisted to storage as part of the message history. For chunks that are only needed during live streaming — such as progress updates or verbose log output — set `transient: true` to skip storage persistence. Transient chunks are still streamed to the client in real time but aren't saved to the database.
+
+```typescript
+await context?.writer?.custom({
+  type: 'data-build-log',
+  data: { line: 'Compiling module 3 of 12...' },
+  transient: true,
+})
+```
+
+Use transient chunks when the data is large or high-frequency and only relevant during the live session. After a page refresh, transient chunks are no longer available — only the tool's return value and any non-transient chunks are loaded from storage.
+
+## Using the `writer` argument
+
+The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
+
+> **Warning:** You must `await` the call to `writer.write(...)` or else you will lock the stream and get a `WritableStream is locked` error.
+
+```typescript
+import { createStep } from "@mastra/core/workflows";
+
+export const testStep = createStep({
+  execute: async ({ inputData, writer }) => {
+    const { value } = inputData;
+
+    await writer?.write({
+      type: "custom-event",
+      status: "pending"
+    });
+
+    const response = await fetch(...);
+
+    await writer?.write({
+      type: "custom-event",
+      status: "success"
+    });
+
+    return {
+      value: ""
+    };
+  },
+});
+```

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

@@ -46,7 +46,7 @@ The wizard creates a new directory for your project with a `src/mastra` folder c
 - `workflows/weather-workflow.ts`: A workflow that runs the weather agent
 - `scorers/weather-scorer.ts`: A scorer to evaluate the weather agent's responses
 
-Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/build-with-ai/skills) or the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server) installed.
+Depending on your choices, you'll also end up with [Mastra Skills](https://mastra.ai/docs/getting-started/build-with-ai) or the [MCP Docs Server](https://mastra.ai/docs/getting-started/build-with-ai) installed.
 
 > **Tip:** You can use [flags](https://mastra.ai/reference/cli/create-mastra) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).
 

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4562 models from 133 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4563 models from 133 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/opencode.md

@@ -1,6 +1,6 @@
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 45 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 46 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -52,6 +52,7 @@ for await (const chunk of stream) {
 | `opencode/gemini-3.5-flash`       | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `opencode/glm-5`                  | 205K    |       |           |       |       |       | $1         | $3          |
 | `opencode/glm-5.1`                | 205K    |       |           |       |       |       | $1         | $4          |
+| `opencode/glm-5.2`                | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode/gpt-5`                  | 400K    |       |           |       |       |       | $1         | $9          |
 | `opencode/gpt-5-codex`            | 400K    |       |           |       |       |       | $1         | $9          |
 | `opencode/gpt-5-nano`             | 400K    |       |           |       |       |       | $0.05      | $0.40       |

package/.docs/reference/agents/durable-agent.md

@@ -2,7 +2,7 @@
 
 `DurableAgent` wraps an existing [`Agent`](https://mastra.ai/reference/agents/agent) with durable execution and resumable streams. It runs the agentic loop so that a client can disconnect and reconnect without missing events, and it streams those events over [PubSub](https://mastra.ai/docs/server/pubsub). Use it when a run must outlive a single request or survive a dropped connection.
 
-Create one with the [`createDurableAgent`](#createdurableagentoptions) factory, or use [`createEventedAgent`](#createeventedagentoptions) for fire-and-forget execution on the built-in workflow engine. For Inngest-powered execution, use `createInngestAgent` from `@mastra/inngest`.
+Create one with the [`createDurableAgent`](#createdurableagentoptions) factory, or use [`createEventedAgent`](#createeventedagentoptions) for fire-and-forget execution on the built-in workflow engine. For Inngest-powered execution, use [`createInngestAgent`](https://mastra.ai/reference/agents/inngest-agent) from `@mastra/inngest`.
 
 ## Usage example
 
@@ -153,6 +153,32 @@ Returns: `Promise<DurableAgentStreamResult>`
 
 > **Warning:** The `cleanup()` returned by `observe()` destroys the run's registry entries and cached events. Only call it when you are done with the run. If the run is suspended and you intend to resume later, don't call `cleanup()` — let the auto-cleanup timer handle it after the run finishes or errors. Auto-cleanup doesn't fire on suspended events.
 
+#### `prepare(messages, options?)`
+
+Prepares a run for durable execution without starting it. Registers the run in the internal registry and returns the serialized workflow input. Use this when you need to control when and how the workflow is triggered.
+
+```typescript
+const { runId, messageId, workflowInput, threadId, resourceId } = await durableAgent.prepare(
+  'Summarize the document',
+  {
+    memory: { threadId: 'thread-1', resourceId: 'user-1' },
+  },
+)
+```
+
+Returns:
+
+```typescript
+interface PrepareResult {
+  runId: string
+  messageId: string
+  workflowInput: any
+  registryEntry: object
+  threadId?: string
+  resourceId?: string
+}
+```
+
 ## Stream options
 
 `stream()` accepts a `DurableAgentStreamOptions` object. It supports the agent execution options below, plus lifecycle callbacks.
@@ -191,6 +217,8 @@ Returns: `Promise<DurableAgentStreamResult>`
 
 **structuredOutput** (`object`): Structured output configuration.
 
+**untilIdle** (`boolean | { maxIdleMs?: number }`): When set, keeps the stream open across background-task continuations until the agent is idle. Pass \`true\` for the default 5-minute idle timeout, or \`{ maxIdleMs }\` to customise. Equivalent to the deprecated \`streamUntilIdle()\` method.
+
 **versions** (`object`): Version overrides for sub-agent delegation.
 
 **onChunk** (`(chunk: ChunkType) => void | Promise<void>`): Called for each streamed chunk.
@@ -234,6 +262,7 @@ interface DurableAgentStreamResult<OUTPUT = undefined> {
 
 ## Related
 
+- [`createInngestAgent()`](https://mastra.ai/reference/agents/inngest-agent)
 - [Agent class](https://mastra.ai/reference/agents/agent)
 - [PubSub](https://mastra.ai/docs/server/pubsub)
 - [`.getMemory()`](https://mastra.ai/reference/agents/getMemory)

package/.docs/reference/agents/getDefaultOptions.md

@@ -28,5 +28,5 @@ await agent.getDefaultOptions({
 
 ## Related
 
-- [Streaming with agents](https://mastra.ai/docs/streaming/overview)
+- [Streaming with agents](https://mastra.ai/guides/concepts/streaming)
 - [Request Context](https://mastra.ai/docs/server/request-context)

package/.docs/reference/agents/getDefaultStreamOptions.md

@@ -30,5 +30,5 @@ await agent.getDefaultStreamOptionsLegacy({
 
 ## Related
 
-- [Streaming with agents](https://mastra.ai/docs/streaming/overview)
+- [Streaming with agents](https://mastra.ai/guides/concepts/streaming)
 - [Request Context](https://mastra.ai/docs/server/request-context)