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

package/.docs/reference/index.md

@@ -92,6 +92,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listScorers()](https://mastra.ai/reference/core/listScorers)
 - [.listVectors()](https://mastra.ai/reference/core/listVectors)
 - [.listWorkflows()](https://mastra.ai/reference/core/listWorkflows)
+- [.removeWorkspace()](https://mastra.ai/reference/core/removeWorkspace)
 - [.setLogger()](https://mastra.ai/reference/core/setLogger)
 - [.setStorage()](https://mastra.ai/reference/core/setStorage)
 - [Cloudflare](https://mastra.ai/reference/deployer/cloudflare)
@@ -127,6 +128,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Keyword Coverage Scorer](https://mastra.ai/reference/evals/keyword-coverage)
 - [Noise Sensitivity Scorer](https://mastra.ai/reference/evals/noise-sensitivity)
 - [Prompt Alignment Scorer](https://mastra.ai/reference/evals/prompt-alignment)
+- [Rubric Scorer](https://mastra.ai/reference/evals/rubric)
 - [Textual Difference Scorer](https://mastra.ai/reference/evals/textual-difference)
 - [Tone Consistency Scorer](https://mastra.ai/reference/evals/tone-consistency)
 - [Tool Call Accuracy Scorers](https://mastra.ai/reference/evals/tool-call-accuracy)
@@ -222,6 +224,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [createNotificationInboxTool()](https://mastra.ai/reference/signals/create-notification-inbox-tool)
 - [SignalProvider](https://mastra.ai/reference/signals/signal-provider)
+- [TaskSignalProvider](https://mastra.ai/reference/signals/task-signal-provider)
 - [WebhookSignalProvider](https://mastra.ai/reference/signals/webhook-signal-provider)
 - [Overview](https://mastra.ai/reference/storage/overview)
 - [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
@@ -251,6 +254,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
@@ -341,6 +345,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
+- [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)
 - [SandboxProcessManager](https://mastra.ai/reference/workspace/process-manager)
 - [VercelMicroVMSandbox](https://mastra.ai/reference/workspace/vercel-microvm-sandbox)

package/.docs/reference/memory/serialized-memory-config.md

@@ -2,7 +2,7 @@
 
 `SerializedMemoryConfig` is the JSON-serializable subset of [`Memory`](https://mastra.ai/reference/memory/memory-class) configuration that lives on a stored agent record. The runtime hydrates it back into a `Memory` instance by resolving the vector and embedder IDs against the configured `Mastra` instance.
 
-It is the type used by [`BuilderAgentDefaults.memory`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
+It's the type used by [`BuilderAgentDefaults.memory`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by `EditorAgentNamespace.create({ memory })`.
 
 ## Usage example
 

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -15,7 +15,7 @@ Two conditions must be true for a metric to reach storage:
 1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse or DuckDB).
 
-If metrics aren't appearing, see [troubleshooting](#troubleshooting).
+If metrics aren't available, see [troubleshooting](#troubleshooting).
 
 ## Duration metrics
 
@@ -112,11 +112,11 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 
 ## Troubleshooting
 
-### No metrics are appearing
+### No metrics are available
 
 - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
 - **`MastraStorageExporter` or `MastraPlatformExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. `MastraStorageExporter` is required for the local Studio dashboard, and `MastraPlatformExporter` is required to view metrics in Mastra platform.
-- **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) are not supported for metrics.
+- **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) aren't supported for metrics.
 - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
 
 ### Duration metrics are missing

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -121,7 +121,7 @@ new DatadogBridge({
 })
 ```
 
-Note: APM data cannot be sent in agentless mode. If you only need LLM Observability data without `dd-trace` APM, the [Datadog Exporter](https://mastra.ai/reference/observability/tracing/exporters/datadog) is a simpler choice.
+Note: APM data can't be sent in agentless mode. If you only need LLM Observability data without `dd-trace` APM, the [Datadog Exporter](https://mastra.ai/reference/observability/tracing/exporters/datadog) is a simpler choice.
 
 ### With Additional Exporters
 

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -104,7 +104,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for Cloud export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `CloudExporter`; the exporter forwards every metric event it receives unless it is disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the Cloud metrics endpoint derived from the configured base endpoint. Additional filtering by metric subtype or status inside `CloudExporter` isn't performed; the exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -116,7 +116,7 @@ async onScoreEvent(event: ScoreEvent): Promise<void>
 
 Processes score signals for Cloud export.
 
-Every `ScoreEvent` passed to this handler is buffered and exported to the Cloud scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+Every `ScoreEvent` passed to this handler is buffered and exported to the Cloud scores endpoint derived from the configured base endpoint. No extra filtering at the exporter layer beyond the disabled-exporter check is performed, so all score events received by this method are forwarded.
 
 **Returns:** `Promise<void>` after the score event has been accepted for buffering.
 
@@ -128,7 +128,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for Cloud export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `CloudExporter`; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the Cloud feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `CloudExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -132,7 +132,7 @@ Failed flushes are retried with exponential backoff:
 - Maximum attempts: `maxRetries`
 - Batch is dropped after all retries fail
 
-When storage does not support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
+When storage doesn't support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
 
 ### Out-of-Order Handling
 

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -4,7 +4,7 @@
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
-> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it's deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.
 
 ## Constructor
 
@@ -106,7 +106,7 @@ async onMetricEvent(event: MetricEvent): Promise<void>
 
 Processes metric signals for export.
 
-Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `MastraPlatformExporter`; the exporter forwards every metric event it receives unless it is disabled.
+Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. No additional filtering by metric subtype or status inside `MastraPlatformExporter` is performed; the exporter forwards every metric event it receives unless it's disabled.
 
 **Returns:** `Promise<void>` after the metric event has been accepted for buffering.
 
@@ -118,7 +118,7 @@ async onScoreEvent(event: ScoreEvent): Promise<void>
 
 Processes score signals for export.
 
-Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. No extra filtering at the exporter layer beyond the disabled-exporter check is performed, so all score events received by this method are forwarded.
 
 **Returns:** `Promise<void>` after the score event has been accepted for buffering.
 
@@ -130,7 +130,7 @@ async onFeedbackEvent(event: FeedbackEvent): Promise<void>
 
 Processes feedback signals for export.
 
-Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `MastraPlatformExporter`; all feedback events received here are forwarded unless the exporter is disabled.
+Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. No feedback-type filtering inside `MastraPlatformExporter` is performed; all feedback events received here are forwarded unless the exporter is disabled.
 
 **Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
 
@@ -190,7 +190,7 @@ Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `
 
 ## Span wire format
 
-The shape of each span sent to Mastra platform is documented here for reference only — it is not exported from `@mastra/observability` and should not be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
+The shape of each span sent to Mastra platform is documented here for reference only — it's not exported from `@mastra/observability` and shouldn't be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
 
 ```typescript
 type MastraPlatformSpanRecord = AnyExportedSpan & {

package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md

@@ -2,7 +2,7 @@
 
 Persists traces to Mastra's configured storage with automatic batching and retry logic.
 
-> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
+> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it's deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
 
 ## Constructor
 

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -161,7 +161,7 @@ const exporter = new OtelExporter({
 
 ## Protocol requirements
 
-Different providers require different OTEL exporter packages. Trace and log export are independent: install only the trace package if you only need traces, or install both the trace and log packages for the chosen protocol if you also want log export. Zipkin does not support OTLP logs.
+Different providers require different OTEL exporter packages. Trace and log export are independent: install only the trace package if you only need traces, or install both the trace and log packages for the chosen protocol if you also want log export. Zipkin doesn't support OTLP logs.
 
 | Protocol      | Trace package                                                 | Log package                                                  |
 | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -4,7 +4,7 @@ A SpanOutputProcessor that redacts sensitive information from span fields.
 
 ## Auto-applied by default
 
-`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You do not need to add it manually unless you want to customize its options.
+`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You don't need to add it manually unless you want to customize its options.
 
 To opt out or customize the auto-applied filter, use the `sensitiveDataFilter` option on the [`Observability` registry config](https://mastra.ai/reference/observability/tracing/configuration):
 
@@ -22,7 +22,7 @@ new Observability({
 })
 ```
 
-If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values are not modified — add a `SensitiveDataFilter` to their processors yourself if needed.
+If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values aren't modified — add a `SensitiveDataFilter` to their processors yourself if needed.
 
 ## Constructor
 

package/.docs/reference/processors/cost-guard-processor.md

@@ -103,10 +103,10 @@ When the `block` strategy is active (default), `CostGuardProcessor` calls `abort
 | `resource` | Yes                | `resourceId` + time window  | `resourceId` in `RequestContext` |
 | `thread`   | Yes                | `threadId` + time window    | `threadId` in `RequestContext`   |
 
-All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance does not have observability storage configured, an error is thrown at registration time.
+All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance doesn't have observability storage configured, an error is thrown at registration time.
 
 For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
 
 For `resource` and `thread` scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, cost is treated as zero.
 
-> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. There is a short delay between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.
+> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. A short delay exists between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

package/.docs/reference/processors/processor-interface.md

@@ -369,7 +369,7 @@ System messages are **reset to their original values** at the start of each step
 
 Processes the final LLM request after Mastra converts the `MessageList` into `LanguageModelV2Prompt` and before the provider call. Use this method for transient, model-aware rewrites that should affect only the current outbound request.
 
-Returned prompt changes are forwarded to the model for the current call only. They are not persisted back to `MessageList`, memory, UI history, or later provider calls.
+Returned prompt changes are forwarded to the model for the current call only. They're not persisted back to `MessageList`, memory, UI history, or later provider calls.
 
 ```typescript
 processLLMRequest?(
@@ -892,8 +892,8 @@ export class WordCounter implements Processor {
 
 Every processor receives a `state` object in `processLLMRequest`, `processLLMResponse`, `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
 
-- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids cannot read or overwrite each other's state.
-- **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State does not leak between requests or between users.
+- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids can't read or overwrite each other's state.
+- **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State doesn't leak between requests or between users.
 - **Shared across methods**: Within one request, the same `state` object is passed to `processLLMRequest` (before the provider call), `processLLMResponse` (after the step completes), `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). For example, `processLLMRequest` can stash a cache key and `processLLMResponse` can read it back to write the response.
 
 Initialize fields defensively on first access, because `state` starts as an empty object:
@@ -957,7 +957,7 @@ await writer.custom({
 })
 ```
 
-By default, processors do **not** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
+By default, processors **don't** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
 
 ```typescript
 class ModerationCollector implements Processor {

package/.docs/reference/processors/response-cache.md

@@ -4,7 +4,7 @@
 
 The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
 
-There is no agent-level option for response caching; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+No agent-level option for response caching exists; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
 
 ## Usage example
 
@@ -85,7 +85,7 @@ The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
 
 **bust** (`boolean`): Skip the cache read but still write on completion.
 
-`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they are instance-level concerns that should not vary per request.
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they're instance-level concerns that shouldn't vary per request.
 
 ## ResponseCacheKeyInputs
 

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

@@ -4,7 +4,7 @@ The `SkillSearchProcessor` is an **input processor** that enables on-demand skil
 
 By default, when you attach only `SkillSearchProcessor` to an agent with a skill-enabled `Workspace`, the agent treats skills as on-demand:
 
-- The default eager `SkillsProcessor` is not auto-added.
+- The default eager `SkillsProcessor` isn't auto-added.
 - `search_skills` and `load_skill` are exposed for discovery and instruction loading.
 - Overlapping `skill` and `skill_search` tools are hidden.
 - `skill_read` remains available so the agent can read supporting skill files such as references, scripts, and assets.
@@ -90,11 +90,11 @@ The agent workflow is:
 
 ## Workspace file tools
 
-`SkillSearchProcessor` loads skill instructions into the conversation. It does not block workspace file tools from reading files.
+`SkillSearchProcessor` loads skill instructions into the conversation. It doesn't block workspace file tools from reading files.
 
 Use `skill_read` for supporting files that belong to a loaded skill, such as files under `references/`, `scripts/`, or `assets/`.
 
-Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent does not need to read the same `SKILL.md` file after `load_skill` succeeds.
+Reserve workspace file tools such as `mastra_workspace_read_file` for explicit file inspection or editing workflows. During normal task execution, the agent doesn't need to read the same `SKILL.md` file after `load_skill` succeeds.
 
 ## Compared to SkillsProcessor
 

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

@@ -27,13 +27,17 @@ const toolSearch = new ToolSearchProcessor({
 
 **options.tools** (`Record<string, Tool>`): All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.
 
-**options.search** (`{ topK?: number; minScore?: number }`): Configuration for the search behavior.
+**options.search** (`{ topK?: number; minScore?: number; autoLoad?: boolean }`): Configuration for the search behavior.
 
 **options.search.topK** (`number`): Maximum number of tools to return in search results.
 
 **options.search.minScore** (`number`): Minimum relevance score (0-1) for including a tool in search results.
 
-**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.search.autoLoad** (`boolean`): When true, tools returned by search\_tools are activated immediately as part of the search. The load\_tool meta-tool is not exposed, collapsing the two-step search then load flow into a single search step. Discovered tools become available on the next turn. Keep topK conservative since every match is activated.
+
+**options.storage** (`'in-memory' | 'context'`): Where loaded-tool state lives. 'in-memory' (default) tracks loaded tools in an in-memory map per thread with TTL cleanup (see ttl); state is lost on restart and anonymous requests share a 'default' entry. 'context' derives loaded state from the conversation messages — a tool is loaded while a search\_tools/load\_tool result naming it remains in the messages; it is restart-safe, requires no memory, and de-loads automatically once that result is no longer present in the messages. The 'context' store is opt-in.
+
+**options.ttl** (`number`): Time-to-live for in-memory thread state, in milliseconds. Only applies to the default storage: 'in-memory' store; after this duration of inactivity thread state is cleaned up. Set to 0 to disable cleanup. Ignored by the 'context' store.
 
 **options.filter** (`(args: ToolSearchFilterArgs) => boolean | Promise<boolean>`): Optional request-aware hook for hiding tools from search results, blocking tool loading, or hiding already-loaded tools for the current request.
 
@@ -45,6 +49,48 @@ const toolSearch = new ToolSearchProcessor({
 
 **processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes each step to inject search/load meta-tools and any previously loaded tools into the agent's tool set.
 
+## Methods
+
+### State inspection (legacy `'in-memory'` store)
+
+These methods operate on the default `'in-memory'` store only. They're no-ops for the `'context'` store, whose state lives in the conversation messages rather than an in-process map.
+
+#### `clearState(threadId)`
+
+Clears the loaded-tool state for a single thread.
+
+```typescript
+processor.clearState('thread-123')
+```
+
+#### `clearAllState()`
+
+Clears loaded-tool state for every thread.
+
+```typescript
+processor.clearAllState()
+```
+
+#### `getStateStats()`
+
+Returns the number of tracked threads and the oldest access time, for debugging in-memory growth.
+
+```typescript
+const { threadCount, oldestAccessTime } = processor.getStateStats()
+```
+
+Returns: `{ threadCount: number; oldestAccessTime: number | null }`
+
+#### `cleanupNow()`
+
+Immediately runs TTL cleanup instead of waiting for the scheduled sweep.
+
+```typescript
+const cleaned = processor.cleanupNow()
+```
+
+Returns: `number` — the count of threads cleaned up.
+
 ## Request-aware filtering
 
 Use `filter` to apply request-specific policy to dynamic tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
@@ -70,9 +116,9 @@ The `phase` value describes where the filter is being applied:
 
 - `search`: Filters results returned by `search_tools`.
 - `load`: Blocks `load_tool` from loading disallowed tools.
-- `active`: Hides already-loaded tools from the current request if they are no longer allowed.
+- `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The meta-tools `search_tools` and `load_tool` are always available. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available; `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
 
 ## Extended usage example
 
@@ -114,6 +160,64 @@ The agent workflow is:
 4. The loaded tool becomes available on the next turn
 5. Agent uses the loaded tool normally
 
+## Single-step discovery with `autoLoad`
+
+Set `search.autoLoad` to `true` to skip the separate load step. The tools returned by `search_tools` are activated immediately, and the `load_tool` meta-tool isn't exposed. This removes one model turn per discovery, which lowers token usage and latency, and works the same across providers.
+
+```typescript
+const toolSearch = new ToolSearchProcessor({
+  tools: allTools,
+  search: {
+    topK: 3,
+    autoLoad: true,
+  },
+})
+```
+
+With `autoLoad` the workflow becomes:
+
+1. Agent receives a user message
+2. Agent calls `search_tools` with keywords
+3. The matching tools are activated automatically and become available on the next turn
+4. Agent uses the tool normally
+
+Every match is activated, so keep `topK` small (for example, `3`) to avoid adding tools the agent didn't need. Activated tools are appended after existing tools, which keeps the cached prompt prefix stable for providers that support prompt caching.
+
+## Loaded-tool storage
+
+The `storage` option controls where the set of loaded tools is tracked. The default is `'in-memory'`; the `'context'` store is opt-in.
+
+### `'in-memory'` (default)
+
+Loaded tools are tracked in an in-memory map per thread, with TTL-based cleanup controlled by the `ttl` option (default one hour). This is the original behavior:
+
+- Requires no memory configuration.
+- State is lost on process restart.
+- Requests with no thread ID share a single `'default'` entry.
+
+Use `clearState`, `clearAllState`, `getStateStats`, and `cleanupNow` to inspect or reset this store.
+
+### `'context'`
+
+Loaded state is derived from the conversation messages: a tool is loaded while a `search_tools` or `load_tool` result naming it remains in the messages. This mode:
+
+- Requires no memory configuration.
+- Is restart-safe — the durable record is the persisted message history.
+- De-loads a tool automatically once that result is no longer present in the messages.
+
+```typescript
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: allTools,
+  storage: 'context',
+})
+```
+
+Loading tools is cache-friendly in both modes: loads are append-only, so the cached prompt prefix stays stable for providers that support prompt caching.
+
+Unloading a tool changes the tool definitions sent to the model, which shifts the cached prefix and causes the next turn to pay a cache write instead of a cache hit. In `'in-memory'` mode this happens when a thread's state is evicted by `ttl`. In `'context'` mode it happens when a tool's discovery result is no longer present in the messages (for example, when older messages are trimmed) — the tool de-loads and the model must search for it again before reuse. This is expected: removing an unused tool trades one cache write for a smaller prefix on later turns.
+
 ## Combining with other processors
 
 ```typescript

package/.docs/reference/pubsub/base.md

@@ -165,7 +165,7 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 ### `SubscribeBatchOptions`
 
-Per-subscription batching policy. The callback signature does not change; a batch of N events becomes N consecutive callback invocations in publish order.
+Per-subscription batching policy. The callback signature doesn't change; a batch of N events becomes N consecutive callback invocations in publish order.
 
 **maxSize** (`number`): Maximum events held before forcing a flush.
 

package/.docs/reference/pubsub/caching-pubsub.md

@@ -2,9 +2,9 @@
 
 `CachingPubSub` wraps any [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation and adds event caching and replay. It records every published event per topic in a cache, so a subscriber that connects late or reconnects after a disconnect can replay the events it missed before continuing with live events.
 
-Use it to build resumable streams on top of a transport that does not keep history, such as [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). Transports that already persist events, such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), do not need this wrapper.
+Use it to build resumable streams on top of a transport that doesn't keep history, such as [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). Transports that already persist events, such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), don't need this wrapper.
 
-`CachingPubSub` is transparent to batching: `subscribe()` forwards `options.batch` to the inner pub/sub, and `supportsNativeBatching` mirrors the inner's value. Wrapping an inner that does not support batching results in unbatched delivery even when `options.batch` is passed.
+`CachingPubSub` is transparent to batching: `subscribe()` forwards `options.batch` to the inner pub/sub, and `supportsNativeBatching` mirrors the inner's value. Wrapping an inner that doesn't support batching results in unbatched delivery even when `options.batch` is passed.
 
 ## Usage example
 

package/.docs/reference/pubsub/event-emitter.md

@@ -4,11 +4,11 @@
 
 Use it for single-process applications. For delivery across processes on one host, see [`UnixSocketPubSub`](https://mastra.ai/reference/pubsub/unix-socket-pubsub). For distributed delivery, see [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
 
-Because it is in-process, events are not persisted and are not shared with other processes. Wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) when you need replay for resumable streams.
+Because it's in-process, events aren't persisted and aren't shared with other processes. Wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) when you need replay for resumable streams.
 
 ## Usage example
 
-`EventEmitterPubSub` is used automatically when you do not configure a `pubsub` option, so most applications never construct it directly. Create one explicitly only when you want to configure or share it.
+`EventEmitterPubSub` is used automatically when you don't configure a `pubsub` option, so most applications never construct it directly. Create one explicitly only when you want to configure or share it.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -104,4 +104,4 @@ await pubsub.subscribe(
 )
 ```
 
-The buffer is in-memory and per-process, so batched state is not persisted and does not survive a restart. A flush triggered by `maxWaitMs` is best-effort: if a step such as a throwing `coalesce` fails, the error is surfaced through the configured `logger` rather than thrown. `flush()` drains every batched subscriber buffer before resolving.
+The buffer is in-memory and per-process, so batched state isn't persisted and doesn't survive a restart. A flush triggered by `maxWaitMs` is best-effort: if a step such as a throwing `coalesce` fails, the error is surfaced through the configured `logger` rather than thrown. `flush()` drains every batched subscriber buffer before resolving.

package/.docs/reference/pubsub/google-cloud-pubsub.md

@@ -57,7 +57,7 @@ export const mastra = new Mastra({
 
 ### `init(topicName, group?)`
 
-Creates the topic and a subscription if they do not already exist, and returns the subscription. `subscribe` calls this internally, so you rarely call it directly.
+Creates the topic and a subscription if they don't already exist, and returns the subscription. `subscribe` calls this internally, so you rarely call it directly.
 
 ```typescript
 await pubsub.init('workflow.events')

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

@@ -105,4 +105,4 @@ await pubsub.close()
 
 ## Redelivery and reclaim
 
-When a subscriber calls `nack`, the event is republished with an incremented `deliveryAttempt` and the original is acknowledged. Once an event reaches `maxDeliveryAttempts`, it is dropped instead of redelivered. Separately, each subscription periodically reclaims events that an earlier consumer in the group read but never acknowledged, controlled by `reclaimIntervalMs` and `reclaimIdleMs`.
+When a subscriber calls `nack`, the event is republished with an incremented `deliveryAttempt` and the original is acknowledged. Once an event reaches `maxDeliveryAttempts`, it's dropped instead of redelivered. Separately, each subscription periodically reclaims events that an earlier consumer in the group read but never acknowledged, controlled by `reclaimIntervalMs` and `reclaimIdleMs`.

package/.docs/reference/pubsub/unix-socket-pubsub.md

@@ -4,7 +4,7 @@
 
 Use it when several local processes need to share a stream, such as coordinating thread streams across the Mastra Code terminal interface. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For distributed delivery across hosts, use [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
 
-`UnixSocketPubSub` is a push transport: events arrive without a read loop, so Mastra does not run a pull worker for it.
+`UnixSocketPubSub` is a push transport: events arrive without a read loop, so Mastra doesn't run a pull worker for it.
 
 ## Usage example
 

package/.docs/reference/server/nestjs-adapter.md

@@ -2,7 +2,7 @@
 
 The `@mastra/nestjs` package provides a NestJS module for running Mastra with the Express-based NestJS platform.
 
-It is intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
+It's intentionally Express-only for v1. If Nest is bootstrapped with a different HTTP adapter, `MastraModule` throws during startup instead of attempting a partial integration.
 
 > **Info:** For general adapter concepts, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
@@ -51,7 +51,7 @@ import { mastra } from './mastra'
 export class AppModule {}
 ```
 
-> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it is imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
+> **Note:** `MastraModule` registers a catch-all controller (`@All('*')`). If it's imported before your app modules, it can intercept unrelated routes and return 404s. To avoid conflicts, import `MastraModule` last or mount it under a dedicated prefix (e.g., `/api/v1/mastra`).
 
 ```typescript
 import { NestFactory } from '@nestjs/core'

package/.docs/reference/signals/task-signal-provider.md

@@ -0,0 +1,62 @@
+# TaskSignalProvider
+
+Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.
+
+Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider). The task list is stored in the thread-scoped `tasks` storage domain (the source of truth) and projected onto the agent state-signal lane by the processor, so it survives observational-memory truncation without invalidating the prompt cache.
+
+## Usage example
+
+Register the provider on an agent that has `Memory` and a Mastra `storage`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TaskSignalProvider } from '@mastra/core/signals'
+
+const agent = new Agent({
+  name: 'coder',
+  instructions: '...',
+  model,
+  memory,
+  signals: [new TaskSignalProvider()],
+})
+```
+
+The Agent automatically merges the four task tools into its toolset and registers the processor on its input-processor chain. No other wiring is required.
+
+Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the task tools no-op and return a result explaining that task tracking requires agent memory. The `tasks` storage domain is wired in-memory by default, so task tracking works without configuring a storage backend.
+
+## Constructor parameters
+
+`TaskSignalProvider` takes no constructor arguments.
+
+## Properties
+
+**id** (`'task-signals'`): Stable identifier for the provider instance.
+
+## Methods
+
+### Agent integration
+
+These methods are called automatically by the Agent when the provider is passed to `signals`. You normally do not call them directly.
+
+#### `getTools()`
+
+Returns the four task tools keyed by their tool ids (`task_write`, `task_update`, `task_complete`, `task_check`). The Agent merges these into its toolset.
+
+```typescript
+const tools = new TaskSignalProvider().getTools()
+// { task_write, task_update, task_complete, task_check }
+```
+
+Returns: `Record<string, Tool>`
+
+#### `getInputProcessors()`
+
+Returns the provider's `TaskStateProcessor` instance. The Agent registers it on the input-processor chain, which propagates the Mastra instance so the processor can resolve the `tasks` store.
+
+```typescript
+const [processor] = new TaskSignalProvider().getInputProcessors()
+// processor instanceof TaskStateProcessor
+```
+
+Returns: `InputProcessorOrWorkflow[]`