@mastra/mcp-docs-server 1.3.6-alpha.9 → 1.3.7-alpha.1

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

@@ -131,10 +131,14 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **scheduler.enabled** (`boolean`): Explicitly enable or disable the scheduler.
 
-**recovery** (`MastraRecoveryConfig`): Boot-time recovery behavior for orphaned agent and workflow runs. See Crash recovery. (Default: `{ durableAgents: 'off' }`)
+**recovery** (`MastraRecoveryConfig`): Boot-time recovery behavior for orphaned agent and workflow runs. See Crash recovery. (Default: `{ durableAgents: 'off', workflows: 'auto', workflowConcurrency: 5 }`)
 
 **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.
 
+**recovery.workflows** (`'auto' | 'off'`): Set to 'off' to skip restarting active workflow runs on server boot. Individual workflows can also opt out with autoRestartActiveRuns: false.
+
+**recovery.workflowConcurrency** (`number`): Maximum number of workflow runs restarted at the same time during boot recovery. Use Infinity for no limit. Workflow and durable agent recovery run in parallel.
+
 ## Methods
 
 ### `recoverAllDurableAgents()`
@@ -143,17 +147,21 @@ Re-drives every orphaned `running` durable-agent run across all registered durab
 
 Requires persistent storage. With an in-memory store, there's nothing to recover after a process restart.
 
+A run that another execution still drives isn't taken over. It's counted in `skipped` and checked again once that execution's claim could have lapsed, so a run whose process crashed is recovered without another call. `shutdown()` cancels pending re-checks. See [run ownership](https://mastra.ai/docs/harness/durable-agents).
+
 ```typescript
 const result = await mastra.recoverAllDurableAgents()
-// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }
+// { agents: 2, recovered: 3, succeeded: 3, failed: 0, skipped: 1 }
 ```
 
 Returns:
 
 **agents** (`number`): Number of durable agents scanned.
 
-**recovered** (`number`): Total number of runs that were re-driven.
+**recovered** (`number`): Total number of runs that were re-driven: succeeded plus failed.
 
 **succeeded** (`number`): Runs that restarted successfully.
 
-**failed** (`number`): Runs whose restart threw an error.
+**failed** (`number`): Runs whose restart threw an error.
+
+**skipped** (`number`): Runs that another execution still drives. Each is checked again later.

package/.docs/reference/memory/observational-memory.md

@@ -99,7 +99,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
 
