@mastra/mcp-docs-server 1.2.17-alpha.9 → 1.2.18-alpha.1

package/.docs/reference/editor/prompt-blocks.md

@@ -4,7 +4,7 @@
 
 Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text with embedded prompt blocks and references to independently versioned prompt blocks.
 
-See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+See [Prompt blocks](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
 
 ## Block types
 
@@ -134,4 +134,4 @@ The default Mastra server prefix is `/api`. A custom server prefix changes the p
 
 ## Version resolution
 
-Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/editor/overview) for the shared draft, publish, and restore lifecycle.
+Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/studio/editor) for the shared draft, publish, and restore lifecycle.

package/.docs/reference/editor/tool-provider.md

@@ -4,7 +4,7 @@
 
 The `ToolProvider` interface defines how the editor discovers and resolves integration tools from external platforms. Mastra includes two built-in implementations: `ComposioToolProvider` and `ArcadeToolProvider`.
 
-See [Editor tools](https://mastra.ai/docs/editor/overview) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
+See [Editor tools](https://mastra.ai/docs/studio/editor) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
 
 ## ToolProvider interface
 
@@ -77,6 +77,8 @@ const editor = new MastraEditor({
 
 **defaultScope** (`'per-author' | 'caller-supplied'`): Connection identity scope. Defaults to per-author. (Default: `'per-author'`)
 
+**userIdResolver** (`ComposioUserIdResolver`): Server-side resolver that derives the effective Composio userId from authenticated context fields. Used for invoker and caller-supplied execution. The exact connected account always comes from the stored connection pin.
+
 ### Tool slugs
 
 Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MESSAGE`.
@@ -85,6 +87,111 @@ Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MES
 
 Connections use per-author scope by default. Set `defaultScope: 'caller-supplied'` to bucket authorization by the caller identity resolved from `MASTRA_RESOURCE_ID_KEY` in request context. Ensure each authenticated request provides a stable, unique resource ID. When using `MastraAuthWorkos`, configure `mapUserToResourceId` to set this value from the authenticated user.
 
+How the provider resolves the Composio user for a tool call depends on the connection:
+
+- **Author-bound connections** (`kind: 'author'`) execute as the agent author's user against the pinned connected account.
+- **Invoker-bound connections** (`kind: 'invoker'`) execute as the authenticated invoker against the exact pinned account, which may be an account another user shared with the invoker through Composio's access control list (ACL). The user ID comes from `userIdResolver` when configured, then the authenticated user, and never from the Memory `resourceId`. Invoker resolution fails when no authenticated user or resolver result exists.
+- **Caller-supplied scope** (`scope: 'caller-supplied'`) uses `userIdResolver` when configured. Otherwise, it falls back to the legacy `resourceId` from request context for backward compatibility. When a specific connected account is pinned, execution routes to that exact account. Otherwise, Composio auto-resolves within the user's bucket.
+
+### Execute with a shared account
+
+Bob needs to run a Salesforce tool with an account that Alice shared through Composio. Keep each identity separate:
+
+| Identity          | Value                 |
+| ----------------- | --------------------- |
+| Memory resource   | `project_123`         |
+| Composio user ID  | `bob`                 |
+| Connected account | `ca_alice_salesforce` |
+
+Register the provider normally. Mastra server authentication writes the authenticated user to request context, so most applications don't need a `userIdResolver`:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { MastraEditor } from '@mastra/editor'
+import { ComposioToolProvider } from '@mastra/editor/composio'
+
+const editor = new MastraEditor({
+  toolProviders: {
+    composio: new ComposioToolProvider({
+      apiKey: process.env.COMPOSIO_API_KEY!,
+    }),
+  },
+})
+
+export const mastra = new Mastra({ editor })
+```
+
+Configure the agent with an invoker connection pinned to `ca_alice_salesforce`. When Bob invokes the agent, Mastra sends `bob` as the Composio user and the pinned account ID as the exact connected account. The Memory resource stays `project_123`. Composio then checks whether the account's ACL permits Bob to execute it.
+
+### Map application users to Composio users
+
+Use `userIdResolver` when your Composio user IDs differ from the IDs returned by Mastra authentication, or when your application must authorize the stored account pin before execution.
+
+```typescript
+type ComposioUserIdResolver = (
+  input: ComposioUserIdResolverInput,
+) => Promise<string | undefined> | string | undefined
+```
+
+**requestContext** (`RequestContext`): Live per-request context. Client-provided non-reserved entries are untrusted. Derive identity and authorize connectedAccountId only from validated, server-populated fields such as MASTRA\_USER\_KEY, read with getRaw().
+
+**toolkit** (`string`): Toolkit slug the identity is being resolved for, when known.
+
+**connectedAccountId** (`string`): Stored connection pin being resolved, when one exists. Use it to validate that the invoker may use this exact account.
+
+The resolver returns the Composio user ID, or `undefined` to use the provider's default resolution. Returning an empty string throws instead of silently falling back. The resolver can't replace the connected account.
+
+This example namespaces the Composio user by organization and asks the application's authorization layer to approve the exact account pin:
+
+```typescript
+import { MASTRA_USER_KEY } from '@mastra/server/auth'
+import { ComposioToolProvider } from '@mastra/editor/composio'
+import { canUseConnectedAccount } from './integration-authorization'
+
+type AuthenticatedUser = {
+  id: string
+  organizationId: string
+}
+
+function isAuthenticatedUser(value: unknown): value is AuthenticatedUser {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'organizationId' in value &&
+    typeof value.organizationId === 'string'
+  )
+}
+
+const composio = new ComposioToolProvider({
+  apiKey: process.env.COMPOSIO_API_KEY!,
+  userIdResolver: async ({ requestContext, toolkit, connectedAccountId }) => {
+    const user = requestContext?.getRaw(MASTRA_USER_KEY)
+    if (!isAuthenticatedUser(user)) return undefined
+
+    if (connectedAccountId) {
+      const allowed = await canUseConnectedAccount({
+        actorId: user.id,
+        organizationId: user.organizationId,
+        provider: 'composio',
+        toolkit,
+        connectedAccountId,
+      })
+      if (!allowed) {
+        throw new Error('User cannot access this connected account')
+      }
+    }
+
+    return `${user.organizationId}:${user.id}`
+  },
+})
+```
+
+Use the same namespaced ID when creating Composio connections and shared-account ACL entries. For example, Bob's Composio user ID in this setup is `acme:bob`.
+
+Throw from `userIdResolver` to deny the request. During stored-agent resolution, Mastra logs the failure and omits tools associated with that connection, so no tool call reaches Composio. Other connections continue to resolve. When calling `resolveToolsVNext()` directly, the error is returned to the caller instead.
+
 ### Connection management tools
 
 Composio provides tools for starting and monitoring authorization from an agent chat. When `allowedToolkits` is set, include `composio` to make these tools available:

package/.docs/reference/editor/tools.md

@@ -4,7 +4,7 @@
 
 Editor stores tool selections as part of an agent version. A stored configuration can add registered tools and tools from integration providers, as well as tools from Model Context Protocol (MCP) clients.
 
-See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+See [Editor tools](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
 
 ## Tool sources
 

package/.docs/reference/editor/versioning.md

@@ -4,7 +4,7 @@
 
 Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations. Code-backed agent overrides use deterministic files and Git history.
 
-See [Editor versioning](https://mastra.ai/docs/editor/overview) for release and experimentation patterns.
+See [Editor versioning](https://mastra.ai/docs/studio/editor) for release and experimentation patterns.
 
 ## Database lifecycle
 
@@ -35,7 +35,7 @@ See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for sourc
 
 ## Select an agent version
 
-Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/editor/overview) for a TypeScript example.
+Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/studio/editor) for a TypeScript example.
 
 With the default server prefix, pass selectors as query parameters under `/api`:
 
@@ -54,7 +54,7 @@ See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agen
 
 ## Sub-agent versioning
 
-Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:
+Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/subagents) in request context. Define selectors at three levels:
 
 1. `Mastra` instance `versions`: Defaults for every invocation
 2. Server request-body `versions`: Per-request values added to request context

package/.docs/reference/evals/prompt-alignment.md

@@ -70,6 +70,24 @@ const scorer = createPromptAlignmentScorerLLM({
 })
 ```
 
+### Multi-turn conversations
+
+By default the scorer only sees the current turn. In a conversation, a reply like `"A"` is meaningless on its own, so the judge can't tell what the user asked for and scores the response as misaligned.
+
+Set `includeConversationHistory` to give the judge the prior turns from the agent's memory. The judge uses them to interpret the current prompt, but still scores only the current response.
+
+```typescript
+const scorer = createPromptAlignmentScorerLLM({
+  model: 'openai/gpt-5.6-sol',
+  options: {
+    evaluationMode: 'user',
+    includeConversationHistory: { maxMessages: 6 }, // or `true` for the last 10 messages
+  },
+})
+```
+
+This only affects agent runs, where the scorer receives the remembered messages. Runs scored from a plain prompt string are unchanged.
+
 ### Multi-Dimensional Analysis
 
 Prompt Alignment evaluates responses across four key dimensions with weighted scoring that adapts based on the evaluation mode:

package/.docs/reference/evals/rubric.md

@@ -111,5 +111,5 @@ The `reason` summarizes the result and lists each criterion with its verdict, so
 ## Related
 
 - [isTaskComplete on stream()](https://mastra.ai/reference/streaming/agents/stream)
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor agents](https://mastra.ai/docs/subagents)
 - [createScorer](https://mastra.ai/reference/evals/create-scorer)

package/.docs/reference/file-based-agents/memory.md

@@ -18,7 +18,7 @@ import { Memory } from '@mastra/memory'
 export default new Memory()
 ```
 
-The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
+The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage) for more information.
 
 Use the same `resource` and `thread` values when calling the agent to continue a conversation:
 
@@ -51,7 +51,7 @@ export default new Memory({
 
 Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
 
-- [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
+- [Storage](https://mastra.ai/docs/storage): configure persistence for memory data.
 - [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
 - [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
 

package/.docs/reference/file-based-agents/server.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-Mastra configures its HTTP [server](https://mastra.ai/docs/server/mastra-server) from a `server.ts` file directly under `src/mastra/`. The server exposes agents, workflows, and other registered primitives as REST endpoints, and the file default-exports the same `ServerConfig` shape you'd pass to [`new Mastra()`](https://mastra.ai/reference/core/mastra-class).
+Mastra configures its HTTP [server](https://mastra.ai/docs/server/overview) from a `server.ts` file directly under `src/mastra/`. The server exposes agents, workflows, and other registered primitives as REST endpoints, and the file default-exports the same `ServerConfig` shape you'd pass to [`new Mastra()`](https://mastra.ai/reference/core/mastra-class).
 
-Use this page for the file-based convention. For server features, middleware, custom routes, generated API docs, and deployment behavior, see [Server overview](https://mastra.ai/docs/server/mastra-server).
+Use this page for the file-based convention. For server features, middleware, custom routes, generated API docs, and deployment behavior, see [Server overview](https://mastra.ai/docs/server/overview).
 
 ## Quickstart
 
@@ -32,7 +32,7 @@ export default {
 | Add webhooks or health checks         | `apiRoutes`                               |
 | Enable generated API docs             | `build.openAPIDocs` and `build.swaggerUI` |
 
-See [Mastra server](https://mastra.ai/docs/server/mastra-server), [middleware](https://mastra.ai/docs/server/middleware), and [custom API routes](https://mastra.ai/docs/server/custom-api-routes) for examples.
+See [Mastra server](https://mastra.ai/docs/server/overview), [middleware](https://mastra.ai/docs/server/middleware), and [custom API routes](https://mastra.ai/docs/server/custom-api-routes) for examples.
 
 ## Precedence with code
 

package/.docs/reference/file-based-agents/skills.md

@@ -6,7 +6,7 @@
 
 A file-based agent discovers skills from its `skills/` directory and bundles them at build time. Skills are reusable procedures or reference material that the agent can load when relevant, instead of putting every detail into the always-on prompt.
 
-Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/agents/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/workspace/skills).
+Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/sandbox/skills).
 
 ## Quickstart
 

package/.docs/reference/file-based-agents/storage.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
+Mastra sets the project's default [storage](https://mastra.ai/docs/storage) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
 
-Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
+Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage).
 
 ## Quickstart
 
@@ -25,7 +25,7 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Production backends
 
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
 
 ## Precedence with code
 

package/.docs/reference/file-based-agents/subagents.md

@@ -6,7 +6,7 @@
 
 A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
-Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/capabilities/subagents).
+Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/subagents).
 
 ## Quickstart
 

package/.docs/reference/file-based-agents/workspace.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A [workspace](https://mastra.ai/docs/workspace/sandbox) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
+A [workspace](https://mastra.ai/docs/sandbox/overview) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
 
-Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/workspace/sandbox).
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/sandbox/overview).
 
 ## Default workspace
 
@@ -65,7 +65,7 @@ Customize the workspace when the default local directory isn't enough. Common re
 - Add workspace search with BM25 or vector search.
 - Share one workspace across multiple agents.
 
-For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/workspace/sandbox) and [workspace search](https://mastra.ai/docs/workspace/search).
+For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/sandbox/overview) and [workspace search](https://mastra.ai/docs/sandbox/search).
 
 ## Runtime boundary
 

package/.docs/reference/index.md

@@ -211,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getThreadById()](https://mastra.ai/reference/memory/getThreadById)
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
+- [.settled()](https://mastra.ai/reference/memory/settled)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
 - [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)

package/.docs/reference/manual-install.md

@@ -157,7 +157,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).
+   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/tools).
 
 5. Create a `weather-agent.ts` file:
 
@@ -244,7 +244,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
 - [Review the project structure](https://mastra.ai/reference/project-structure): Understand how `src/mastra/` files map to agents, tools, workflows, storage, and configuration.
 - [Test your agent in Studio](https://mastra.ai/docs/studio/overview): Open the local Studio UI and run the weather agent.
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools): Replace the example weather tool with a real tool that calls an API or service.
+- [Use tools with agents](https://mastra.ai/docs/agents/tools): Replace the example weather tool with a real tool that calls an API or service.
 - [Add memory](https://mastra.ai/docs/memory/overview): Persist conversation history and user-specific context.
-- [Configure storage](https://mastra.ai/docs/storage/overview): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
+- [Configure storage](https://mastra.ai/docs/storage): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
 - [Build and deploy](https://mastra.ai/docs/deployment/overview): Build the Mastra server and deploy it to a hosting platform.

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

@@ -145,4 +145,5 @@ export const agent = new Agent({
 - [listThreads](https://mastra.ai/reference/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [settled](https://mastra.ai/reference/memory/settled)
 - [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)

package/.docs/reference/memory/settled.md

@@ -0,0 +1,57 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.settled()
+
+The `.settled()` method resolves once all background work the `Memory` instance started has finished. Some memory work continues after an agent run returns:
+
+- Observational memory cycles (buffered observation and reflection, including the nested agent runs they spawn)
+- Vector cleanup started by `deleteThread()` and `deleteMessages()`
+
+Await this method before closing a storage connection you own. Without it, background statements can run against a closed connection.
+
+The method is declared on the base memory class, so it's also available on the `MastraMemory` instance returned by `agent.getMemory()`.
+
+## Usage example
+
+```typescript
+await agent.generate('Hello', {
+  memory: { thread: 'thread-123', resource: 'user-456' },
+})
+
+await memory.settled()
+await store.close()
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**void** (`Promise<void>`): A promise that resolves when all background memory work has finished. Background work that fails does not reject this promise.
+
+## Extended usage example
+
+Test suites and short-lived processes are the most common places to need this, since they close the store immediately after a run finishes.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+const store = new PostgresStore({ connectionString })
+const memory = new Memory({ storage: store })
+
+// ... run your agent ...
+
+// Wait for observational memory and vector cleanup to finish before closing.
+await memory.settled()
+await store.close()
+```
+
+> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It does not prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)

package/.docs/reference/migrations/network-to-supervisor.md

@@ -255,9 +255,9 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 
 ## See also
 
-- [Supervisor Agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor Agents](https://mastra.ai/docs/subagents)
 - [Agent Networks](https://mastra.ai/docs/agents/networks)
 - [Agent.stream() Reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.generate() Reference](https://mastra.ai/reference/agents/generate)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
 - [Guide: Research Coordinator](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents)

package/.docs/reference/processors/provider-history-compat.md

@@ -45,11 +45,12 @@ Mastra agents don't add this processor automatically. Add it explicitly when you
 
 `ProviderHistoryCompat` includes these built-in compatibility rules:
 
-| Rule                                        | Provider  | Timing                      | Behavior                                                                                                                          |
-| ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `anthropic-tool-id-format`                  | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                   |
-| `cerebras-strip-reasoning-content`          | Cerebras  | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
-| `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.       |
+| Rule                                        | Provider     | Timing                      | Behavior                                                                                                                                                    |
+| ------------------------------------------- | ------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anthropic-tool-id-format`                  | Anthropic    | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                                             |
+| `cerebras-strip-reasoning-content`          | Cerebras     | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields.                           |
+| `anthropic-strip-foreign-reasoning-content` | Anthropic    | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.                                 |
+| `azure-system-reminder-transform`           | Azure OpenAI | Preemptive prompt rewrite   | Renames `<system-reminder>` wrappers in user text and system instructions to `<memory-context>` for the outbound request. Stored history remains unchanged. |
 
 Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.
 

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

@@ -41,6 +41,8 @@ const skillSearch = new SkillSearchProcessor({
 
 **options.ttl** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
 
+**options.blockingRefresh** (`boolean`): When true, awaits the skills staleness check before the first step of each request so skill changes appear in the same turn. When false, the cached catalog is served and revalidated in the background, so skill changes can lag by one turn plus the staleness cooldown (up to 30 seconds).
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'skill-search'
@@ -112,4 +114,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
 
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Workspace Skills](https://mastra.ai/docs/workspace/skills)
+- [Workspace Skills](https://mastra.ai/docs/sandbox/skills)

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

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

package/.docs/reference/processors/tool-call-filter.md

@@ -2,7 +2,9 @@
 
 # ToolCallFilter
 
-The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the prompt sent to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+
+Filtering happens in the `processLLMRequest` hook, which runs after the message list is converted to a model prompt. Changes are transient: they affect only what's sent to the model on that call. Stored messages, memory, and UI history keep their original tool calls and results.
 
 ## Usage example
 
@@ -44,13 +46,11 @@ const filterWithCompactToolHistory = new ToolCallFilter({
 
 **name** (`string`): Processor display name set to 'ToolCallFilter'
 
-**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Processes input messages to filter out tool calls and their results based on configuration
-
-**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes agent loop step input when filterAfterToolSteps is configured. Returns no changes when step filtering is disabled
+**processLLMRequest** (`(args: ProcessLLMRequestArgs) => Promise<ProcessLLMRequestResult | undefined>`): Filters tool calls and results out of the model prompt before it is sent to the provider. Returns undefined when nothing is filtered. Changes are transient and are not persisted to the message list or memory
 
 ## Step filtering
 
-By default, `ToolCallFilter` filters only the initial input before the agent loop starts. Set `filterAfterToolSteps` to also filter during each loop step.
+By default, `ToolCallFilter` filters tool calls from history but leaves tool calls made during the current agent loop in place. Set `filterAfterToolSteps` to also filter tool calls produced by the current loop.
 
 `filterAfterToolSteps` counts tool-producing steps. For example, `filterAfterToolSteps: 2` keeps tool calls and results from the two most recent tool-producing steps and filters older tool calls and results. Non-tool text remains in context.
 
@@ -64,9 +64,9 @@ const filter = new ToolCallFilter({
 
 ## Preserve compact model output
 
-Set `preserveModelOutput: true` to retain compact `toModelOutput` history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw `toolInvocation.args` and raw `toolInvocation.result` payloads.
+Set `preserveModelOutput: true` to retain compact `toModelOutput` history for tool results that the filter removes. The removed tool call and result are replaced with a single text part in the prompt, so the model still sees the output while the raw tool arguments are dropped.
 
-Only completed tool results with `providerMetadata.mastra.modelOutput` are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.
+Tool results without model output that can be represented as text are removed entirely.
 
 ```typescript
 const filter = new ToolCallFilter({

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

@@ -277,4 +277,4 @@ const agent = new Agent({
 ## Related
 
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
+- [Using Tools](https://mastra.ai/docs/agents/tools)

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/develop) docs.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/develop) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

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

@@ -2,7 +2,7 @@
 
 # LeaseProvider
 
-`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/long-running-agents/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.
+`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.
 
 Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can actually coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
 
@@ -129,5 +129,5 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
-- [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread execution across processes
-- [Channels](https://mastra.ai/docs/capabilities/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Signals](https://mastra.ai/docs/harness/signals): The runtime that uses leasing to coordinate thread execution across processes
+- [Channels](https://mastra.ai/docs/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

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

@@ -131,7 +131,7 @@ When a subscriber calls `nack`, the event is republished with an incremented `de
 
 ## Distributed leasing
 
-`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
+`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/harness/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
 
 Lease keys are namespaced under the same `keyPrefix` as topics, as `<keyPrefix>:lease:<key>`. All operations are atomic: `acquireLease` uses `SET NX PX` and refreshes its own TTL idempotently, while `releaseLease`, `renewLease`, and `transferLease` use Lua scripts that check ownership before mutating, so a concurrent renewal from another owner is never clobbered.