@mastra/mcp-docs-server 1.2.2 → 1.2.3-alpha.11

package/.docs/docs/{harness → agent-controller}/tool-approvals.md

@@ -1,6 +1,6 @@
 # Tool approvals and permissions
 
-The Harness provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
+The AgentController provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.
 
 ## Permission policies
 
@@ -16,18 +16,18 @@ Set policies per-category or per-tool. Per-tool policies take precedence over ca
 
 ```typescript
 // Category-level: all execute tools require approval
-await harness.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
+await agentController.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
 
 // Tool-level: this specific tool is always blocked
-await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+await agentController.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
 ```
 
 ### Tool categories
 
-The `toolCategoryResolver` maps tool names to categories. Pass it to the Harness constructor:
+The `toolCategoryResolver` maps tool names to categories. Pass it to the AgentController constructor:
 
 ```typescript
-const harness = new Harness({
+const agentController = new AgentController({
   id: 'my-agent',
   toolCategoryResolver: toolName => {
     if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
@@ -41,13 +41,13 @@ Built-in categories are `read`, `edit`, `execute`, `mcp`, and `other`.
 
 ## Responding to approval requests
 
-When a tool's policy is `ask`, the Harness emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
+When a tool's policy is `ask`, the AgentController emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_approval_required') {
     // Show approval UI...
-    harness.session.respondToToolApproval({ decision: 'approve' })
+    agentController.session.respondToToolApproval({ decision: 'approve' })
   }
 })
 ```