-**observation.blockAfter** (`number`): Safety net for when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 resolves to 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Above this point, activation uses the smallest set of buffered chunks that reaches the retention target, even when that overshoots the target by more than the usual safeguard allows. It never activates more chunks than are needed to reach the retention target, so it removes only slightly more history than a normal activation. It changes the result only when the retention floor is above roughly 20,000 tokens; with the default bufferActivation (a 6k floor) it has no observable effect. Activation usually keeps a minimum remaining context (the smaller of 1000 tokens or the retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less. Crossing blockAfter does not trigger a blocking observation. A synchronous (blocking) observation runs when the messageTokens threshold is reached and activating buffered chunks doesn't bring pending tokens back under it, for example when a large tool result arrives after buffering has stopped. All remaining buffered chunks are activated first, so the synchronous observation only covers messages no chunk has observed. Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net for when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 resolves to 120% of the threshold (36k tokens with the default 30k). Multipliers apply to a per-thread messageTokens override when one is set. Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run: reaching the threshold without a buffered chunk to activate starts background buffering, and the chunk activates on a later step. A synchronous (blocking) observation runs if pending tokens still reach blockAfter after buffered activation. All remaining buffered chunks are activated first, so the synchronous observation only covers messages no chunk has observed. Set blockAfter: 1 to observe synchronously at messageTokens. Above this point, activation also uses the smallest set of buffered chunks that reaches the retention target, even when that overshoots the target by more than the usual safeguard allows. It never activates more chunks than are needed to reach the retention target, so it removes only slightly more history than a normal activation. It changes the result only when the retention floor is above roughly 20,000 tokens; with the default bufferActivation (a 6k floor) it has no observable effect. Activation usually keeps a minimum remaining context (the smaller of 1000 tokens or the retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less. Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
@@ -371,7 +371,7 @@ export const agent = new Agent({
 
 Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals and produce chunks of observations. At the threshold, activation moves observations into the log and removes raw messages from context. Above `blockAfter`, activation may overshoot the retention target instead of activating fewer chunks. A synchronous observation runs if pending tokens are still at or above the threshold after all buffered chunks have been activated.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals and produce chunks of observations. At the threshold, activation moves observations into the log and removes raw messages from context. Between the threshold and `blockAfter`, buffering continues in the background and the next ready chunk activates on a later step. A synchronous observation runs if pending tokens still reach `blockAfter` after all buffered chunks have been activated. Above `blockAfter`, activation may also overshoot the retention target instead of activating fewer chunks.
 
 Default settings:
 
@@ -402,7 +402,7 @@ export const agent = new Agent({
           bufferTokens: 5_000,
           // Activate to retain 30% of threshold
           bufferActivation: 0.7,
-          // Above 1.5x the threshold, let activation overshoot the retention target
+          // Observe synchronously at 1.5x the threshold if no buffered chunk is ready
           blockAfter: 1.5,
         },
         reflection: {

package/.docs/reference/pubsub/lease-provider.md

@@ -6,6 +6,8 @@
 
 `LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/harness/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
 
+[Durable agents](https://mastra.ai/docs/harness/durable-agents) also claim each run through a lease when the workflows store doesn't support run fencing, so crash recovery can tell whether another process still drives the run.
+
 Leasing is separate from pub/sub. A `LeaseProvider` implementation needs actual lock coordination, whether through an atomic Redis operation such as `SET` or Lua or through an in-memory map for a single process. For backends that omit leasing, the signals runtime preserves single-process behavior with a no-op provider.
 
 The built-in [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) implements `LeaseProvider`, which is what enables signals to coordinate across instances in distributed and serverless deployments.

package/.docs/reference/pubsub/valkey-streams.md

@@ -49,7 +49,7 @@ export const mastra = new Mastra({
 
 ## Constructor parameters
 
-**url** (`string`): Valkey connection URL. Falls back to valkeyOptions.url. (Default: `valkey://localhost:6379`)
+**url** (`string`): Valkey connection URL. Falls back to valkeyOptions.url. rediss\:// and valkeys\:// URLs enable TLS unless valkeyOptions.useTLS is set. (Default: `valkey://localhost:6379`)
 
 **valkeyOptions** (`ValkeyClientOptions`): GLIDE connection options, including native client configuration.
 

package/.docs/reference/server/routes.md

@@ -405,6 +405,7 @@ On authenticated servers, the read routes require the `stored-workflows:read` pe
 | `POST`   | `/api/datasets/:datasetId/items`                                       | Add a dataset item                                                                          |
 | `DELETE` | `/api/datasets/:datasetId/items/:itemId/purge`                         | Permanently scrub an item's content from every dataset version and linked experiment result |
 | `GET`    | `/api/experiments`                                                     | List experiments across datasets                                                            |
+| `GET`    | `/api/experiments/:experimentId`                                       | Get an experiment by ID without knowing its dataset                                         |
 | `DELETE` | `/api/experiments/:experimentId`                                       | Delete an experiment, including one orphaned by dataset deletion                            |
 | `GET`    | `/api/datasets/:datasetId/experiments`                                 | List experiments for a dataset                                                              |
 | `POST`   | `/api/datasets/:datasetId/experiments`                                 | Trigger an experiment, or create one without starting it (`start: false`)                   |

package/.docs/reference/storage/retention.md

@@ -95,29 +95,32 @@ Set the `retention` field on the store config.
 
 Each domain specifies its age-prunable tables and the timestamp column that anchors comparison, chosen so `maxAge` matches the meaning of the data. Append-only logs use creation time, live state uses last activity, and jobs or runs use completion time so in-flight work isn't pruned.
 
-| Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
-| ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
-| `memory`          | `threads`          | `createdAt`      | Thread age                                                       |
-| `memory`          | `messages`         | `createdAt`      | Message age                                                      |
-| `memory`          | `resources`        | `createdAt`      | Resource age                                                     |
-| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives              |
-| `observability`   | `spans`            | `startedAt`      | Span age                                                         |
-| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                    |
-| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                       |
-| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                     |
-| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                  |
-| `scores`          | `scorers`          | `createdAt`      | Score record age                                                 |
-| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive          |
-| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned |
-| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned      |
-| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                 |
-| `harness`         | `sessions`         | `createdAt`      | Session record age                                               |
-| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                               |
+| Domain            | Table key          | Anchor column    | `maxAge` measures                                                                                                                |
+| ----------------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `memory`          | `threads`          | `createdAt`      | Thread age                                                                                                                       |
+| `memory`          | `messages`         | `createdAt`      | Message age                                                                                                                      |
+| `memory`          | `resources`        | `createdAt`      | Resource age                                                                                                                     |
+| `memory`          | `runFences`        | `retiredAt`      | Time since the durable agent execution holding the fence settled. Fences of running executions (`NULL`) are never pruned         |
+| `threadState`     | `threadState`      | `updatedAt`      | Inactivity: state for still-active threads survives                                                                              |
+| `observability`   | `spans`            | `startedAt`      | Span age                                                                                                                         |
+| `observability`   | `metrics`          | `timestamp`      | Metric event age (vNext only)                                                                                                    |
+| `observability`   | `logs`             | `timestamp`      | Log event age (vNext only)                                                                                                       |
+| `observability`   | `scores`           | `timestamp`      | Score event age (vNext only)                                                                                                     |
+| `observability`   | `feedback`         | `timestamp`      | Feedback event age (vNext only)                                                                                                  |
+| `scores`          | `scorers`          | `createdAt`      | Score record age                                                                                                                 |
+| `workflows`       | `workflowSnapshot` | `updatedAt`      | Inactivity, suspended or long-running workflows survive                                                                          |
+| `workflows`       | `runOwnership`     | `updatedAt`      | Inactivity. A running durable agent execution renews its claim every 10 seconds, so keep `maxAge` well above its 30-second lease |
+| `backgroundTasks` | `backgroundTasks`  | `completedAt`    | Time since completion, in-flight tasks (`NULL`) are never pruned                                                                 |
+| `experiments`     | `experiments`      | `completedAt`    | Time since completion, running experiments are never pruned                                                                      |
+| `notifications`   | `notifications`    | `createdAt`      | Notification age                                                                                                                 |
+| `harness`         | `sessions`         | `createdAt`      | Session record age                                                                                                               |
+| `schedules`       | `triggers`         | `actual_fire_at` | Fire-history age (epoch-ms column)                                                                                               |
 
 > **Note:**
 >
 > - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
+> - `runOwnership` and `runFences` hold the run fencing records of durable agents, one small record per run in each. If the `runOwnership` `maxAge` is too short, a running execution can lose its run, but an execution that lost a run still can't write. A fence is retired only when its execution settles, so the fence of a run that crashed and was never recovered is never pruned.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
 > - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.

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

@@ -17,6 +17,7 @@ constructor({
   id?: string;
   servers: Record<string, MastraMCPServerDefinition>;
   timeout?: number;
+  clientInfo?: { name?: string; version?: string };
 }: MCPClientOptions)
 ```
 
@@ -28,6 +29,8 @@ constructor({
 
 **timeout** (`number`): Global timeout value in milliseconds for all servers unless overridden in individual server configs. (Default: `60000`)
 
+**clientInfo** (`{ name?: string; version?: string }`): Client name and version every server receives on connect and with each request, so servers can attribute traffic to your application. Defaults to the server key as name and '1.0.0' as version. Individual server configs can override either field with their own clientInfo. Doesn't change tool name prefixes, which always use the server key.
+
 ### `MastraMCPServerDefinition`
 
 Each server in the `servers` map is configured using the `MastraMCPServerDefinition` type. The transport type is detected based on the provided parameters:
@@ -59,6 +62,8 @@ The client speaks the MCP `2026-07-28` revision. On connect it asks the server w
 
 **timeout** (`number`): Server-specific timeout in milliseconds. Falls back to the client-level timeout when omitted.
 
+**clientInfo** (`{ name?: string; version?: string }`): Overrides the top-level clientInfo for this server. Fields you set replace the top-level values; fields you omit keep them.
+
 **capabilities** (`MCPClientCapabilities`): Client capabilities to advertise: elicitation and extensions. elicitation is only accepted together with an inputRequests handler and defaults to form support when a handler is configured. Roots and sampling are not supported.
 
 **inputRequests** (`MCPInputRequestHandler`): Answers input requests from this server. When a tool, resource or prompt call ends as input\_required, the handler is called with each embedded request and the client retries the call with the answers. Without a handler an input\_required result surfaces as an error. See Answering input requests below.

package/.docs/reference/workspace/platform-sandbox.md

@@ -123,10 +123,21 @@ const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
 
 When `sandboxId` is set, `environmentId` isn't required because the sandbox already exists.
 
-Read the platform's id for the running sandbox from the `sandboxId` property after `start()` and persist it for the next reattach. The property is `undefined` until the sandbox has started in the current process. The option passed to the constructor is a hint for `start()`. Before `start()` runs, `getInfo()` answers from local state and doesn't ask the platform about the hint. If the platform no longer knows the id, `start()` falls through to a fresh provision keyed by the sandbox's logical `id`. That fallback needs `environmentId` (or `MASTRA_ENVIRONMENT_ID`), so pass it whenever a hint might be stale; without it, `start()` throws `environmentId is required`.
+Read the platform's id for the running sandbox from the `sandboxId` property after `start()` and persist it for the next reattach. The property is `undefined` until the sandbox has started in the current process. The option passed to the constructor is a hint for `start()`. Before `start()` runs, `getInfo()` answers from local state and doesn't ask the platform about the hint. Under the default `reattach: 'best-effort'`, if the platform no longer knows the id, `start()` falls through to a fresh provision keyed by the sandbox's logical `id`. That fallback needs `environmentId` (or `MASTRA_ENVIRONMENT_ID`), so pass it whenever a hint might be stale; without it, `start()` throws `environmentId is required`.
 
 `start()` reports `{ outcome: 'connected' }` on reattach and `{ outcome: 'created' }` on a fresh provision (including a checkpoint-recovered boot, which is a new VM even when its filesystem was restored). See [`start()`](https://mastra.ai/reference/workspace/sandbox) for the shared contract.
 
+When a fresh sandbox would silently lose state your app depends on, set `reattach: 'required'`:
+
+```typescript
+const sandbox = new PlatformSandbox({
+  sandboxId: 'sbx_abc123',
+  reattach: 'required',
+})
+```
+
+With `reattach: 'required'`, a reattach target the platform reports as missing (404), gone (410), or destroyed rejects `start()` with a `SandboxError` whose `code` is `SANDBOX_REATTACH_FAILED`, and no sandbox is provisioned. The error's `details` include `provider`, `sandboxId`, `logicalId` (the sandbox's logical `id`), and `reason`. Other errors propagate unchanged. To start fresh, clear your persisted `sandboxId` and construct the sandbox without it. Clones inherit the `reattach` setting.
+
 ### Reusable templates
 
 Pass a reusable template builder to `PlatformSandbox`. A fresh sandbox start sends the serialized definition to Platform, which content-addresses it and starts or reuses the provider build. Sandbox creation never blocks on a build. When the exact template isn't built yet, Platform boots the sandbox on the best available fallback and rebuilds the requested template in the background. The fallback is a same-lineage stale template with matching resources when one exists, otherwise the provider base template:
@@ -315,6 +326,8 @@ console.log(result.exitCode)
 
 **sandboxId** (`string`): Existing sandbox ID to reattach to instead of creating a new sandbox. When set, environmentId is not required.
 
+**reattach** (`'best-effort' | 'required'`): What start() does when sandboxId is set but the platform reports that sandbox as missing, gone, or destroyed. 'best-effort' provisions a fresh sandbox. 'required' throws a SandboxError with code SANDBOX\_REATTACH\_FAILED instead of provisioning. (Default: `'best-effort'`)
+
 **seedCheckpointName** (`string`): Boot-only fallback checkpoint used when the primary recovery checkpoint for id has no stored state. Later snapshots continue writing to the checkpoint for id.
 
 **template** (`SandboxTemplateBuilder | (() => SandboxTemplateBuilder | undefined | Promise<SandboxTemplateBuilder | undefined>)`): Reusable template builder or lazy resolver used during a fresh sandbox provision. Resolver and provider build failures fall back to the selected provider default.
@@ -351,7 +364,7 @@ console.log(result.exitCode)
 
 ## Methods
 
-**start** (`() => Promise<SandboxStartResult>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
+**start** (`() => Promise<SandboxStartResult>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision under the default reattach: 'best-effort', and throws SANDBOX\_REATTACH\_FAILED under reattach: 'required'.
 
 **destroy** (`() => Promise<void>`): Tear down the remote sandbox and clear the cached exec lease. A subsequent start() provisions a fresh sandbox (or restores from checkpoint when a stable id is set).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.6-alpha.9",
+  "version": "1.3.7-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,8 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.76.0-alpha.4",
-    "@mastra/mcp": "^2.2.1-alpha.0"
+    "@mastra/mcp": "^2.3.0",
+    "@mastra/core": "1.77.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -43,9 +43,9 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
-    "@internal/lint": "0.0.141",
-    "@internal/types-builder": "0.0.116",
-    "@mastra/core": "1.76.0-alpha.4"
+    "@internal/types-builder": "0.0.117",
+    "@internal/lint": "0.0.142",
+    "@mastra/core": "1.77.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {