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

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -2,13 +2,17 @@
 
 # createCodingAgent()
 
-`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with portable defaults for the pieces a coding agent always needs: a local workspace, the task-list signal provider, network-retry error processors, and the goal judge prompt. Supply only `model`, `instructions`, and `tools` to get a working agent, or override any default.
+**Added in:** `@mastra/core@1.48.0`
 
-The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+`createCodingAgent()` builds a coding [`Agent`](https://mastra.ai/reference/agents/agent) with the essential defaults a coding agent always needs: a local workspace, the task-list signal provider when `memory` is configured, network-retry error processors, and the goal judge prompt. Supply only `model` and `instructions` to get a working agent, or override any default.
+
+The returned value is a standard `Agent`, so it works anywhere an `Agent` does: including as the agent passed to an [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class). The function lives in `@mastra/core` with no hosted service behind it, and every default it fills in is a primitive you can also configure on [`new Agent()`](https://mastra.ai/reference/agents/agent) yourself.
+
+The defaults match the ones [Mastra Code](https://code.mastra.ai) runs on. The prompt, modes, and tools that make up that product aren't included: `createCodingAgent()` sets up only the runtime pieces listed under [Defaults](#defaults).
 
 ## Usage example
 
-Pass a model, instructions, and tools. The factory fills in the workspace, task signal, error processors, and goal prompt:
+Pass a model and instructions. `createCodingAgent()` fills in the workspace and the error processors. The task signal provider is added when `memory` is configured, and the goal prompt when a `goal` is configured:
 
 ```typescript
 import { createCodingAgent } from '@mastra/core/coding-agent'
@@ -18,13 +22,20 @@ const agent = createCodingAgent({
   name: 'My Coding Agent',
   model: 'openai/gpt-5',
   instructions: 'You are a helpful coding assistant.',
-  tools: {},
 })
+
+const result = await agent.generate('Which test files mention the /health endpoint?')
 ```
 
+The agent receives the [workspace tools](https://mastra.ai/reference/workspace/workspace-class) for its resolved workspace, so `tools` is only needed for capabilities beyond the workspace, such as opening a pull request. Mastra also adds a description of the workspace to the system prompt.
+
+> **Warning:** The default workspace runs commands on the host machine with the permissions of your application process. See [Workspace](#workspace) for how to swap in an isolated sandbox.
+
+For the behavioral prompt Mastra Code uses, covering repository exploration, edits, commands, and commits, build `instructions` with [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt).
+
 ## Parameters
 
-`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide always take precedence over the factory defaults.
+`createCodingAgent()` accepts every field of [`AgentConfig`](https://mastra.ai/reference/agents/agent) plus the fields below. Fields you provide replace the corresponding default, except for `signals`: the default task signal provider is merged into the providers you pass. See [Signals](#signals).
 
 **model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): The language model the agent uses. Passed straight through to Agent.
 
@@ -32,11 +43,11 @@ const agent = createCodingAgent({
 
 **tools** (`ToolsInput | DynamicArgument<ToolsInput>`): Tools available to the agent. Passed straight through to Agent.
 
-**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, the factory builds no default — opt out when the workspace is wired elsewhere (for example at the AgentController level).
+**workspace** (`AnyWorkspace | undefined`): The workspace backing the agent. When the key is omitted, a default local workspace is built. When set explicitly to undefined, no default is built. Opt out this way when the workspace is wired elsewhere, for example at the AgentController level.
 
 **basePath** (`string`): Base path for the default workspace built when workspace is omitted. (Default: `process.cwd()`)
 
-**signals** (`SignalProvider[]`): Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.
+**signals** (`SignalProvider[]`): Signal providers for the agent. A TaskSignalProvider is added only when memory is configured, and it is merged into the providers you pass rather than replacing them. Without memory, the agent gets exactly the providers you pass, or none.
 
 **errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus PrefillErrorHandler and ProviderHistoryCompat.
 
@@ -48,18 +59,29 @@ const agent = createCodingAgent({
 
 ## Defaults
 
-The factory only fills a default when you don't provide the corresponding field. Caller-provided values always win.
+A default is only filled in when you don't provide the corresponding field. `signals` is the exception: the task signal provider is appended to the providers you pass.
 
 | Field             | Default when omitted                                                                                                                           |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `workspace`       | A [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) backed by `LocalFilesystem` and `LocalSandbox` rooted at the base path. |
-| `signals`         | A single [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider).                                                     |
+| `signals`         | A [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), added only when `memory` is configured.                    |
 | `errorProcessors` | Unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus `PrefillErrorHandler` and `ProviderHistoryCompat`.     |
 | `goal.prompt`     | `DEFAULT_GOAL_JUDGE_PROMPT` (only when a `goal` is configured).                                                                                |
 
+Nothing else is filled in. There's no default `model`, `instructions`, `tools`, `memory`, storage, or input and output processors.
+
+Each default has an explicit opt-out:
+
+| Default           | How to opt out                              |
+| ----------------- | ------------------------------------------- |
+| Workspace         | `workspace: undefined`                      |
+| Task tracking     | Don't configure `memory` on the agent       |
+| Error processors  | `errorProcessors: []`                       |
+| Goal judge prompt | Omit `goal`, or pass your own `goal.prompt` |
+
 ### Workspace
 
-When the `workspace` key is omitted, the factory builds a local workspace rooted at `basePath` (default `process.cwd()`):
+When the `workspace` key is omitted, a local workspace rooted at `basePath` (default `process.cwd()`) is built:
 
 ```typescript
 import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
@@ -70,19 +92,94 @@ new Workspace({
 })
 ```
 
-To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly:
+To keep that shape but work in a different directory, pass `basePath`:
 
 ```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  basePath: '/srv/checkouts/my-app',
+})
+```
+
+Pass a `workspace` to build the backends yourself. Here the agent reads the whole repository while commands run inside one package. A remote sandbox takes the place of `LocalSandbox` in the same slot, see [Sandbox](https://mastra.ai/docs/sandbox/overview) for the available backends and isolation options:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  workspace: new Workspace({
+    filesystem: new LocalFilesystem({ basePath: '/srv/checkouts/my-app' }),
+    sandbox: new LocalSandbox({ workingDirectory: '/srv/checkouts/my-app/packages/api' }),
+  }),
+})
+```
+
+To opt out (for example, when the workspace is injected at the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) level), pass `workspace: undefined` explicitly. An omitted key builds the default, an explicit `undefined` builds nothing:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+
 const agent = createCodingAgent({
   id: 'my-coding-agent',
   name: 'My Coding Agent',
   model: 'openai/gpt-5',
   instructions: 'You are a helpful coding assistant.',
-  tools: {},
   workspace: undefined, // opt out of the default workspace
 })
 ```
 
+### Signals
+
+[`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider) adds the `task_write`, `task_update`, `task_complete`, and `task_check` [task tools](https://mastra.ai/reference/tools/task-tools) and persists the list in thread state, which gives the agent a durable plan across a multi-step request:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'Plan multi-step work with the task tools, then carry it out.',
+  memory: new Memory(),
+})
+```
+
+The provider needs a memory-backed thread, so it's only added when `memory` is configured. With memory configured, the provider is merged into any `signals` you pass, which keeps task tracking from being dropped by custom providers. Passing `signals: []` alongside `memory` still yields the task provider. To run a memory-backed agent with no task tracking, configure the agent with [`new Agent()`](https://mastra.ai/reference/agents/agent) instead. Before `@mastra/core@1.49.0`, the provider was always added, which failed in memoryless contexts.
+
+`TaskSignalProvider` takes no constructor arguments, so customizing this default means choosing which other providers the agent gets:
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { WebhookSignalProvider } from '@mastra/core/signals'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  memory: new Memory(),
+  signals: [
+    new WebhookSignalProvider({
+      extractResourceId: payload => (payload as { repository: string }).repository,
+    }),
+  ],
+})
+```
+
+That agent gets the webhook provider and the task provider.
+
 ### Error processors
 
 The default [`StreamErrorRetryProcessor`](https://mastra.ai/reference/processors/stream-error-retry-processor) applies these retry policies:
@@ -91,10 +188,42 @@ The default [`StreamErrorRetryProcessor`](https://mastra.ai/reference/processors
 - Network resets (`ECONNRESET` / `socket hang up`) retry up to twice with exponential backoff (`1000ms * 2^retryCount`, capped at `30000ms`).
 - Bad-request errors retry once after `2000ms`.
 
-Specific network-reset and bad-request policies take precedence over the unknown-error policy. Passing `errorProcessors` replaces the default processor stack. `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
+Specific network-reset and bad-request policies take precedence over the unknown-error policy. Passing `errorProcessors` replaces the default processor stack. `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility: both repair errors caused by the shape of the message history, such as a provider rejecting a conversation that ends with an assistant message.
+
+Retries happen inside the `generate()` or `stream()` call that hit the error, so a recovered failure is invisible to your code. When the retries run out, the error surfaces the way any model error does: `generate()` rejects and `stream()` emits an `error` chunk. `generate()` and `stream()` also accept `errorProcessors` per call, which replaces the agent's stack for that request. See [Processors](https://mastra.ai/docs/agents/processors) for `maxProcessorRetries`, the retry budget these processors share.
+
+### Goal
+
+No goal is configured by default. When you pass a `goal` without a `prompt`, `DEFAULT_GOAL_JUDGE_PROMPT` is used. The `goal` config carries the judge and the run budget, while the objective itself is per thread and set with [`setObjective()`](https://mastra.ai/docs/harness/goals):
+
+```typescript
+import { createCodingAgent } from '@mastra/core/coding-agent'
+import { Memory } from '@mastra/memory'
+
+const agent = createCodingAgent({
+  id: 'my-coding-agent',
+  name: 'My Coding Agent',
+  model: 'openai/gpt-5',
+  instructions: 'You are a helpful coding assistant.',
+  memory: new Memory(),
+  goal: {
+    judge: 'openai/gpt-5-mini',
+    maxRuns: 50,
+  },
+})
+
+const threadId = 'thread-1'
+const resourceId = 'user-1'
+
+await agent.setObjective('Get the test suite passing', { threadId, resourceId })
+```
+
+[Goals](https://mastra.ai/docs/harness/goals) require a [storage](https://mastra.ai/docs/storage) backend and a memory-backed thread. Without a resolved `judge`, the goal step is a no-op.
 
 ## Related
 
 - [`buildBasePrompt()`](https://mastra.ai/reference/coding-agent/build-base-prompt)
+- [Goals](https://mastra.ai/docs/harness/goals)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)
 - [`Agent`](https://mastra.ai/reference/agents/agent)
 - [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/reference/configuration.md

@@ -44,7 +44,7 @@ export const mastra = new Mastra({
 
 Enables and configures the background task manager. When enabled, agents can dispatch long-running tool calls (including subagent invocations) to run asynchronously while the agentic loop continues. Tasks are persisted, so a configured `storage` backend is required.
 
-Visit the [Background tasks documentation](https://mastra.ai/docs/long-running-agents/background-tasks) to learn more.
+Visit the [Background tasks documentation](https://mastra.ai/docs/harness/background-tasks) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -219,7 +219,7 @@ export const mastra = new Mastra({
 
 MCP (Model Context Protocol) servers that expose Mastra tools, agents, workflows, and resources to MCP-compatible clients. Use this to author your own MCP servers that can be consumed by any system that supports the protocol.
 
-Visit the [MCP Overview](https://mastra.ai/docs/mcp/overview) to learn more.
+Visit the [MCP Overview](https://mastra.ai/docs/connections/mcp) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -366,7 +366,7 @@ export const mastra = new Mastra({
 
 Storage provider for persisting application data. Used by memory, workflows, traces, and other components that require persistence. Mastra supports multiple database backends including PostgreSQL, MongoDB, libSQL, and more.
 
-Visit the [Storage documentation](https://mastra.ai/docs/storage/overview) to learn more.
+Visit the [Storage documentation](https://mastra.ai/docs/storage) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -386,7 +386,7 @@ export const mastra = new Mastra({
 
 Tools are reusable functions that agents can use to interact with external systems. Each tool defines inputs, outputs, and execution logic.
 
-Visit the [Tools documentation](https://mastra.ai/docs/agents/using-tools) to learn more.
+Visit the [Tools documentation](https://mastra.ai/docs/agents/tools) to learn more.
 
 > **Note:** Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.
 
@@ -483,7 +483,7 @@ export const mastra = new Mastra({
 
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the `Mastra` class unless they have their own workspace configured.
 
-See the [Workspace documentation](https://mastra.ai/docs/workspace/sandbox) for implementation details.
+See the [Workspace documentation](https://mastra.ai/docs/sandbox/overview) for implementation details.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -618,7 +618,7 @@ export const mastra = new Mastra({
 
 Authentication configuration for the server. Mastra supports multiple authentication providers including JWT, Clerk, Supabase, Firebase, WorkOS, and Auth0.
 
-Visit the [Authentication documentation](https://mastra.ai/docs/server/auth) to learn more.
+Visit the [Authentication documentation](https://mastra.ai/docs/auth/overview) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/getEditor.md

@@ -33,5 +33,5 @@ This method doesn't accept any parameters.
 
 ## Related
 
-- [Editor](https://mastra.ai/docs/editor/overview)
+- [Editor](https://mastra.ai/docs/studio/editor)
 - [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)

package/.docs/reference/core/getMCPServer.md

@@ -43,5 +43,5 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getMCPServerById.md

@@ -51,5 +51,5 @@ const serverByKey = mastra.getMCPServer('customKey')
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/getTool.md

@@ -27,7 +27,7 @@ const tool = mastra.getTool('weather')
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)
 - [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/getToolById.md

@@ -42,7 +42,7 @@ const toolById = mastra.getToolById('weather-tool')
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
 - [Mastra.listTools()](https://mastra.ai/reference/core/listTools)

package/.docs/reference/core/listMCPServers.md

@@ -49,5 +49,5 @@ This method doesn't accept any parameters.
 
 ## See also
 
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/.docs/reference/core/listTools.md

@@ -32,7 +32,7 @@ This method lists the Mastra-level registry. It doesn't include tools that exist
 
 ## Related
 
-- [Share tools across agents](https://mastra.ai/docs/agents/using-tools)
+- [Share tools across agents](https://mastra.ai/docs/agents/tools)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Mastra.getTool()](https://mastra.ai/reference/core/getTool)
 - [Mastra.getToolById()](https://mastra.ai/reference/core/getToolById)

package/.docs/reference/core/removeWorkspace.md

@@ -24,5 +24,5 @@ When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with
 
 ## Related
 
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/reference/editor/mastra-editor.md

@@ -4,7 +4,7 @@
 
 The `MastraEditor` class sets up the editor system. Pass it to the `Mastra` constructor to turn on editor features like prompt blocks, agent code override, versioning, and tool providers.
 
-See [Editor](https://mastra.ai/docs/editor/overview) for an introduction to what the editor does.
+See [Editor](https://mastra.ai/docs/studio/editor) for an introduction to what the editor does.
 
 ## Usage example
 
@@ -238,4 +238,4 @@ const source = mastra.getEditor()?.getSource()
 
 Returns: `'code' | 'db' | undefined`
 
-When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/editor/overview) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.
+When `source` is omitted, Editor uses the configured database storage even though `getSource()` returns `undefined`. See [Editor storage options](https://mastra.ai/docs/studio/editor) for the storage workflows and [code-source versioning](https://mastra.ai/reference/editor/versioning) for activation and Git history behavior.

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