@mastra/mcp-docs-server 1.2.26 → 1.2.27-alpha.1

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

@@ -134,7 +134,7 @@ await mastraClient.createStoredAgent({
 })
 ```
 
-`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`.
+`durable` also accepts `{ maxSteps, cleanupTimeoutMs }`. Only serializable options are accepted here, so snapshot persistence for API-created agents follows the server's `recovery.durableAgents` setting. 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()`
 
@@ -254,10 +254,33 @@ await durableAgent.resume(runId, { approved: true })
 
 ## Crash recovery
 
-If the server process crashes while a durable agent run is in progress, that run remains in `running` status in storage with no automatic retry. For orderly shutdowns such as rolling deploys, the generated server can also drain in-flight turns before exiting. See [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server). On the next server start you can re-drive these orphaned runs so they pick up where they left off.
+Durable agents can checkpoint each run's state to storage while it executes. If the server process crashes mid-run, the run remains in `running` status in storage with no automatic retry, and on the next server start you can re-drive these orphaned runs so they pick up where they left off. For orderly shutdowns such as rolling deploys, the generated server can also drain in-flight turns before exiting. See [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server).
+
+Under the default persistence policy, these `running` checkpoints are only written when crash recovery is enabled. With `recovery.durableAgents: 'off'` (the default), durable agents persist snapshots only for `pending`, `paused`, and `suspended` runs (the artifacts human-in-the-loop resume depends on) and skip the per-step `running` writes entirely. A custom `shouldPersistSnapshot` predicate can keep `running` checkpoints even with recovery off. See [snapshot persistence](#snapshot-persistence) for the full policy and how to override it.
 
 Durable agent runs are excluded from the generic boot-time restart of active workflow runs. The only automatic recovery path for durable agent runs is `recovery.durableAgents: 'auto'`, which holds a recovery lease and registers thread runtimes before re-driving each run.
 
+### Snapshot persistence
+
+The `shouldPersistSnapshot` option on `createDurableAgent()` (also accepted in the agent-level `durable` config) controls which workflow snapshots a durable agent writes. The default policy:
+
+- Always persists `pending`, `paused`, and `suspended` snapshots. These are what `resume()` and tool approval read, so human-in-the-loop flows work without configuration.
+- Persists `running` checkpoints only when `recovery.durableAgents` is `'auto'`. These per-step writes exist solely to make in-flight runs recoverable after a crash, so they're skipped when nothing consumes them.
+
+To keep crash-recovery checkpoints without enabling automatic recovery (for example, when you call `recoverActiveRuns()` yourself behind a leader election), pass a predicate that includes `running`:
+
+```typescript
+export const durableResearcher = createDurableAgent({
+  agent,
+  shouldPersistSnapshot: ({ workflowStatus }) =>
+    ['pending', 'paused', 'suspended', 'running'].includes(workflowStatus),
+})
+```
+
+Mastra logs a warning when a custom predicate excludes `suspended` or `paused`, which breaks human-in-the-loop resume, or excludes `running` while `recovery.durableAgents` is `'auto'`, which makes the agent invisible to automatic recovery.
+
+Evented agents always persist the full snapshot set: the evented engine coordinates workers through storage, so the `running` row is part of its execution model. Inngest agents always persist only `suspended` snapshots, because Inngest's own replay provides durability. Both accept `shouldPersistSnapshot` for API symmetry but log a warning and ignore it.
+
 ### Automatic recovery
 
 Set `recovery.durableAgents` to `'auto'` in the Mastra config. The deployer calls `recoverAllDurableAgents()` on boot, right after restarting active workflow runs:
@@ -290,6 +313,8 @@ const agentResult = await durableAgent.recoverActiveRuns()
 await durableAgent.recoverActiveRuns({ runId: 'run-abc-123' })
 ```
 
+Manual recovery reads the same `running` checkpoints as automatic recovery. If `recovery.durableAgents` is `'off'` and you haven't set a custom `shouldPersistSnapshot` that includes `running`, in-flight runs are never checkpointed, so `listActiveRuns()` and `recoverActiveRuns()` find nothing after a crash. See [snapshot persistence](#snapshot-persistence).
+
 ### Multi-instance deployments
 
 Mastra doesn't provide a distributed lease or lock yet. In multi-replica deployments, every replica that starts with `recovery.durableAgents: 'auto'` will race to recover the same runs. For now, either gate recovery behind your own leader election or run it from a single replica.

package/.docs/integrations/observability/opentelemetry.md

@@ -571,11 +571,14 @@ The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](http
 
 #### Span Naming
 
-- **LLM Operations**: `chat {model}`
+- **Model calls**: `chat {model}`
+- **Generation loop**: `model_generation {model}`, with one `agent_step {agent_id}` per turn
 - **Tool Execution**: `execute_tool {tool_name}`
 - **Agent Runs**: `invoke_agent {agent_id}`
 - **Workflow Runs**: `invoke_workflow {workflow_id}`
 
+Each agent turn calls the model once. The `chat` span is that call and is the only span that carries `gen_ai.request.model`, the messages, and `gen_ai.usage.*`, so backends that sum usage across spans count each call once. The `model_generation` span wraps the whole loop and `agent_step` wraps one turn (model call plus tool execution); neither carries usage.
+
 #### Key Attributes
 
 - `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
@@ -805,10 +808,13 @@ With the `OtelBridge`, your traces maintain proper hierarchy across OTEL and Mas
 ```text
 HTTP POST /api/chat (from Hono middleware)
 └── agent.assistant (from Mastra via OtelBridge)
-    ├── chat gpt-5.4 (LLM call)
-    ├── tool.execute search (tool execution)
-    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
-    └── chat gpt-5.4 (follow-up LLM call)
+    └── model_generation gpt-5 (generation loop)
+        ├── agent_step assistant (turn 1)
+        │   ├── chat gpt-5 (LLM call)
+        │   └── execute_tool search (tool execution)
+        │       └── HTTP GET api.example.com (from OTEL auto-instrumentation)
+        └── agent_step assistant (turn 2)
+            └── chat gpt-5 (follow-up LLM call)
 ```
 
 ### Multi-service distributed tracing
@@ -821,7 +827,9 @@ Service A: HTTP POST /api/process
 
 Service B: HTTP POST /api/analyze (incoming call - same trace!)
 └── agent.analyzer (Mastra agent inherits trace context)
-    └── chat gpt-5.4
+    └── model_generation gpt-5
+        └── agent_step analyzer
+            └── chat gpt-5
 ```
 
 Both services must have:

package/.docs/models/index.md

@@ -4,7 +4,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7315 models from 204 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7314 models from 204 providers through a single API.
 
 ## Features
 

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

@@ -4,7 +4,7 @@
 
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 580 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 579 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -113,7 +113,6 @@ for await (const chunk of stream) {
 | `nano-gpt/claw-medium`                                           | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/cohere/command-r-plus-08-2024`                         | 128K    |       |           |       |       |       | $3         | $14         |
 | `nano-gpt/command-a-reasoning-08-2025`                           | 256K    |       |           |       |       |       | $3         | $10         |
-| `nano-gpt/deepclaude`                                            | 128K    |       |           |       |       |       | $3         | $15         |
 | `nano-gpt/deepcogito/cogito-v1-preview-qwen-32B`                 | 128K    |       |           |       |       |       | $2         | $2          |
 | `nano-gpt/deepseek-ai/DeepSeek-R1-0528`                          | 164K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/deepseek-ai/DeepSeek-V3.1`                             | 128K    |       |           |       |       |       | $0.20      | $0.70       |

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

@@ -43,7 +43,7 @@ cleanup()
 
 ### Using the `durable` config flag
 
-Set `durable: true` on `AgentConfig` and the agent is automatically wrapped with `createDurableAgent` when it's attached to a `Mastra` instance. Use an object to forward advanced options such as `cache`, `pubsub`, `maxSteps`, `cleanupTimeoutMs`, or `shouldCache`.
+Set `durable: true` on `AgentConfig` and the agent is automatically wrapped with `createDurableAgent` when it's attached to a `Mastra` instance. Use an object to forward advanced options such as `cache`, `pubsub`, `maxSteps`, `cleanupTimeoutMs`, `shouldCache`, or `shouldPersistSnapshot`.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -92,6 +92,8 @@ Returns: `DurableAgent`
 
 **shouldCache** (`(topic: string) => boolean`): Per-topic opt-out of the replay cache. Return false to publish a topic straight to the underlying PubSub without recording it; subscribers of that topic receive live events only and cannot resume from an offset. Useful for trading replay for minimum publish latency on hot topics when the cache is remote (for example, cross-region Redis). Run-local topics are always excluded, regardless of this option.
 
+**shouldPersistSnapshot** (`(params: { stepResults, workflowStatus }) => boolean`): Predicate controlling which workflow snapshots the durable run persists. The default always persists pending, paused, and suspended (required for human-in-the-loop resume) and persists running checkpoints only when the Mastra instance is configured with recovery.durableAgents: 'auto'. Pass a predicate that includes running to keep crash-recovery checkpoints for manual listActiveRuns() / recoverActiveRuns() without enabling automatic recovery. Mastra logs a warning when a predicate excludes suspended or paused, or excludes running while recovery.durableAgents is 'auto'.
+
 ## `createEventedAgent(options)`
 
 Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It doesn't accept `id` or `name` overrides.
@@ -116,6 +118,8 @@ Returns: `EventedAgent` (a subclass of `DurableAgent`)
 
 **shouldCache** (`(topic: string) => boolean`): Per-topic opt-out of the replay cache. Return false to publish a topic straight to the underlying PubSub without recording it; subscribers of that topic receive live events only and cannot resume from an offset. Useful for trading replay for minimum publish latency on hot topics when the cache is remote (for example, cross-region Redis). Run-local topics are always excluded, regardless of this option.
 
+**shouldPersistSnapshot** (`(params: { stepResults, workflowStatus }) => boolean`): Accepted for API symmetry with createDurableAgent, but ignored: the evented engine requires the full snapshot set (pending, paused, suspended, running) because the initial running write creates the base row that suspend-merges and multi-worker coordination build on. A warning is logged if set.
+
 ## Constructor parameters
 
 The `DurableAgent` class accepts the same options as `createDurableAgent`, plus `cleanupTimeoutMs`. Prefer the factory unless you need to subclass.
@@ -134,6 +138,8 @@ The `DurableAgent` class accepts the same options as `createDurableAgent`, plus
 
 **shouldCache** (`(topic: string) => boolean`): Per-topic opt-out of the replay cache. Return false to publish a topic straight to the underlying PubSub without recording it; subscribers of that topic receive live events only and cannot resume from an offset. Useful for trading replay for minimum publish latency on hot topics when the cache is remote (for example, cross-region Redis). Run-local topics are always excluded, regardless of this option.
 
+**shouldPersistSnapshot** (`(params: { stepResults, workflowStatus }) => boolean`): Predicate controlling which workflow snapshots the durable run persists. The default always persists pending, paused, and suspended (required for human-in-the-loop resume) and persists running checkpoints only when the Mastra instance is configured with recovery.durableAgents: 'auto'.
+
 **cleanupTimeoutMs** (`number`): Grace period in milliseconds before registry entries are cleaned up automatically after a stream finishes or errors. Set to 0 to disable auto-cleanup and require a manual cleanup() call. Auto-cleanup does not fire on suspended events. (Default: `30000`)
 
 ## Methods
@@ -260,6 +266,8 @@ Returns: `boolean`. `false` when this process has no active run recorded for the
 
 Lists this agent's runs whose persisted snapshot is in `running` status: runs whose agentic loop was mid-execution when the workflow engine last saved state. On a live process they transition to `suspended` or a terminal status. After a crash or restart they stay `running` with nothing driving them, which is what `recoverActiveRuns()` re-drives. Runs started by other durable agents on the same storage aren't included.
 
+`running` snapshots are only written when `recovery.durableAgents` is `'auto'` or a custom `shouldPersistSnapshot` includes `running`. Without one of those, this method returns no runs. See [snapshot persistence](https://mastra.ai/docs/harness/durable-agents).
+
 ```typescript
 const { runs, total } = await durableAgent.listActiveRuns({ resourceId: 'user-1' })
 

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

@@ -83,6 +83,8 @@ Returns: [`InngestAgent`](#inngestagent-interface)
 
 **mastra** (`Mastra`): Mastra instance for observability. Set automatically when the agent is registered with Mastra.
 
+**shouldPersistSnapshot** (`(params: { stepResults, workflowStatus }) => boolean`): Accepted for API symmetry with createDurableAgent, but ignored: Inngest's step memoization and replay own durability, so InngestAgent always persists suspended snapshots only (for human-in-the-loop resume). A warning is logged if set.
+
 ## `InngestAgent` interface
 
 The object returned by `createInngestAgent()`. It provides the durable execution methods below. Any property or method not explicitly defined (e.g., `listTools()` and `getMemory()`) is forwarded to the underlying agent via a Proxy. Thread APIs such as `sendSignal()`, `sendStateSignal()`, `sendNotificationSignal()`, and `subscribeToThread()` are forwarded too, but a signal that wakes an idle thread starts the run through the durable `stream()`.

package/.docs/reference/core/mastra-class.md

@@ -131,7 +131,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **recovery** (`MastraRecoveryConfig`): Boot-time recovery behavior for orphaned agent and workflow runs. See Crash recovery. (Default: `{ durableAgents: 'off' }`)
 
-**recovery.durableAgents** (`'auto' | 'off'`): Set to 'auto' to automatically re-drive orphaned RUNNING durable agent runs on server boot. Recovery re-issues LLM calls and re-executes tool calls, so tools must be idempotent. See Crash recovery.
+**recovery.durableAgents** (`'auto' | 'off'`): Set to 'auto' to automatically re-drive orphaned RUNNING durable agent runs on server boot. This also controls the default snapshot-persistence policy for durable agents: running checkpoints are only written when set to 'auto' (or when an agent sets a custom shouldPersistSnapshot that includes running). Recovery re-issues LLM calls and re-executes tool calls, so tools must be idempotent. See Crash recovery.
 
 ## Methods
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.26",
+  "version": "1.2.27-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.18.0",
-    "@mastra/core": "1.67.0"
+    "@mastra/core": "1.68.0-alpha.0",
+    "@mastra/mcp": "^1.18.0"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -44,9 +44,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
+    "@internal/lint": "0.0.133",
     "@internal/types-builder": "0.0.108",
-    "@mastra/core": "1.67.0",
-    "@internal/lint": "0.0.133"
+    "@mastra/core": "1.68.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {