@mastra/mcp-docs-server 1.2.17-alpha.17 → 1.2.17-alpha.19

package/.docs/docs/connections/acp.md

@@ -4,7 +4,7 @@
 
 Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
 
-ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.
+ACP is useful for coding agents such as Claude Code, Cline, OpenCode, Amp, Codex, or any other executable that implements ACP over standard input and output.
 
 ## When to use ACP
 
@@ -30,6 +30,18 @@ The flow is:
 
 During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
 
+## Compatible agents
+
+Any executable that implements ACP over standard input and output works with `@mastra/acp`. You don't need a dedicated Mastra package for each agent. Install the agent, then pass its launch command through `command` and `args`.
+
+| Agent      | `command`  | `args`      |
+| ---------- | ---------- | ----------- |
+| Cline      | `cline`    | `['--acp']` |
+| OpenCode   | `opencode` | `['acp']`   |
+| Gemini CLI | `gemini`   | `['--acp']` |
+
+Each agent documents its own ACP mode, and launch flags change between releases. Check the agent's documentation for the current command, such as [Cline ACP](https://docs.cline.bot/usage/acp) or [OpenCode ACP](https://opencode.ai/docs/acp/).
+
 ## Getting started
 
 Install `@mastra/acp` in a project that already uses `@mastra/core`. The package requires `@mastra/core` version `1.34.0` or later.
@@ -75,8 +87,8 @@ const codeAgent = new AcpAgent({
   id: 'code-agent',
   name: 'Code Agent',
   description: 'An ACP-compatible coding agent that can inspect and edit files',
-  command: 'acp-agent',
-  args: ['--stdio'],
+  command: 'opencode',
+  args: ['acp'],
   cwd: process.cwd(),
 })
 
@@ -104,8 +116,8 @@ import { Agent } from '@mastra/core/agent'
 const codeAgentTool = createACPTool({
   id: 'code-agent',
   description: 'Use an ACP-compatible coding agent to inspect and edit code',
-  command: 'acp-agent',
-  args: ['--stdio'],
+  command: 'opencode',
+  args: ['acp'],
   cwd: process.cwd(),
 })
 

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