@@ -55,22 +55,22 @@ harness.subscribe(event => {
 The `decision` field accepts `'approve'`, `'decline'`, or `'always_allow_category'`. When `always_allow_category` is used, the tool's category is granted for the rest of the session. Future tools in the same category are auto-approved.
 
 ```typescript
-harness.session.respondToToolApproval({ decision: 'always_allow_category' })
+agentController.session.respondToToolApproval({ decision: 'always_allow_category' })
 ```
 
 ## Session grants
 
-The Harness owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/harness/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
+The AgentController owns permission _policy_ (which categories require approval); the [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
 
 ```typescript
 // Grant all edit tools for this session
-harness.session.grantCategory('edit')
+agentController.session.grantCategory('edit')
 
 // Grant a specific tool
-harness.session.grantTool('mastra_workspace_execute_command')
+agentController.session.grantTool('mastra_workspace_execute_command')
 
 // Check current grants
-const grants = harness.session.getGrants()
+const grants = agentController.session.getGrants()
 // { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
 ```
 
@@ -79,11 +79,11 @@ const grants = harness.session.getGrants()
 Interactive built-in tools (`ask_user`, `submit_plan`) use the native tool-suspension primitive instead of the approval flow. They emit a `tool_suspended` event with `toolCallId`, `toolName`, and `suspendPayload`. Resume with `respondToToolSuspension()`:
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
     const { question } = event.suspendPayload as { question: string }
     // Show question to user, then resume:
-    harness.respondToToolSuspension({
+    agentController.respondToToolSuspension({
       toolCallId: event.toolCallId,
       resumeData: 'User response here',
     })
@@ -97,13 +97,13 @@ The `submit_plan` tool suspends via the same mechanism. Resume with an `action`
 
 ```typescript
 // Approve the plan
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'approved' },
 })
 
 // Reject with feedback
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'rejected', feedback: 'Needs more detail' },
 })
@@ -111,7 +111,7 @@ harness.respondToToolSuspension({
 
 ## Built-in tools
 
-The Harness provides these built-in tools to agents in every mode:
+The AgentController provides these built-in tools to agents in every mode:
 
 | Tool            | Description                                                         |
 | --------------- | ------------------------------------------------------------------- |
@@ -126,7 +126,7 @@ The Harness provides these built-in tools to agents in every mode:
 Disable specific built-in tools with `disableBuiltinTools`:
 
 ```typescript
-const harness = new Harness({
+const agentController = new AgentController({
   id: 'no-plans',
   disableBuiltinTools: ['submit_plan'],
 })
@@ -134,8 +134,8 @@ const harness = new Harness({
 
 ## Related
 
-- [Harness overview](https://mastra.ai/docs/harness/overview)
-- [Session](https://mastra.ai/docs/harness/session)
-- [Subagents](https://mastra.ai/docs/harness/subagents)
+- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
+- [Session](https://mastra.ai/docs/agent-controller/session)
+- [Subagents](https://mastra.ai/docs/agent-controller/subagents)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
-- [API reference](https://mastra.ai/reference/harness/harness-class)
+- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

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

@@ -357,6 +357,44 @@ For automatic tool resumption to work:
 
 Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
 
+## Resuming after a restart
+
+The examples above hold on to `stream.runId` between suspension and approval. That works while the process stays alive, but in production the approval often arrives later — after a page refresh, a server restart, or on a different server instance behind a load balancer.
+
+Use [`listSuspendedRuns()`](https://mastra.ai/reference/agents/listSuspendedRuns) to rediscover the pending run for a conversation from storage:
+
+```typescript
+// In the request handler that receives the user's decision
+const { runs } = await agent.listSuspendedRuns({
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+
+const run = runs[0]
+const toolCall = run?.toolCalls[0]
+
+if (run && toolCall) {
+  let stream
+  if (toolCall.requiresApproval) {
+    // Suspended by requireApproval — approve or decline the tool call
+    stream = await agent.approveToolCall({ runId: run.runId, toolCallId: toolCall.toolCallId })
+  } else {
+    // Suspended by suspend() — resume with the data the tool asked for
+    console.log('Tool asked:', toolCall.suspendPayload)
+    stream = await agent.resumeStream({ name: 'San Francisco' }, { runId: run.runId })
+  }
+  for await (const chunk of stream.textStream) process.stdout.write(chunk)
+}
+```
+
+Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `args`, and `requiresApproval`). Approval suspensions (`requiresApproval: true`) are answered with `approveToolCall()` / `declineToolCall()`, while `suspend()`-based suspensions carry their `suspendPayload` and expect `resumeStream()` with resume data — so you can rebuild the right UI for either flow without keeping any state in memory.
+
+`sendToolApproval()` uses the same storage-backed discovery automatically: when no active run is found in memory for the thread, it looks up the suspended run in storage before failing. If several suspended runs match the thread, pass a `toolCallId` to disambiguate.
+
+The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
+
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/memory/storage). The default in-memory store loses snapshots when the process exits.
+
 ## Tool approval: Supervisor agents
 
 A [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:

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

@@ -164,6 +164,53 @@ By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupporte
 
 > **Note:** See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced mime types.
 
+## Serverless deployment
+
+On serverless platforms like Vercel, each request runs in a separate, short-lived instance. Channels need two things to work reliably in that environment: a way to keep the function alive while the agent responds, and a shared pub/sub so instances can coordinate.
+
+### Keep the function alive with `waitUntil`
+
+A channel webhook returns a `200` response right away, then the agent runs in the background to post its reply. On most serverless platforms the function is frozen as soon as it responds, which kills the run before the agent answers. Pass a `waitUntil` function so the platform keeps the instance alive until the run finishes.
+
+On Vercel, pass `waitUntil` from `@vercel/functions`:
+
+```typescript
+import { waitUntil } from '@vercel/functions'
+
+export const agent = new Agent({
+  // ...
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    waitUntil,
+  },
+})
+```
+
+Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soon as the response is sent. Cloudflare Workers and Netlify Functions are detected automatically from the request context, so they don't need it. For runtimes where `waitUntil` lives on the request context but isn't detected automatically, use `resolveWaitUntil`. See the [Channels reference](https://mastra.ai/reference/agents/channels) for details.
+
+### Coordinate instances with a shared pub/sub
+
+Channels route messages through the agent's signal pipeline, and each run acquires a lease on its thread so a single run owns the conversation at a time. The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
+
+Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  agents: { agent },
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'mastra:my-app',
+  }),
+})
+```
+
+Vercel's one-click Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+
 ## Related
 
 - [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)

package/.docs/docs/agents/heartbeats.md

@@ -0,0 +1,211 @@
+# Heartbeats
+
+**Added in:** `@mastra/core@1.46.0`
+
+> **Beta:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
+A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+
+Heartbeats are persisted, so they survive restarts and redeploys. Manage them at runtime through `mastra.heartbeats`, the canonical create, read, update, and delete (CRUD) surface.
+
+## Prerequisites
+
+Heartbeats require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain, for example `@mastra/libsql`. Without one, `mastra.heartbeats.create()` throws.
+
+## Quickstart
+
+The following heartbeat runs the `pinger` agent every hour. It has no thread, so each fire is an isolated `agent.generate()` run.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+
+const pinger = new Agent({
+  id: 'pinger',
+  name: 'Pinger',
+  instructions: 'Report the current system status in one sentence.',
+  model: 'openai/gpt-5.5',
+})
+
+const mastra = new Mastra({
+  agents: { pinger },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+})
+
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+Mastra starts the scheduler the first time a heartbeat is created, then fires the agent on the cron you specify.
+
+## Cadence
+
+Heartbeats fire on a cron expression. The `cron` field accepts a standard 5-, 6-, or 7-part cron expression, and it's validated when you create or update the heartbeat.
+
+Croner nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
+
+```typescript
+// Every weekday at 9am
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * 1-5',
+  prompt: 'Start-of-day check.',
+})
+```
+
+Set `timezone` to an IANA timezone, for example `America/New_York`, so fire times don't depend on the host's locale. When omitted, the cron resolves against the host's local timezone.
+
+For more readable cron construction, you can use a userland builder such as [`cron-time-generator`](https://www.npmjs.com/package/cron-time-generator) and pass its output to `cron`.
+
+## Threadless and threaded heartbeats
+
+A heartbeat fires in one of two modes, decided by whether you pass a `threadId`.
+
+### Threadless
+
+Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing is written to a conversation thread. This is the simplest mode and suits status checks, reports, and other work that doesn't need conversation context.
+
+### Threaded
+
+With a `threadId`, the heartbeat sends a [signal](https://mastra.ai/docs/agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded heartbeats require a `resourceId` alongside the `threadId`.
+
+```typescript
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+```
+
+Threaded heartbeats accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
+
+- `signalType`: the [signal type](https://mastra.ai/docs/agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
+- `tagName`: the XML tag the signal renders as. Defaults to `heartbeat`, so a fire surfaces to the agent as `<heartbeat>…</heartbeat>`.
+- `attributes`: values rendered onto the signal's XML tag.
+- `ifActive`: behavior when the thread is already streaming, as `{ behavior, attributes }`. `behavior` is one of `deliver`, `persist`, or `discard`.
+- `ifIdle`: behavior when the thread is idle, as `{ behavior, attributes, streamOptions }`. `behavior` is one of `wake`, `persist`, or `discard`. `streamOptions.requestContext` is applied to the woken run.
+
+These fields require a `threadId`. Passing them on a threadless heartbeat throws.
+
+```typescript
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+  tagName: 'check-in', // renders as <check-in>…</check-in>
+  attributes: { source: 'cron' },
+  ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
+  ifIdle: {
+    behavior: 'wake', // wake the agent if the thread is idle
+    streamOptions: { requestContext: { locale: 'en-US' } },
+  },
+})
+```
+
+`providerOptions` are merged into the signal payload on every fire and apply to both threaded and threadless heartbeats.
+
+## Managing heartbeats
+
+Use `mastra.heartbeats` for all heartbeat operations. To scope to a single agent, pass `agentId` to `create` or `list`.
+
+```typescript
+// Create
+const hb = await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Status check.',
+})
+
+// Read
+await mastra.heartbeats.get(hb.id)
+await mastra.heartbeats.list({ agentId: 'pinger' })
+
+// Update — changing cron or timezone recomputes the next fire time
+await mastra.heartbeats.update(hb.id, { cron: '*/30 * * * *' })
+
+// Pause and resume
+await mastra.heartbeats.pause(hb.id)
+await mastra.heartbeats.resume(hb.id)
+
+// Fire once now, off-schedule
+await mastra.heartbeats.run(hb.id)
+
+// Delete
+await mastra.heartbeats.delete(hb.id)
+```
+
+A few rules worth knowing:
+
+- `pause` and `resume` are durable and idempotent. A paused heartbeat survives restarts, and `resume` recomputes the next fire time from now rather than firing backlogged runs.
+- `run` fires the heartbeat once immediately without affecting its schedule.
+- `list` filters by `agentId`, `threadId`, `resourceId`, and `name`.
+
+### Custom IDs
+
+By default `create` generates a random `hb_<uuid>` id. Pass `id` to choose a stable one, for example when you want a predictable handle to look up, update, or delete later:
+
+```typescript
+await mastra.heartbeats.create({
+  id: 'nightly-summary',
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+})
+// stored as `hb_nightly-summary`
+```
+
+The id is normalized to `hb_<slug>`: the `hb_` prefix is added if missing and the rest is slugified. Creating a heartbeat with an id that already exists throws, so use `update` to change an existing one.
+
+### From the client
+
+The same operations are available from `@mastra/client-js` over the server routes, so you can manage heartbeats from a separate process or a UI.
+
+## Lifecycle hooks
+
+Hooks let you run code at key points in a heartbeat's lifecycle, for example to compute fire-time parameters or react to the outcome. Configure them on the `Mastra` constructor under `heartbeat`. The hooks are a single flat bundle that runs for every agent's heartbeats; each hook context carries the firing `agentId`, so branch on it when you need per-agent behavior. Hooks live at the `Mastra` level so they apply to both code-defined and stored agents.
+
+```typescript
+const mastra = new Mastra({
+  agents: { pinger },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  heartbeat: {
+    prepare: async ({ agentId, heartbeat, trigger }) => {
+      // Return overrides, null to skip this fire, or undefined for defaults
+      return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
+    },
+    onFinish: async ({ agentId, outcome, runId }) => {
+      // Runs on any non-error, non-abort outcome
+    },
+    onError: async ({ agentId, phase, error }) => {
+      // Runs when prepare, the signal, or the agent run threw
+    },
+    onAbort: async ({ agentId, runId }) => {
+      // Runs when the run was aborted mid-stream
+    },
+  },
+})
+```
+
+The hooks are:
+
+- `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
+- `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
+- `onError`: runs when `prepare`, the signal, or the agent run threw.
+- `onAbort`: runs when the run was aborted mid-stream.
+
+Every hook context includes `agentId` (the agent the heartbeat fired for) alongside `heartbeat` and `trigger`.
+
+Hook exceptions are caught and logged. They never re-route the worker or trigger another hook.
+
+## Related
+
+- [Signals](https://mastra.ai/docs/agents/signals): the delivery mechanism behind threaded heartbeats.
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): run a workflow, rather than an agent, on a cron schedule.

package/.docs/docs/agents/signals.md

@@ -322,6 +322,29 @@ Use `createNotificationInboxTool()` to give agents one tool for inbox actions in
 
 `sendNotificationSignal()` requires a storage domain with `notifications` support. Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
+## Distributed and serverless deployments
+
+Signals coordinate runs through a pub/sub backend. When a signal arrives on a backend that implements `LeaseProvider`, Mastra acquires a lease on the target thread so a single process owns the conversation at a time, then either wakes the agent or routes the input into the running loop. Backends without leasing fall back to a no-op that always grants ownership, which is fine in a single process but not across instances.
+
+The default in-memory pub/sub can't cross instance boundaries. On serverless platforms like Vercel, or any multi-instance deployment, a follow-up signal can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
+
+Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  agents: { agent },
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'mastra:my-app',
+  }),
+})
+```
+
+`RedisStreamsPubSub` implements both the event delivery contract and distributed leasing, so a single backend handles cross-instance signal delivery and lease ownership. Vercel's one-click Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+
 ## Compatibility and APIs
 
 ### Compatibility
@@ -404,4 +427,5 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
-- [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)
+- [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)

package/.docs/docs/observability/metrics/overview.md

@@ -8,9 +8,9 @@ Three categories of metrics are emitted automatically:
 - **Token usage metrics**: Input and output token counts broken down by type (text, cache, audio, image, reasoning).
 - **Cost estimation**: Estimated cost per model call based on an embedded pricing registry.
 
-> **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. aren't supported for metrics. In-memory storage resets on restart.
+> **Note:** Metrics require an analytics-capable store for observability. Most relational databases (LibSQL, MSSQL) aren't supported for metrics. In-memory storage resets on restart.
 >
-> For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`.
+> For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`. `PostgresStoreVNext` with the observability domain enabled also supports metrics, but always provide a time range to avoid full partition scans.
 >
 > Google Cloud Spanner supports metrics, but it's not recommended for heavy metrics workloads. The Spanner adapter disables metrics by default because metrics are write-heavy and scan-heavy. Set `disableMetrics: false` only for light workloads, or route metrics to an OLAP store.
 

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

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 337 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 336 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -61,7 +61,6 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-opus-4.1`                                     |
 | `anthropic/claude-opus-4.5`                                     |
 | `anthropic/claude-opus-4.6`                                     |
-| `anthropic/claude-opus-4.6-fast`                                |
 | `anthropic/claude-opus-4.7`                                     |
 | `anthropic/claude-opus-4.7-fast`                                |
 | `anthropic/claude-opus-4.8`                                     |

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

@@ -1,6 +1,6 @@
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 292 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 294 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -72,6 +72,7 @@ ANTHROPIC_API_KEY=ant-...
 | `amazon/nova-micro`                      |
 | `amazon/nova-pro`                        |
 | `amazon/titan-embed-text-v2`             |
+| `anthropic/claude-3.5-haiku`             |
 | `anthropic/claude-haiku-4.5`             |
 | `anthropic/claude-opus-4`                |
 | `anthropic/claude-opus-4.1`              |
@@ -267,6 +268,7 @@ ANTHROPIC_API_KEY=ant-...
 | `perplexity/sonar-pro`                   |
 | `perplexity/sonar-reasoning-pro`         |
 | `prodia/flux-fast-schnell`               |
+| `quiverai/arrow-1.1`                     |
 | `recraft/recraft-v2`                     |
 | `recraft/recraft-v3`                     |
 | `recraft/recraft-v4`                     |

package/.docs/models/index.md

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

package/.docs/models/providers/anthropic.md

@@ -1,6 +1,6 @@
 # ![Anthropic logo](https://models.dev/logos/anthropic.svg)Anthropic
 
-Access 18 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
+Access 17 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
 
 Learn more in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
 
@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "anthropic/claude-3-5-haiku-latest"
+  model: "anthropic/claude-fable-5"
 });
 
 // Generate a response
@@ -32,7 +32,6 @@ for await (const chunk of stream) {
 
 | Model                                  | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `anthropic/claude-3-5-haiku-latest`    | 200K    |       |           |       |       |       | $0.80      | $4          |
 | `anthropic/claude-fable-5`             | 1.0M    |       |           |       |       |       | $10        | $50         |
 | `anthropic/claude-haiku-4-5`           | 200K    |       |           |       |       |       | $1         | $5          |
 | `anthropic/claude-haiku-4-5-20251001`  | 200K    |       |           |       |       |       | $1         | $5          |
@@ -60,7 +59,7 @@ const agent = new Agent({
   id: "custom-agent",
   name: "custom-agent",
   model: {
-    id: "anthropic/claude-3-5-haiku-latest",
+    id: "anthropic/claude-fable-5",
     apiKey: process.env.ANTHROPIC_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -79,7 +78,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "anthropic/claude-sonnet-4-6"
-      : "anthropic/claude-3-5-haiku-latest";
+      : "anthropic/claude-fable-5";
   }
 });
 ```