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

package/.docs/docs/agent-builder/browser.md

@@ -46,7 +46,7 @@ new MastraEditor({
 
 - `id` — provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
 - `name` — display name shown in the Builder UI.
-- `createBrowser(config)` — hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that are not stored in the agent snapshot.
+- `createBrowser(config)` — hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.
 
 Browser classes ship as separate packages (e.g., `@mastra/stagehand`, `@mastra/agent-browser`). The provider entry is a plain object wrapping the class — register one entry per browser you want the Builder to expose to end users. See the [StorageBrowserRef reference](https://mastra.ai/reference/editor/storage-browser-ref) for the full `browser` field schema, including all `StorageBrowserConfig` options.
 

package/.docs/docs/agent-builder/channels.md

@@ -63,7 +63,7 @@ The Slack provider handles app creation, OAuth, slash commands, and message rout
 
 `SlackProvider` requires one environment variable and accepts one optional override:
 
-- `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): the refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token does not expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
+- `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): the refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token doesn't expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
 - `baseUrl` (optional): the public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address — typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
 
 ## Storage requirement

package/.docs/docs/agent-builder/integrations.md

@@ -0,0 +1,73 @@
+# Tool providers
+
+> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
+Tool providers let Builder-created agents call tools from third-party apps such as Gmail, Slack, or GitHub. The Builder reuses the same tool providers as the editor, so any provider registered on `MastraEditor` is available in the Builder.
+
+This page covers what's specific to the Builder: setting up connections, choosing a connection scope, and managing connections. To register a provider and enable its toolkits, see [Tools](https://mastra.ai/docs/editor/tools).
+
+## Prerequisites
+
+Before agents can use integration tools in the Builder:
+
+- Register a tool provider on the `toolProviders` map of `MastraEditor` (see below).
+- Set up a Composio auth config for each toolkit you want to use (see below).
+- Configure a storage adapter on the `Mastra` instance. Connection state persists through `Mastra.storage`.
+
+## Register a tool provider
+
+The Builder reuses the editor's tool providers. Register each provider you want to expose on the `toolProviders` map of `MastraEditor`. Mastra ships providers for [Composio](https://composio.dev) and [Arcade](https://arcade.dev); add a provider by giving it a key and an instance.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+import { ComposioToolProvider } from '@mastra/editor/composio'
+
+export const mastra = new Mastra({
+  agents: {
+    /* your agents */
+  },
+  editor: new MastraEditor({
+    toolProviders: {
+      composio: new ComposioToolProvider({
+        apiKey: process.env.COMPOSIO_API_KEY!,
+        allowedToolkits: ['gmail', 'googlecalendar'],
+      }),
+    },
+  }),
+})
+```
+
+Each provider's toolkits become available in the Builder once it is registered. Use `allowedToolkits` to restrict which toolkits the provider exposes — by slug, such as `gmail` or `googlecalendar`. Omit it to expose every toolkit the provider offers. To add another provider, import it and add another entry to `toolProviders`. For the full list of providers and their options, see [Tools — Integration providers](https://mastra.ai/docs/editor/tools).
+
+## Set up a Composio auth config
+
+Each toolkit a user can connect needs its own auth config in the [Composio dashboard](https://dashboard.composio.dev). An auth config defines how Composio authenticates with an app — its OAuth client, scopes, and credentials. Each toolkit needs its own because requirements vary by app: some share common OAuth methods, while others need extra setup. Without an enabled config, the connection flow fails.
+
+1. Open the [Composio dashboard](https://dashboard.composio.dev) and select the toolkit you want to enable, for example **Gmail** or **GitHub**.
+2. Create an auth config for the toolkit and complete the app-specific setup. Composio's [auth config docs](https://docs.composio.dev/docs/authenticating-tools) cover the fields each app requires.
+3. Enable the auth config.
+
+Keep exactly one auth config enabled per toolkit. When a user connects the toolkit, the provider resolves the single enabled config for that toolkit and starts the OAuth flow against it.
+
+> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. Enable exactly one auth config per toolkit you expose in the Builder.
+
+## Connect a toolkit
+
+Once a provider is registered and its auth config is enabled, the toolkit can be connected from the Builder:
+
+1. Open the agent and add the toolkit's tools.
+2. Click **Connect** on the toolkit and complete the OAuth flow for the account you want to use.
+
+The connected account is bound to the agent, and its tools are ready to use on the next run.
+
+## Connection scope
+
+When you select a toolkit's tools for an agent, you also pin a connection. The connection determines which account each tool call uses at runtime, with a scope that controls who shares the credential. Today connections are `per-author`: the connection belongs to the agent's author, and any invoker runs the agent with the author's account.
+
+## Related
+
+- [Tools](https://mastra.ai/docs/editor/tools): Register providers and browse toolkits in the editor.
+- [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider): Provider API details.
+- [Agent Builder API reference](https://mastra.ai/reference/client-js/agent-builder): Manage connections programmatically with the `@mastra/client-js` SDK.
+- [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview)

package/.docs/docs/agent-builder/overview.md

@@ -9,6 +9,7 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
 - [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
 - [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
+- [**Tool providers**](https://mastra.ai/docs/agent-builder/integrations): Connect Builder-created agents to third-party apps through OAuth-backed tool providers.
 - [**Skill registries**](https://mastra.ai/docs/agent-builder/skill-registries): Browse and install community skills from opt-in registries.
 - [**Deploying**](https://mastra.ai/docs/agent-builder/deploying): Swap local primitives for cloud-backed storage, filesystems, and sandboxes.
 

package/.docs/docs/agents/adding-voice.md

@@ -158,7 +158,7 @@ await voice.connect()
 When you use a resolver:
 
 - Each call to `getVoice()` returns a new instance, so concurrent sessions never share state.
-- Mastra does not add tools or instructions to a resolver instance. Configure those inside the resolver or on the provider.
+- Mastra doesn't add tools or instructions to a resolver instance. Configure those inside the resolver or on the provider.
 - You own the lifecycle of the returned instance, so call `disconnect()` or `close()` when the session ends.
 
 The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.

package/.docs/docs/agents/agent-approval.md

@@ -96,7 +96,7 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above does not override it. If the function throws, the call requires approval (fail-safe).
+A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above doesn't override it. If the function throws, the call requires approval (fail-safe).
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 
@@ -106,7 +106,7 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
-> **Note:** `suspend()` does not throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+> **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
 

package/.docs/docs/agents/background-tasks.md

@@ -104,7 +104,7 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 }
 ```
 
-The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it is not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it's not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
 
 ### Resolution order
 

package/.docs/docs/agents/channels.md

@@ -84,7 +84,7 @@ When a user mentions the agent mid-conversation in a channel thread, the agent m
 1. On the **first mention** in a thread, the agent fetches recent messages from the platform.
 2. These messages are prepended to the user's message as conversation context.
 3. After responding, the agent subscribes to the thread and has full history via Mastra's memory.
-4. Subsequent messages in that thread do **not** re-fetch from the platform.
+4. Subsequent messages in that thread **don't** re-fetch from the platform.
 
 Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-DM threads.
 
@@ -114,7 +114,7 @@ const deleteFile = createTool({
 
 When the agent calls this tool, users see a card with the tool name, arguments, and Approve/Deny buttons. The tool only executes after approval.
 
-Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context, since hidden mode does not post approval buttons.
+Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context, since hidden mode doesn't post approval buttons.
 
 ## Multi-user awareness
 

package/.docs/docs/agents/code-mode.md

@@ -4,27 +4,30 @@
 
 > **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
-Code mode gives an agent a single tool that runs a short TypeScript program in a sandbox. Instead of calling tools one at a time, the model writes a program that orchestrates your existing tools as `external_*` functions, batching calls with `Promise.all`, aggregating with `reduce`, branching, and doing math in a real runtime, then returns a single result.
+Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response. Instead of calling tools one turn at a time, the model writes a tailored function for the user query that orchestrates your existing tools as `external_*` functions, reduces or aggregates their results, and returns one structured answer.
 
-`createCodeMode` returns this tool with the default id `execute_typescript`. The id is configurable, so an agent can have several code mode tools at once, each scoped to a different set of tools (see [Scoping tools across multiple code tools](#scoping-tools-across-multiple-code-tools)).
+[`createCodeMode()`](https://mastra.ai/reference/tools/create-code-mode) returns this tool with the default `id` of `execute_typescript`. The `id` is configurable, so an agent can have several code mode tools at once, each scoped to a different set of tools (see [Scoping tools across multiple code tools](#scoping-tools-across-multiple-code-tools)).
 
 ## When to use code mode
 
-Use code mode when a task touches several tools at once or needs real computation between calls:
+Use code mode when an agent touches multiple tools to answer a user query or perform a complex computation:
 
-- Fewer round-trips: a task that touches several tools runs in one tool call instead of one model turn per tool.
-- Correct math: sums, averages, and other arithmetic run as JavaScript, not as token prediction.
-- Planning up front: filtering, aggregation, and branching happen inside the program rather than across separate turns.
+- Fewer round-trips: A multi-tool query runs in one tool call instead of repeating the agentic loop for every tool decision.
+- Smaller context: The function can reduce or aggregate large tool responses before returning them to the agent.
+- Correct math: Sums, averages, and other arithmetic run as JavaScript, not as token prediction.
+- Planning up front: Filtering, aggregation, and branching happen inside the function rather than across separate turns.
 
 ## How it works
 
-Your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, so dangerous tools, approvals, and validation behave exactly as they do for normal tool calls.
+Without code mode, multi-tool queries can run the agentic loop several times: the model chooses a tool, reads the result, chooses again, and repeats. Each turn adds the full tool response to the agent's context window which can lead to poorer reasoning and increased token usage.
 
-The program runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the program as a host `node` process with host privileges, so only use it for trusted or local development.
+With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
+
+The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
 ## Quickstart
 
-`createCodeMode` returns the tool plus generated instructions. With no `id`, the tool is named `execute_typescript`. Add both to your agent:
+`createCodeMode()` returns the tool plus generated instructions. With no `id`, the tool is named `execute_typescript`. Add both to your agent:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -83,52 +86,18 @@ return top.products.map((product, i) => {
 
 All five rating lookups run in parallel, the averages are computed in JavaScript, and the agent receives one structured result.
 
-## Configuration
-
-```typescript
-const { tool, instructions } = createCodeMode({
-  tools: { getTopProducts, getProductRatings }, // exposed as external_*; only these can be called
-  sandbox, // required WorkspaceSandbox, unless the agent runs in a workspace that provides one
-  timeout: 30_000, // optional execution timeout in ms (default 30000)
-  id: 'execute_typescript', // optional tool id (default "execute_typescript")
-})
-```
-
-| Option    | Type               | Description                                                                                                                                   |
-| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tools`   | `ToolsInput`       | Tools exposed to the program as `external_<id>`. Only these may be called.                                                                    |
-| `sandbox` | `WorkspaceSandbox` | Sandbox to run the program in. Required unless the agent runs in a workspace that provides one. Pass `new LocalSandbox()` to run on the host. |
-| `timeout` | `number`           | Execution timeout in milliseconds. Default `30000`.                                                                                           |
-| `id`      | `string`           | The generated tool's id. Default `execute_typescript`.                                                                                        |
-
-## Result
-
-The tool returns a `CodeModeToolResult`:
-
-```typescript
-type CodeModeToolResult = {
-  success: boolean
-  result?: unknown // value returned by the program
-  logs?: string[] // captured console output
-  error?: { message: string; name?: string; line?: number }
-}
-```
-
-## Inspecting the instructions
+For `createCodeMode()` to work well, keep these tips in mind:
 
-The generated `instructions` contain the usage contract and a typed `external_*` declaration for each tool, derived from your tool schemas. Print them to see exactly what the model receives:
+- Keep tools focused, so each does one thing well and the model composes them in code.
+- Code mode helps most when calls can be parallelized with `Promise.all`.
 
-```typescript
-import { createCodeModeInstructions } from '@mastra/core/tools'
-
-console.log(createCodeModeInstructions({ tools: { getTopProducts, getProductRatings } }))
-```
+> **Note:** Visit the [`createCodeMode()` reference](https://mastra.ai/reference/tools/create-code-mode) for configuration options, return values, result shape, and instructions inspection.
 
 ## Scoping tools across multiple code tools
 
-`createCodeMode` captures its own allow-list. Call it more than once to give an agent several code tools, each scoped to a different subset of tools. A program can only call the `external_*` functions for the tools passed to its own `createCodeMode` call, so the subsets stay isolated.
+`createCodeMode()` captures its own allow-list. Call it more than once to give an agent several code tools, each scoped to a different subset of tools. It can only call the `external_*` functions for the tools passed to its own `createCodeMode()` call, so the subsets stay isolated.
 
-Give each tool a distinct `id` so their ids do not collide, and add each tool's instructions to the agent:
+Give each tool a distinct `id` so their ids don't collide, and add each tool's instructions to the agent:
 
 ```typescript
 const sales = createCodeMode({
@@ -151,15 +120,10 @@ const agent = new Agent({
 })
 ```
 
-A program run by `sales_code` cannot call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
-
-## Tips
-
-- Keep tools focused, so each does one thing well and the model composes them in code.
-- Code mode helps most when calls can be parallelized with `Promise.all`.
-- Use `console.log` for debugging. Logs are captured in the result.
+The generated code for `sales_code` can't call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
 
 ## Related
 
+- [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/overview.md

@@ -89,6 +89,7 @@ Once your agent is running, use this table to find the right page for what you w
 | Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
 | Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
+| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/agents/supervisor-agents)       |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/docs/agents/adding-voice)                    |
 | Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/agents/channels)                     |

package/.docs/docs/agents/sdk-agents.md

@@ -13,6 +13,7 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
 
 - [Claude Agent SDK](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
 - [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
+- [OpenAI Agents SDK](#openai-agents-sdk): Use `@mastra/openai` to register an OpenAI SDK agent and call it with Mastra `generate()` and `stream()`.
 
 ## Claude Agent SDK
 
@@ -216,6 +217,117 @@ export const cursorSDKAgent = new CursorSDKAgent({
 })
 ```
 
+## OpenAI Agents SDK
+
+Use `@mastra/openai` to register an OpenAI Agents SDK agent in Mastra while keeping OpenAI-specific agent settings in OpenAI SDK options.
+
+### Install OpenAI packages
+
+Install the Mastra package and the OpenAI Agents SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/openai @openai/agents zod
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/openai @openai/agents zod
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/openai @openai/agents zod
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/openai @openai/agents zod
+```
+
+Set the OpenAI SDK credential:
+
+```bash
+export OPENAI_API_KEY="..."
+```
+
+### Create an OpenAI SDK agent
+
+Configure OpenAI Agents SDK through `sdkOptions`. `OpenAISDKAgent` creates the OpenAI SDK agent on first use.
+
+```typescript
+import { OpenAISDKAgent } from '@mastra/openai'
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Repository assistant',
+    instructions: 'Answer clearly and cite the relevant files.',
+    model: 'gpt-5',
+  },
+})
+```
+
+### Use an existing OpenAI SDK agent
+
+If your app already creates an OpenAI SDK agent, pass that agent to `OpenAISDKAgent` instead:
+
+```typescript
+import { Agent as OpenAIAgent } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+
+const sdkAgent = new OpenAIAgent({
+  name: 'Repository assistant',
+  instructions: 'Answer clearly and cite the relevant files.',
+  model: 'gpt-5',
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  agent: sdkAgent,
+})
+```
+
+### Add OpenAI SDK tools
+
+OpenAI Agents SDK tools are configured with OpenAI SDK options. Create tools with the OpenAI SDK, then pass them through `sdkOptions.tools`.
+
+```typescript
+import { tool } from '@openai/agents'
+import { OpenAISDKAgent } from '@mastra/openai'
+import { z } from 'zod'
+
+const getTemperature = tool({
+  name: 'get_temperature',
+  description: 'Get the current temperature for a city.',
+  parameters: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return `${city}: 27 C`
+  },
+})
+
+export const openaiSDKAgent = new OpenAISDKAgent({
+  id: 'openai-sdk-agent',
+  name: 'OpenAI SDK Agent',
+  description: 'Use OpenAI Agents SDK through Mastra.',
+  sdkOptions: {
+    name: 'Weather assistant',
+    model: 'gpt-5',
+    tools: [getTemperature],
+  },
+})
+```
+
 ## Register SDK agents
 
 Register SDK agents in the Mastra instance like other agents:
@@ -224,11 +336,13 @@ Register SDK agents in the Mastra instance like other agents:
 import { Mastra } from '@mastra/core'
 import { claudeSDKAgent } from './agents/claude-sdk-agent'
 import { cursorSDKAgent } from './agents/cursor-sdk-agent'
+import { openaiSDKAgent } from './agents/openai-sdk-agent'
 
 export const mastra = new Mastra({
   agents: {
     claudeSDKAgent,
     cursorSDKAgent,
+    openaiSDKAgent,
   },
 })
 ```
@@ -246,11 +360,61 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
+## Resume SDK runs
+
+SDK agents support Mastra `resumeGenerate()` and `resumeStream()` with provider-native resume data. Pass the message to continue with and the resume identifier used by the underlying SDK.
+
+Claude SDK agents can resume a known session with `sessionId`:
+
+```typescript
+const result = await claudeSDKAgent.resumeGenerate({
+  message: 'Continue the previous task.',
+  sessionId: 'claude-session-id',
+})
+
+console.log(result.text)
+```
+
+OpenAI SDK agents can resume with a previous response, conversation, or session:
+
+```typescript
+const stream = await openaiSDKAgent.resumeStream({
+  message: 'Continue the previous task.',
+  previousResponseId: 'resp_123',
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+Cursor SDK agents can continue with the wrapped SDK agent. If you need to resume a stored Cursor SDK agent by ID, pass `agentId` in `resumeData`.
+
+## Structured output
+
+Claude and OpenAI SDK agents support Mastra `structuredOutput` through their provider-native structured output APIs. The validated value is available on `result.object`.
+
+```typescript
+import { z } from 'zod'
+
+const result = await openaiSDKAgent.generate<{ summary: string }>('Summarize this project.', {
+  structuredOutput: {
+    schema: z.object({
+      summary: z.string(),
+    }),
+  },
+})
+
+console.log(result.object.summary)
+```
+
+Cursor SDK agents throw a clear error when `structuredOutput` is requested because the Cursor TypeScript SDK doesn't expose a schema-constrained output API.
+
 ## Observability
 
 SDK agents create Mastra agent and model spans for `generate()` and `stream()` calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.
 
-Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.
+Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates. OpenAI SDK runs include token usage from OpenAI run state.
 
 For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
 

package/.docs/docs/agents/supervisor-agents.md

@@ -169,7 +169,7 @@ The callback receives `messages` (the full conversation history), `primitiveId`
 
 ## Subagent result context
 
-When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, are not added to the supervisor model context.
+When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, aren't added to the supervisor model context.
 
 Application code and UI integrations can still inspect the raw delegation result, including `subAgentToolResults`, from the tool result payload. This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
 
@@ -263,7 +263,7 @@ for await (const chunk of stream.fullStream) {
 
 ## Task completion scoring
 
-Task completion scorers validate whether the task is complete after each iteration. If validation fails, the supervisor continues iterating. Feedback from failed scorers is included in the conversation context so subagents can see what was missing.
+Agents don't always produce a complete, correct output on the first try. Task completion scorers can help with that by validating whether the task is complete after each iteration. If validation fails, the supervisor continues iterating. Feedback from failed scorers is included in the conversation context so subagents can see what was missing.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'
@@ -290,6 +290,44 @@ const stream = await supervisor.stream('Research AI in education', {
 })
 ```
 
+### Rubric scorer
+
+The built-in rubric scorer lets you define what "correct" looks like as a checklist and have the agent self-evaluate and iterate until every criterion is satisfied or `maxSteps` is reached.
+
+It works as an **LLM-as-judge** scorer: a separate grader model reviews the agent's output against the rubric after each iteration. If every required criterion passes, the loop ends. If anything falls short, per-criterion feedback is injected back into the conversation and the agent tries again.
+
+This is most effective for tasks with clear, verifiable success criteria. You can use it like so:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: 'You coordinate research and writing using specialized agents.',
+  model: 'openai/gpt-5.5',
+  agents: { researchAgent, writingAgent },
+})
+
+const rubricScorer = createRubricScorer({
+  model: 'openai/gpt-5-mini',
+  criteria: [
+    { description: 'The response includes an analysis section' },
+    { description: 'The response includes concrete recommendations' },
+  ],
+})
+
+const stream = await supervisor.stream('Research AI in education', {
+  maxSteps: 10,
+  isTaskComplete: {
+    scorers: [rubricScorer],
+    strategy: 'all',
+  },
+})
+```
+
+For full API details, see the [rubric scorer reference](https://mastra.ai/reference/evals/rubric).
+
 ## Writing effective instructions
 
 Clear instructions are essential for effective delegation. Your supervisor's `instructions` should specify available resources, when to use each one, how to coordinate them, and success criteria.

package/.docs/docs/agents/using-tools.md

@@ -228,10 +228,68 @@ export const weatherTool = createTool({
 
 Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.
 
-If a transform is configured and it fails, Mastra does not fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
+If a transform is configured and it fails, Mastra doesn't fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
 
 See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
 
+## Run logic around tool calls
+
+Use `hooks` to run custom logic before and after every tool call an agent makes. Hooks apply to all tool sources: assigned tools, memory tools, toolsets, client tools, agent and workflow tools, and [workspace tools](https://mastra.ai/docs/workspace/overview). Common uses include logging, auditing, input validation, and blocking specific calls.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const supportAgent = new Agent({
+  name: 'support-agent',
+  instructions: 'Help users with their questions.',
+  model: 'openai/gpt-5.5',
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      console.log(`Running ${toolName}`, input)
+    },
+    afterToolCall: ({ toolName, output, error }) => {
+      console.log(`Finished ${toolName}`, { output, error })
+    },
+  },
+})
+```
+
+`beforeToolCall` runs before the tool executes and receives the tool name, input, and execution context. Return `{ proceed: false, output }` to skip the tool call entirely — the agent receives `output` as the tool result:
+
+```typescript
+const guardedAgent = new Agent({
+  name: 'guarded-agent',
+  instructions: 'Run shell commands for the user.',
+  model: 'openai/gpt-5.5',
+  hooks: {
+    beforeToolCall: ({ toolName, input }) => {
+      const command = (input as { command?: string }).command ?? ''
+      if (toolName === 'execute_command' && command.includes('rm -rf')) {
+        return { proceed: false, output: 'Command blocked by policy.' }
+      }
+    },
+  },
+})
+```
+
+`afterToolCall` runs after the tool finishes, whether it succeeded or failed. On success it receives `output`; if the tool threw, it receives `error` instead and the error is re-thrown after the hook runs.
+
+### Per-execution hooks
+
+Pass `hooks` to `.generate()` or `.stream()` to set hooks for a single execution. Per-execution hooks override matching agent-level hooks:
+
+```typescript
+await supportAgent.generate('Look up the order status', {
+  hooks: {
+    beforeToolCall: ({ toolName }) => {
+      console.log(`This run only: ${toolName}`)
+    },
+  },
+})
+```
+
+Agent-level and per-execution hooks merge per key: passing only `beforeToolCall` at execution time keeps the agent-level `afterToolCall`.
+
 ## Control tool selection
 
 Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.

package/.docs/docs/browser/agent-browser.md

@@ -71,7 +71,7 @@ When the agent uses the `browser_screenshot` tool, it captures a PNG image of th
 
 Use screenshots when you need to visually inspect the page — for example, evaluating images, layout, or colors. For text or structured data, use `browser_snapshot` instead.
 
-To disable the screenshot tool for models that do not support vision, use `excludeTools`:
+To disable the screenshot tool for models that don't support vision, use `excludeTools`:
 
 ```typescript
 const browser = new AgentBrowser({