@@ -6,7 +6,7 @@ Connections let Mastra work with remote agents, coding agents, provider software
 
 - [**Model Context Protocol (MCP)**](https://mastra.ai/docs/connections/mcp): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
 - [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
-- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes as Mastra tools or subagents.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes, such as Claude Code, Cline, or OpenCode, as Mastra tools or subagents.
 - [**SDK agents**](https://mastra.ai/docs/connections/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
 
 ## When to use connections

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

@@ -17,6 +17,8 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
 - [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()`.
 
+Coding agents without a dedicated Mastra package, such as Cline and OpenCode, run through the [Agent Client Protocol](https://mastra.ai/docs/connections/acp) instead.
+
 ## Claude Agent SDK
 
 Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.

package/.docs/docs/deployment/cloud-providers.md

@@ -21,5 +21,6 @@ The following pages show you how to deploy Mastra to specific cloud providers.
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)

package/.docs/docs/deployment/overview.md

@@ -52,6 +52,7 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)
 

package/.docs/docs/harness/durable-agents.md

@@ -118,6 +118,22 @@ const agent = new Agent({
 export const eventedWriter = createEventedAgent({ agent })
 ```
 
+### Stored agents created through the API
+
+Agents created with [`createStoredAgent()`](https://mastra.ai/reference/client-js/agents) opt in with a `durable` field on the agent config. The server wraps the agent with `createDurableAgent()` when it hydrates it, so no code deployment is needed:
+
+```typescript
+await mastraClient.createStoredAgent({
+  id: 'helper',
+  name: 'Helper',
+  instructions: 'You are a helpful assistant.',
+  model: { provider: 'openai', name: 'gpt-5' },
+  durable: true,
+})
+```
+
+`durable` also accepts `{ maxSteps, cleanupTimeoutMs }`. Cache and pubsub are inherited from the server's `Mastra` instance, so configure distributed backends there if you need durability across replicas. Automatic recovery is still configured in code through `recovery.durableAgents`.
+
 ### Inngest-powered with `createInngestAgent()`
 
 Run the workflow on the [Inngest](https://www.inngest.com/docs) platform. Each tool call becomes a memoized step that Inngest can retry independently, and you get a dashboard for monitoring runs:

package/.docs/docs/sandbox/overview.md

@@ -111,6 +111,7 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
 - [Blaxel](https://mastra.ai/integrations/sandboxes/blaxel)
+- [Cloudflare Sandbox](https://mastra.ai/integrations/sandboxes/cloudflare-sandbox)
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)

package/.docs/integrations/deploy/render.md

@@ -0,0 +1,389 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Render
+
+Deploy Mastra applications on [Render](https://render.com/). Host the Mastra API as a [web service](https://render.com/docs/web-services), or use [Render Workflows](https://render.com/docs/workflows) for long-running tasks with independent retry policies.
+
+Choose the deployment path that fits your application:
+
+- **Mastra API**: Deploy Mastra's [server](https://mastra.ai/docs/server/overview) as a web service with a public endpoint. The [Web Services guide](https://render.com/docs/web-services) explains how to deploy custom code or a supported [server adapter](https://mastra.ai/docs/server/server-adapters).
+- **Mastra workflow**: Run an entire Mastra workflow within one task. Render controls the outer run, while Mastra manages its steps and state. See [Defining Workflow Tasks](https://render.com/docs/workflows-defining) for configuration details.
+- **Distributed agent operations**: Give each operation its own compute plan, timeout, and retry policy. Render Workflows handles the execution queue and provides run observability.
+
+This guide builds an editorial pipeline that reviews a draft from three perspectives in parallel, then passes the feedback to an editor agent. Use the links above if you want to deploy a Mastra API or execute an entire Mastra workflow as one task.
+
+## How Render Workflows integrates with Mastra
+
+Mastra supplies the agents and application logic, while Render Workflows defines the execution boundaries. A typical pipeline has three layers:
+
+1. A parent task coordinates the run.
+2. Child tasks invoke Mastra agents for focused work.
+3. A final task combines the results.
+
+Calling one task from another creates a chained run in a separate instance, with its own compute plan, timeout, and retry policy.
+
+## Setup
+
+Create an empty Mastra project named `render-workflows`:
+
+**npm**:
+
+```bash
+npm create mastra@latest render-workflows -- --empty
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra render-workflows --empty
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra render-workflows --empty
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra render-workflows --empty
+```
+
+Install two additional dependencies:
+
+**npm**:
+
+```bash
+npm install @renderinc/sdk tsx
+```
+
+**pnpm**:
+
+```bash
+pnpm add @renderinc/sdk tsx
+```
+
+**Yarn**:
+
+```bash
+yarn add @renderinc/sdk tsx
+```
+
+**Bun**:
+
+```bash
+bun add @renderinc/sdk tsx
+```
+
+Add your API key to an `.env` file. This example uses OpenAI, but any supported [model provider](https://mastra.ai/models) works.
+
+```text
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Install the [Render CLI](https://render.com/docs/cli) to run workflow commands from your terminal.
+
+## Distributed agent pipeline
+
+### Create the agents
+
+In `src/mastra`, create an `agents` directory with `reviewer-agent.ts` and `editor-agent.ts`. Define both agents:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const reviewerAgent = new Agent({
+  id: 'reviewer-agent',
+  name: 'Reviewer Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Review the supplied draft only from the requested perspective.
+    Identify concrete problems and recommend specific changes.
+    Do not rewrite the full draft.
+  `,
+})
+```
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const editorAgent = new Agent({
+  id: 'editor-agent',
+  name: 'Editor Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Revise the supplied draft using the reviewers' feedback.
+    Return the complete revised draft and nothing else.
+    Preserve accurate details and do not introduce unsupported claims.
+  `,
+})
+```
+
+### Configure the Mastra instance
+
+Add both agents to the Mastra instance in `src/mastra/index.ts`:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { editorAgent } from './agents/editor-agent.js'
+import { reviewerAgent } from './agents/reviewer-agent.js'
+
+export const mastra = new Mastra({
+  agents: {
+    editorAgent,
+    reviewerAgent,
+  },
+})
+```
+
+### Create the tasks
+
+In `src`, create a `tasks` directory with `review-task.ts`, `revision-task.ts`, and `editorial-task.ts`.
+
+#### Review task
+
+The reviewer agent handles one area of focus. Its compute plan, five-minute timeout, and retry policy apply only to that analysis. A temporary model-provider failure can trigger another attempt without restarting the other reviewers.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviewDraft = task(
+  {
+    name: 'review_draft',
+    plan: 'starter',
+    timeoutSeconds: 300,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviewDraft(draft: string, focus: string): Promise<Review> {
+    const reviewer = mastra.getAgentById('reviewer-agent')
+    const response = await reviewer.generate(`
+      Review this draft for ${focus}.
+      Draft: ${draft}
+    `)
+    if (!response.text) {
+      throw new Error(`The ${focus} review returned no text`)
+    }
+    return {
+      focus,
+      feedback: response.text,
+    }
+  },
+)
+```
+
+#### Revision task
+
+This task combines the feedback and produces a revised draft. It uses a larger compute plan and a longer timeout than each reviewer.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviseDraft = task(
+  {
+    name: 'revise_draft',
+    plan: 'standard',
+    timeoutSeconds: 600,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviseDraft(draft: string, reviews: Review[]): Promise<{ draft: string }> {
+    const editor = mastra.getAgentById('editor-agent')
+    const response = await editor.generate(`
+      Revise the draft using the review feedback.
+      Draft: ${draft}
+      Reviews: ${JSON.stringify(reviews, null, 2)}
+    `)
+    if (!response.text) {
+      throw new Error('The editor returned no text')
+    }
+    return {
+      draft: response.text,
+    }
+  },
+)
+```
+
+#### Editorial task
+
+The parent dispatches three reviews in parallel with `Promise.all()`, then sends their combined feedback to the revision step. Retries are disabled at this level because each child defines its own policy. If you enable orchestration retries, ensure that another attempt can't duplicate external side effects or other non-idempotent work.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { reviewDraft } from './review-task.js'
+import { reviseDraft } from './revision-task.js'
+
+export const editorialPipeline = task(
+  {
+    name: 'editorial_pipeline',
+    plan: 'starter',
+    timeoutSeconds: 1_200,
+    retry: {
+      maxRetries: 0,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function editorialPipeline(draft: string): Promise<{ draft: string }> {
+    const focuses = ['technical clarity', 'structure and flow', 'reader usefulness']
+    const reviews = await Promise.all(focuses.map(focus => reviewDraft(draft, focus)))
+    return reviseDraft(draft, reviews)
+  },
+)
+```
+
+### Set up the entry point
+
+Create `src/index.ts` and import the editorial task:
+
+```ts
+import './tasks/editorial-task.js'
+```
+
+In `package.json`, add scripts to build the TypeScript project and run the workflow:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "dev:workflows": "tsx src/index.ts",
+    "start:workflows": "node dist/index.js"
+  }
+}
+```
+
+Configure `tsconfig.json` for the build:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Build the project. The command compiles the JavaScript files into `dist`.
+
+**npm**:
+
+```bash
+npm run build
+```
+
+**pnpm**:
+
+```bash
+pnpm run build
+```
+
+**Yarn**:
+
+```bash
+yarn build
+```
+
+**Bun**:
+
+```bash
+bun run build
+```
+
+## Run the pipeline
+
+### Locally
+
+Start the local development server with the Render CLI:
+
+```bash
+render workflows dev -- npm run dev:workflows
+```
+
+The server lists the registered tasks:
+
+```bash
+➜ render workflows dev -- npm run dev:workflows
+Workflow server listening on port 8120
+Loaded environment variables from .env
+3 tasks found in npm run dev:workflows
+  • editorial_pipeline
+  • review_draft
+  • revise_draft
+
+To browse and run tasks, open another terminal and run:
+  render workflows tasks list --local
+```
+
+In another terminal, confirm that the tasks are available:
+
+```bash
+render workflows tasks list --local
+```
+
+The command displays each task's name, ID, and creation time. Press `Ctrl+C`, then start the editorial pipeline from the same terminal:
+
+```bash
+render workflows tasks runs start editorial_pipeline \
+  --local \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+The development server records the parent run, three parallel reviews, and the final revision.
+
+### Production
+
+Create a workflow service from the current repository:
+
+```bash
+render workflows create \
+  --name mastra-workflows \
+  --repo . \
+  --runtime node \
+  --build-command "npm install && npm run build" \
+  --run-command "npm run start:workflows"
+```
+
+Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the service's environment variables.
+
+After deployment, start a production run. If needed, replace `mastra-workflows/editorial_pipeline` with the task slug shown in the Render Dashboard.
+
+```bash
+render workflows tasks start mastra-workflows/editorial_pipeline \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+Open the workflow service in the Render Dashboard to inspect each task run, attempt, result, and log stream.
+
+## Related
+
+- [Render Workflows documentation](https://render.com/docs/workflows)
+- [Defining Render workflow tasks](https://render.com/docs/workflows-defining)
+- [Triggering task runs](https://render.com/docs/workflows-running)
+- [Render Workflows TypeScript SDK](https://render.com/docs/workflows-sdk-typescript)
+- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)

package/.docs/integrations/sandboxes/cloudflare-sandbox.md

@@ -0,0 +1,118 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Cloudflare Sandbox
+
+`CloudflareSandbox` executes commands and manages files in a remote [Cloudflare Sandbox](https://developers.cloudflare.com/sandbox/) through the [Sandbox Bridge HTTP API](https://developers.cloudflare.com/sandbox/bridge/http-api/).
+
+> **Warning:** Deploy and secure a [Sandbox Bridge Worker](https://developers.cloudflare.com/sandbox/bridge/) before using this provider. The bridge can create and delete sandboxes, execute commands, and write files on behalf of its callers.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare-sandbox
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare-sandbox
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare-sandbox
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cloudflare-sandbox
+```
+
+## Usage
+
+Add `CloudflareSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { CloudflareSandbox } from '@mastra/cloudflare-sandbox'
+
+const workspace = new Workspace({
+  sandbox: new CloudflareSandbox({
+    baseUrl: process.env.CLOUDFLARE_SANDBOX_BRIDGE_URL!,
+    apiToken: process.env.CLOUDFLARE_SANDBOX_API_KEY,
+    workingDirectory: '/workspace',
+    commandTimeout: 300_000,
+  }),
+})
+
+export const agent = new Agent({
+  id: 'dev-agent',
+  name: 'Development agent',
+  instructions: 'You are a helpful development assistant.',
+  model: 'anthropic/claude-sonnet-4-6',
+  workspace,
+})
+```
+
+The provider creates a remote sandbox when the workspace starts. Pass `sandboxId` to reconnect to an existing sandbox instead.
+
+## Execute commands
+
+Pass command arguments, environment variables, a working directory, and streaming callbacks through `executeCommand()`. The provider sends the command as an `argv` array, so the bridge handles shell escaping:
+
+```typescript
+const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
+  cwd: '/workspace/project',
+  env: {
+    NODE_ENV: 'test',
+  },
+  onStdout: chunk => process.stdout.write(chunk),
+  onStderr: chunk => process.stderr.write(chunk),
+})
+```
+
+## Write files
+
+Relative paths are resolved under `/workspace`. Absolute paths must also resolve within `/workspace`. Each file is sent as its own bridge request, and the bridge caps a single file at 32 MiB.
+
+```typescript
+await workspace.sandbox?.writeFiles?.([
+  { path: 'src/index.ts', content: "console.log('hello')\n" },
+  { path: '/workspace/package.json', content: JSON.stringify({ type: 'module' }) },
+])
+```
+
+## Constructor parameters
+
+**baseUrl** (`string`): URL of the deployed Cloudflare Sandbox Bridge Worker.
+
+**apiToken** (`string`): Bearer token matching the Worker's SANDBOX\_API\_KEY secret.
+
+**sandboxId** (`string`): Existing Cloudflare sandbox ID to reconnect to instead of creating a sandbox.
+
+**id** (`string`): Stable Mastra identifier. Defaults to a generated UUID-based value.
+
+**name** (`string`): Human-readable sandbox name. (Default: `Cloudflare Sandbox`)
+
+**env** (`Record<string, string>`): Environment variables applied to every command.
+
+**workingDirectory** (`string`): Working directory applied to every command.
+
+**commandTimeout** (`number`): Default command timeout in milliseconds. (Default: `300000`)
+
+**instructions** (`string | ((options) => string)`): Custom instructions returned by getInstructions().
+
+## Lifecycle behavior
+
+- `start()`: Reconnects to `sandboxId` or creates a remote sandbox.
+- `stop()`: Detaches the Mastra lifecycle without deleting the remote sandbox because the bridge doesn't expose a suspend operation.
+- `destroy()`: Deletes the remote sandbox.
+
+## Limitations
+
+The provider supports command execution, streamed output, and file writes. It doesn't currently expose the bridge's bucket mounts, sessions, PTY terminals, or workspace persistence routes, and it doesn't support background process management, stdin, snapshots, or port URLs.

package/.docs/integrations.md

@@ -36,6 +36,7 @@
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
 - [Blaxel](https://mastra.ai/integrations/sandboxes/blaxel)
+- [Cloudflare Sandbox](https://mastra.ai/integrations/sandboxes/cloudflare-sandbox)
 - [Daytona](https://mastra.ai/integrations/sandboxes/daytona)
 - [Docker](https://mastra.ai/integrations/sandboxes/docker)
 - [E2B](https://mastra.ai/integrations/sandboxes/e2b)
@@ -90,6 +91,7 @@
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Mastra](https://mastra.ai/docs/mastra-platform/deploy)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)
 

package/.docs/models/environment-variables.md

@@ -79,6 +79,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Kenari](https://mastra.ai/models/providers/kenari)                                            | `kenari/*`                 | `KENARI_API_KEY`                                                                                      |
 | [Kilo Gateway](https://mastra.ai/models/providers/kilo)                                        | `kilo/*`                   | `KILO_API_KEY`                                                                                        |
 | [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)                          | `kimi-for-coding/*`        | `KIMI_API_KEY`                                                                                        |
+| [Kosmik Compute](https://mastra.ai/models/providers/kosmik)                                    | `kosmik/*`                 | `KOSMIK_API_KEY`                                                                                      |
 | [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)            | `kuae-cloud-coding-plan/*` | `KUAE_API_KEY`                                                                                        |
 | [Lilac](https://mastra.ai/models/providers/lilac)                                              | `lilac/*`                  | `LILAC_API_KEY`                                                                                       |
 | [Llama](https://mastra.ai/models/providers/llama)                                              | `llama/*`                  | `LLAMA_API_KEY`                                                                                       |

package/.docs/models/gateways/openrouter.md

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 352 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 350 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -149,7 +149,6 @@ ANTHROPIC_API_KEY=ant-...
 | `kwaipilot/kat-coder-air-v2.5`                             |
 | `kwaipilot/kat-coder-pro-v2`                               |
 | `kwaipilot/kat-coder-pro-v2.5`                             |
-| `liquid/lfm-2.5-2.6b:free`                                 |
 | `mancer/weaver`                                            |
 | `meituan/longcat-2.0`                                      |
 | `meta-llama/llama-3.1-70b-instruct`                        |
@@ -386,5 +385,4 @@ ANTHROPIC_API_KEY=ant-...
 | `z-ai/glm-5-turbo`                                         |
 | `z-ai/glm-5.1`                                             |
 | `z-ai/glm-5.2`                                             |
-| `z-ai/glm-5.2:free`                                        |
 | `z-ai/glm-5v-turbo`                                        |

package/.docs/models/gateways/vercel.md

@@ -2,7 +2,7 @@
 
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 329 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 347 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -238,35 +238,51 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-3.5-turbo`                   |
 | `openai/gpt-4-turbo`                     |
 | `openai/gpt-4.1`                         |
+| `openai/gpt-4.1-fast`                    |
 | `openai/gpt-4.1-mini`                    |
+| `openai/gpt-4.1-mini-fast`               |
 | `openai/gpt-4.1-nano`                    |
+| `openai/gpt-4.1-nano-fast`               |
 | `openai/gpt-4o`                          |
+| `openai/gpt-4o-fast`                     |
 | `openai/gpt-4o-mini`                     |
+| `openai/gpt-4o-mini-fast`                |
 | `openai/gpt-4o-mini-search-preview`      |
 | `openai/gpt-4o-mini-transcribe`          |
 | `openai/gpt-4o-transcribe`               |
 | `openai/gpt-5`                           |
 | `openai/gpt-5-codex`                     |
+| `openai/gpt-5-fast`                      |
 | `openai/gpt-5-mini`                      |
+| `openai/gpt-5-mini-fast`                 |
 | `openai/gpt-5-nano`                      |
 | `openai/gpt-5-pro`                       |
 | `openai/gpt-5.1-codex`                   |
 | `openai/gpt-5.1-codex-max`               |
 | `openai/gpt-5.1-codex-mini`              |
 | `openai/gpt-5.1-thinking`                |
+| `openai/gpt-5.1-thinking-fast`           |
 | `openai/gpt-5.2`                         |
 | `openai/gpt-5.2-codex`                   |
+| `openai/gpt-5.2-fast`                    |
 | `openai/gpt-5.2-pro`                     |
 | `openai/gpt-5.3-codex`                   |
+| `openai/gpt-5.3-codex-fast`              |
 | `openai/gpt-5.4`                         |
+| `openai/gpt-5.4-fast`                    |
 | `openai/gpt-5.4-mini`                    |
+| `openai/gpt-5.4-mini-fast`               |
 | `openai/gpt-5.4-nano`                    |
 | `openai/gpt-5.4-pro`                     |
 | `openai/gpt-5.5`                         |
+| `openai/gpt-5.5-fast`                    |
 | `openai/gpt-5.5-pro`                     |
 | `openai/gpt-5.6-luna`                    |
+| `openai/gpt-5.6-luna-fast`               |
 | `openai/gpt-5.6-sol`                     |
+| `openai/gpt-5.6-sol-fast`                |
 | `openai/gpt-5.6-terra`                   |
+| `openai/gpt-5.6-terra-fast`              |
 | `openai/gpt-image-1`                     |
 | `openai/gpt-image-1-mini`                |
 | `openai/gpt-image-1.5`                   |
@@ -282,9 +298,11 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/o1`                              |
 | `openai/o3`                              |
 | `openai/o3-deep-research`                |
+| `openai/o3-fast`                         |
 | `openai/o3-mini`                         |
 | `openai/o3-pro`                          |
 | `openai/o4-mini`                         |
+| `openai/o4-mini-fast`                    |
 | `openai/text-embedding-3-large`          |
 | `openai/text-embedding-3-small`          |
 | `openai/text-embedding-ada-002`          |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6076 models from 177 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 6097 models from 178 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/cloudflare-workers-ai.md

@@ -2,7 +2,7 @@
 
 # ![Cloudflare Workers AI logo](https://models.dev/logos/cloudflare-workers-ai.svg)Cloudflare Workers AI
 
-Access 24 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_API_KEY` environment variable. Configure `CLOUDFLARE_ACCOUNT_ID` as well.
+Access 25 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_API_KEY` environment variable. Configure `CLOUDFLARE_ACCOUNT_ID` as well.
 
 Learn more in the [Cloudflare Workers AI documentation](https://developers.cloudflare.com/workers-ai/models/).
 
@@ -58,6 +58,7 @@ for await (const chunk of stream) {
 | `cloudflare-workers-ai/@cf/openai/gpt-oss-20b`                       | 128K    |       |           |       |       |       | $0.20      | $0.30       |
 | `cloudflare-workers-ai/@cf/qwen/qwen2.5-coder-32b-instruct`          | 33K     |       |           |       |       |       | $0.66      | $1          |
 | `cloudflare-workers-ai/@cf/qwen/qwen3-30b-a3b-fp8`                   | 33K     |       |           |       |       |       | $0.05      | $0.34       |
+| `cloudflare-workers-ai/@cf/qwen/qwen3.8-27b`                         | 262K    |       |           |       |       |       | $0.45      | $3          |
 | `cloudflare-workers-ai/@cf/qwen/qwq-32b`                             | 24K     |       |           |       |       |       | $0.66      | $1          |
 | `cloudflare-workers-ai/@cf/zai-org/glm-4.7-flash`                    | 131K    |       |           |       |       |       | $0.06      | $0.40       |
 | `cloudflare-workers-ai/@cf/zai-org/glm-5.2`                          | 262K    |       |           |       |       |       | $1         | $4          |

package/.docs/models/providers/deepinfra.md

@@ -2,7 +2,7 @@
 
 # ![Deep Infra logo](https://models.dev/logos/deepinfra.svg)Deep Infra
 
-Access 59 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
+Access 60 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
 
 Learn more in the [Deep Infra documentation](https://deepinfra.com/models).
 
@@ -77,6 +77,7 @@ for await (const chunk of stream) {
 | `deepinfra/Qwen/Qwen3.6-35B-A3B`                              | 262K    |       |           |       |       |       | $0.10      | $0.95       |
 | `deepinfra/Qwen/Qwen3.7-Max`                                  | 256K    |       |           |       |       |       | $3         | $8          |
 | `deepinfra/Qwen/Qwen3.8-2.4T-A95B`                            | 262K    |       |           |       |       |       | $2         | $6          |
+| `deepinfra/Qwen/Qwen3.8-27B`                                  | 262K    |       |           |       |       |       | $0.40      | $3          |
 | `deepinfra/Qwen/Qwen3.8-Max`                                  | 256K    |       |           |       |       |       | $2         | $5          |
 | `deepinfra/stepfun-ai/Step-3.7-Flash`                         | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `deepinfra/tencent/Hy3`                                       | 262K    |       |           |       |       |       | $0.14      | $0.58       |

package/.docs/models/providers/edenai.md

@@ -2,7 +2,7 @@
 
 # ![Eden AI logo](https://models.dev/logos/edenai.svg)Eden AI
 
-Access 232 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
+Access 234 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
 
 Learn more in the [Eden AI documentation](https://docs.edenai.co).
 
@@ -66,6 +66,7 @@ for await (const chunk of stream) {
 | `edenai/cloudflare/@cf/openai/gpt-oss-120b`                            | 128K    |       |           |       |       |       | $0.35      | $0.75       |
 | `edenai/cloudflare/@cf/openai/gpt-oss-20b`                             | 128K    |       |           |       |       |       | $0.20      | $0.30       |
 | `edenai/cloudflare/@cf/qwen/qwen2.5-coder-32b-instruct`                | 33K     |       |           |       |       |       | $0.66      | $1          |
+| `edenai/cloudflare/@cf/qwen/qwen3.8-27b`                               | 262K    |       |           |       |       |       | $0.45      | $3          |
 | `edenai/cloudflare/@cf/zai-org/glm-4.7-flash`                          | 131K    |       |           |       |       |       | $0.06      | $0.40       |
 | `edenai/cohere/command-a-03-2025`                                      | 288K    |       |           |       |       |       | $3         | $10         |
 | `edenai/cohere/command-r-08-2024`                                      | 128K    |       |           |       |       |       | $0.15      | $0.60       |
@@ -90,6 +91,7 @@ for await (const chunk of stream) {
 | `edenai/deepinfra/nvidia/Nemotron-3-Nano-30B-A3B`                      | 262K    |       |           |       |       |       | $0.05      | $0.20       |
 | `edenai/deepinfra/openai/gpt-oss-120b`                                 | 131K    |       |           |       |       |       | $0.04      | $0.17       |
 | `edenai/deepinfra/openai/gpt-oss-20b`                                  | 131K    |       |           |       |       |       | $0.03      | $0.14       |
+| `edenai/deepinfra/Qwen/Qwen3.8-27B`                                    | 262K    |       |           |       |       |       | $0.40      | $3          |
 | `edenai/deepinfra/stepfun-ai/Step-3.5-Flash`                           | 262K    |       |           |       |       |       | $0.09      | $0.30       |
 | `edenai/deepinfra/stepfun-ai/Step-3.7-Flash`                           | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `edenai/deepinfra/tencent/Hy3`                                         | 262K    |       |           |       |       |       | $0.14      | $0.58       |

package/.docs/models/providers/kilo.md

@@ -2,7 +2,7 @@
 
 # ![Kilo Gateway logo](https://models.dev/logos/kilo.svg)Kilo Gateway
 
-Access 360 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
+Access 358 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
 
 Learn more in the [Kilo Gateway documentation](https://kilo.ai).
 
@@ -40,7 +40,7 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 262K    |       |           |       |       |       | $0.08      | $0.16       |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.08      | $0.16       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.38      | $2          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~moonshotai/kimi-latest`                                  | 975K    |       |           |       |       |       | $3         | $13         |
@@ -154,7 +154,6 @@ for await (const chunk of stream) {
 | `kilo/kwaipilot/kat-coder-air-v2.5`                             | 256K    |       |           |       |       |       | $0.15      | $0.60       |
 | `kilo/kwaipilot/kat-coder-pro-v2`                               | 256K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/kwaipilot/kat-coder-pro-v2.5`                             | 256K    |       |           |       |       |       | $0.74      | $3          |
-| `kilo/liquid/lfm-2.5-2.6b:free`                                 | 128K    |       |           |       |       |       | —          | —           |
 | `kilo/mancer/weaver`                                            | 8K      |       |           |       |       |       | $0.50      | $0.75       |
 | `kilo/meituan/longcat-2.0`                                      | 1.0M    |       |           |       |       |       | $0.75      | $3          |
 | `kilo/meta-llama/llama-3.1-70b-instruct`                        | 131K    |       |           |       |       |       | $0.40      | $0.40       |
@@ -394,7 +393,6 @@ for await (const chunk of stream) {
 | `kilo/z-ai/glm-5-turbo`                                         | 203K    |       |           |       |       |       | $1         | $4          |
 | `kilo/z-ai/glm-5.1`                                             | 200K    |       |           |       |       |       | $1         | $4          |
 | `kilo/z-ai/glm-5.2`                                             | 1.0M    |       |           |       |       |       | $1         | $4          |
-| `kilo/z-ai/glm-5.2:free`                                        | 128K    |       |           |       |       |       | —          | —           |
 | `kilo/z-ai/glm-5v-turbo`                                        | 203K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration

package/.docs/models/providers/kosmik.md

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ![Kosmik Compute logo](https://models.dev/logos/kosmik.svg)Kosmik Compute
+
+Access 1 Kosmik Compute model through Mastra's model router. Authentication is handled automatically using the `KOSMIK_API_KEY` environment variable.
+
+Learn more in the [Kosmik Compute documentation](https://api.koscompute.com/docs/).
+
+```bash
+KOSMIK_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "kosmik/qwen/qwen3.8-27b"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Kosmik Compute documentation](https://api.koscompute.com/docs/) for details.
+
+## Models
+
+| Model                     | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `kosmik/qwen/qwen3.8-27b` | 262K    |       |           |       |       |       | $0.35      | $2          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.koscompute.com/v1",
+    id: "kosmik/qwen/qwen3.8-27b",
+    apiKey: process.env.KOSMIK_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "kosmik/qwen/qwen3.8-27b"
+      : "kosmik/qwen/qwen3.8-27b";
+  }
+});
+```

package/.docs/models/providers/merge-gateway.md

@@ -2,7 +2,7 @@
 
 # ![Merge Gateway logo](https://models.dev/logos/merge-gateway.svg)Merge Gateway
 
-Access 171 Merge Gateway models through Mastra's model router. Authentication is handled automatically using the `MERGE_GATEWAY_API_KEY` environment variable.
+Access 172 Merge Gateway models through Mastra's model router. Authentication is handled automatically using the `MERGE_GATEWAY_API_KEY` environment variable.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -183,6 +183,7 @@ for await (const chunk of stream) {
 | `merge-gateway/qwen/qwen3.7-plus`                              | 1.0M    |       |           |       |       |       | $0.40      | $2          |
 | `merge-gateway/qwen/qwen3.8-max`                               | 1.0M    |       |           |       |       |       | $2         | $6          |
 | `merge-gateway/sakana/fugu-ultra`                              | 1.0M    |       |           |       |       |       | $5         | $30         |
+| `merge-gateway/sakana/sakana-namazu`                           | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `merge-gateway/thinkingmachines/inkling`                       | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `merge-gateway/writer/palmyra-x4`                              | 128K    |       |           |       |       |       | $3         | $10         |
 | `merge-gateway/writer/palmyra-x5`                              | 1.0M    |       |           |       |       |       | $0.60      | $6          |

package/.docs/models/providers/nano-gpt.md

@@ -401,12 +401,12 @@ for await (const chunk of stream) {
 | `nano-gpt/openai/gpt-5.5`                                        | 1.0M    |       |           |       |       |       | $5         | $30         |
 | `nano-gpt/openai/gpt-5.6-luna`                                   | 1.1M    |       |           |       |       |       | $0.10      | $0.60       |
 | `nano-gpt/openai/gpt-5.6-luna-pro`                               | 1.1M    |       |           |       |       |       | $0.10      | $0.60       |
-| `nano-gpt/openai/gpt-5.6-sol`                                    | 1.1M    |       |           |       |       |       | $5         | $30         |
-| `nano-gpt/openai/gpt-5.6-sol-pro`                                | 1.1M    |       |           |       |       |       | $5         | $30         |
+| `nano-gpt/openai/gpt-5.6-sol`                                    | 1.1M    |       |           |       |       |       | $3         | $15         |
+| `nano-gpt/openai/gpt-5.6-sol-pro`                                | 1.1M    |       |           |       |       |       | $3         | $15         |
 | `nano-gpt/openai/gpt-5.6-terra`                                  | 1.1M    |       |           |       |       |       | $1         | $6          |
 | `nano-gpt/openai/gpt-5.6-terra-pro`                              | 1.1M    |       |           |       |       |       | $1         | $6          |
-| `nano-gpt/openai/gpt-chat-latest`                                | 1.1M    |       |           |       |       |       | $5         | $30         |
-| `nano-gpt/openai/gpt-latest`                                     | 1.1M    |       |           |       |       |       | $5         | $30         |
+| `nano-gpt/openai/gpt-chat-latest`                                | 1.1M    |       |           |       |       |       | $3         | $15         |
+| `nano-gpt/openai/gpt-latest`                                     | 1.1M    |       |           |       |       |       | $3         | $15         |
 | `nano-gpt/openai/gpt-oss-120b`                                   | 128K    |       |           |       |       |       | $0.35      | $0.75       |
 | `nano-gpt/openai/gpt-oss-20b`                                    | 128K    |       |           |       |       |       | $0.20      | $0.30       |
 | `nano-gpt/openai/gpt-oss-safeguard-20b`                          | 128K    |       |           |       |       |       | $0.07      | $0.30       |

package/.docs/models/providers/sakana.md

@@ -2,7 +2,7 @@
 
 # ![Sakana AI logo](https://models.dev/logos/sakana.svg)Sakana AI
 
-Access 3 Sakana AI models through Mastra's model router. Authentication is handled automatically using the `SAKANA_API_KEY` environment variable.
+Access 4 Sakana AI models through Mastra's model router. Authentication is handled automatically using the `SAKANA_API_KEY` environment variable.
 
 Learn more in the [Sakana AI documentation](https://console.sakana.ai/models).
 
@@ -39,6 +39,7 @@ for await (const chunk of stream) {
 | `sakana/fugu`                | 1.0M    |       |           |       |       |       | —          | —           |
 | `sakana/fugu-ultra`          | 1.0M    |       |           |       |       |       | $5         | $30         |
 | `sakana/fugu-ultra-20260615` | 1.0M    |       |           |       |       |       | $5         | $30         |
+| `sakana/sakana-namazu`       | 262K    |       |           |       |       |       | $0.95      | $4          |
 
 ## Advanced configuration
 
@@ -68,7 +69,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "sakana/fugu-ultra-20260615"
+      ? "sakana/sakana-namazu"
       : "sakana/fugu";
   }
 });

package/.docs/models/providers.md

@@ -80,6 +80,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Kenari](https://mastra.ai/models/providers/kenari)
 - [Kilo Gateway](https://mastra.ai/models/providers/kilo)
 - [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
+- [Kosmik Compute](https://mastra.ai/models/providers/kosmik)
 - [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
 - [Lilac](https://mastra.ai/models/providers/lilac)
 - [Llama](https://mastra.ai/models/providers/llama)

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

@@ -778,9 +778,29 @@ const agent = await mastraClient.createStoredAgent({
     version: '1.0',
     team: 'engineering',
   },
+  durable: true,
 })
 ```
 
+#### Durable stored agents
+
+Set `durable` to run the agent as a [durable agent](https://mastra.ai/docs/harness/durable-agents) once the server hydrates it. Pass `true` to accept the defaults, or an object to tune the durable loop:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: 'durable-agent',
+  name: 'Durable Agent',
+  instructions: 'You are a helpful assistant.',
+  model: {
+    provider: 'openai',
+    name: 'gpt-5.4',
+  },
+  durable: { maxSteps: 50, cleanupTimeoutMs: 0 },
+})
+```
+
+Only serializable options are accepted. The durable cache and pubsub are inherited from the server's `Mastra` instance. If it has no distributed cache or pubsub configured, durability is process-local. Automatic recovery is still configured in code through `recovery.durableAgents`.
+
 ### `getStoredAgent()`
 
 Get an instance of a specific stored agent:

package/.docs/reference/processors/skill-search-processor.md

@@ -41,6 +41,8 @@ const skillSearch = new SkillSearchProcessor({
 
 **options.ttl** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
 
+**options.blockingRefresh** (`boolean`): When true, awaits the skills staleness check before the first step of each request so skill changes appear in the same turn. When false, the cached catalog is served and revalidated in the background, so skill changes can lag by one turn plus the staleness cooldown (up to 30 seconds).
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'skill-search'

package/.docs/reference/processors/token-limiter-processor.md

@@ -64,6 +64,10 @@ for await (const part of stream.fullStream) {
 }
 ```
 
+## Media token counting
+
+Images and file attachments are estimated rather than tokenized. This applies to `file` message parts and to tool results shaped like `{ data, mediaType }`. Images use a flat per-image estimate, other media is estimated from its decoded byte size, and remote URLs or provider file ids use a flat fallback because their size isn't known locally. Encoded payloads such as base64 data are never counted as text, which would otherwise inflate the count by an order of magnitude and truncate history unnecessarily.
+
 ## Error behavior
 
 When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:

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

@@ -65,6 +65,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to true, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
 
+**protocolVersion** (`'auto' | '2026-07-28'`): Opt-in MCP protocol version negotiation. Omitted keeps the legacy (2025-era) connect sequence unchanged. 'auto' probes the server at connect time and uses the stateless '2026-07-28' revision when the server supports it, with a safe fallback to the legacy handshake. '2026-07-28' pins that revision exactly and fails with a typed error when the server does not offer it. Elicitation handlers work on both eras: on a '2026-07-28' connection, embedded elicitation requests from input\_required results are dispatched through the same registered handler and the originating call retries automatically.
+
 ## Tool approval
 
 Use `requireToolApproval` on a server definition to require human approval before any tool from that server is executed. This works with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.

package/.docs/reference/tools/mcp-server.md

@@ -91,6 +91,35 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **appResources** (`AppResources`): A map of ui:// URIs to app resource configurations. Each entry defines an interactive HTML UI served via the MCP Apps extension (SEP-1865). See the MCP Apps section for details.
 
+**protocolVersion** (`'2025-11-25' | '2026-07-28'`): Opt-in MCP protocol revision. Omitted (or '2025-11-25') keeps the legacy behavior exactly. Set to '2026-07-28' to serve the stateless MCP revision. See the Protocol versions section for details.
+
+**cacheHints** (`MCPServerCacheHints`): Cache hints (ttlMs / cacheScope) advertised on cacheable results of the '2026-07-28' protocol revision, keyed by operation (e.g. 'tools/list'). Only applied when protocolVersion: '2026-07-28' is set.
+
+## Protocol versions
+
+By default, `MCPServer` speaks the legacy (2025-era) MCP protocol: sessionful streamable HTTP with an `initialize` handshake. Set `protocolVersion: '2026-07-28'` to serve the stateless MCP revision instead:
+
+- HTTP and serverless requests go through a dual-era handler: clients that speak `2026-07-28` are served natively (stateless, per-request envelope), and legacy clients are served through a built-in stateless fallback on the same endpoint.
+- `startStdio()` serves both eras: the opening exchange selects the era for the connection.
+- Tool list, prompt list, resource list, and resource update notifications also reach `2026-07-28` clients through `subscriptions/listen`.
+- Tool log messages honor the caller's per-request `logLevel` opt-in instead of the session-level `logging/setLevel`.
+- Configured `cacheHints` are advertised on cacheable results such as `tools/list`.
+- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for an input.
+
+```typescript
+const server = new MCPServer({
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { weatherTool },
+  protocolVersion: '2026-07-28',
+  cacheHints: {
+    'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
+  },
+})
+```
+
+Omitting `protocolVersion` keeps the current behavior unchanged.
+
 ## Exposing agents as tools
 
 A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
@@ -239,6 +268,8 @@ await server.startStdio()
 
 ### `startSSE()`
 
+> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
+
 This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
 
 ```typescript
@@ -291,6 +322,8 @@ Here are the details for the values needed by the `startSSE` method:
 
 ### `startHonoSSE()`
 
+> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
+
 This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
 
 ```typescript
@@ -361,6 +394,21 @@ async startHTTP({
 }): Promise<void>
 ```
 
+#### Options with `protocolVersion: '2026-07-28'`
+
+The `2026-07-28` protocol uses one shared stateless handler instead of a transport configured for each request. `startHTTP()` handles legacy transport options as follows:
+
+| Options                                                                              | Behavior                                                                                                                                |
+| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverless: true`, `serverlessStreaming: true`, `sessionIdGenerator: undefined`     | Accepted because the modern handler already provides stateless requests and automatic request-scoped streaming.                         |
+| `allowedHosts`, `allowedOrigins`, `enableDnsRebindingProtection`                     | Enforced before the request reaches the modern handler. Host and origin lists are active when `enableDnsRebindingProtection` is `true`. |
+| `sessionIdGenerator` with a function, session callbacks, or `eventStore`             | Rejected because the modern protocol doesn't create HTTP sessions.                                                                      |
+| `enableJsonResponse`, `retryInterval`, `keepAliveMs`, or `supportedProtocolVersions` | Rejected because these values configure a shared handler and can't vary between requests.                                               |
+| `serverless: false` or `serverlessStreaming: false`                                  | Rejected because these values request behavior that differs from the modern handler.                                                    |
+| Unknown options                                                                      | Rejected instead of being ignored.                                                                                                      |
+
+Omit `options` when you don't need request guards or compatibility declarations.
+
 Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
 
 ```typescript
@@ -383,7 +431,7 @@ httpServer.listen(PORT, () => {
 })
 ```
 
-For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
+For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation on the legacy protocol path. Servers configured with `protocolVersion: '2026-07-28'` are already stateless and may omit this option.
 
 ```typescript
 // Supabase Edge Function example
@@ -457,7 +505,7 @@ serve(async req => {
 >
 > This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
 >
-> The following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
+> On the legacy protocol path, the following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
 >
 > - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
 > - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp-docs-server
 
+## 1.2.17-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [[`6db7a5d`](https://github.com/mastra-ai/mastra/commit/6db7a5dd3dd2b6f7ef75dcd804fcffef5fa83963), [`0cdc5dc`](https://github.com/mastra-ai/mastra/commit/0cdc5dc69024957815da4f51acc4119eb4f447d7)]:
+  - @mastra/core@1.60.0-alpha.12
+
+## 1.2.17-alpha.18
+
+### Patch Changes
+
+- Updated dependencies [[`6223446`](https://github.com/mastra-ai/mastra/commit/6223446ddce6166e96e0ba5e00d628b615dee8ca), [`583e235`](https://github.com/mastra-ai/mastra/commit/583e23519c13af16c1746f9c49722d011216611b), [`a77f8d4`](https://github.com/mastra-ai/mastra/commit/a77f8d4740d2178a74c41e4bf678b4fcd8fa0bb2), [`40d358e`](https://github.com/mastra-ai/mastra/commit/40d358e29d55543803e64b49241122f598ffabc7), [`e80cd7e`](https://github.com/mastra-ai/mastra/commit/e80cd7e7683e7d732e1cc6784bcac1d2640d2ce3), [`39ba1b9`](https://github.com/mastra-ai/mastra/commit/39ba1b9ce256a9a910a16f125cc6a59588185bfe), [`0f53aeb`](https://github.com/mastra-ai/mastra/commit/0f53aeb119158bd9f83bd8ef667f1f675740e8f0), [`20504b2`](https://github.com/mastra-ai/mastra/commit/20504b2ecebd0e077acda3d457ab57480a98ed3e)]:
+  - @mastra/core@1.60.0-alpha.11
+  - @mastra/mcp@1.17.0-alpha.2
+
 ## 1.2.17-alpha.17
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.17-alpha.17",
+  "version": "1.2.17-alpha.19",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.60.0-alpha.10",
-    "@mastra/mcp": "^1.17.0-alpha.1"
+    "@mastra/core": "1.60.0-alpha.12",
+    "@mastra/mcp": "^1.17.0-alpha.2"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/types-builder": "0.0.98",
-    "@mastra/core": "1.60.0-alpha.10",
-    "@internal/lint": "0.0.123"
+    "@internal/lint": "0.0.123",
+    "@mastra/core": "1.60.0-alpha.12",
+    "@internal/types-builder": "0.0.98"
   },
   "homepage": "https://mastra.ai",
   "repository": {