@mastra/mcp-docs-server 1.1.39-alpha.6 → 1.1.39

package/.docs/docs/agents/acp.md

@@ -0,0 +1,238 @@
+# ACP (Agent Client Protocol)
+
+Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
+
+ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements the Agent Client Protocol over standard input and output.
+
+## When to use ACP
+
+- A Mastra agent should delegate code inspection, editing, or repository tasks to an external coding agent.
+- An ACP-compatible agent process should stay alive across calls so it can keep session context.
+- A parent agent needs real-time output from a coding agent while the task runs.
+- An ACP-compatible agent needs permission prompts before it reads files, writes files, or runs actions.
+- File access should go through Mastra's workspace abstraction instead of direct process-only file access.
+
+## How ACP works
+
+`@mastra/acp` starts the configured ACP agent command as a child process and communicates with it using newline-delimited JSON over standard input and output.
+
+The flow is:
+
+1. Configure `command`, `args`, and optional connection settings.
+2. `@mastra/acp` spawns the ACP agent process on first use.
+3. The client sends ACP `initialize` and `session/new` requests.
+4. Mastra sends the user task to the ACP agent with `session/prompt`.
+5. The ACP agent streams session updates and message chunks back to Mastra.
+6. Mastra returns the buffered output, emits streaming chunks, or suspends for permission input.
+7. The ACP process stays alive by default, or stops after the prompt when `persistSession` is `false`.
+
+During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
+
+## Getting started
+
+Install `@mastra/acp` in a project that already uses `@mastra/core`:
+
+**npm**:
+
+```bash
+npm install @mastra/acp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/acp
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/acp
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/acp
+```
+
+`@mastra/acp` exports two APIs:
+
+- `createACPTool`: Create a Mastra tool that sends a `task` string to an ACP agent and returns an `output` string.
+- `AcpAgent`: Wrap an ACP agent as a Mastra subagent with `generate()` and `stream()` support.
+
+The package requires `@mastra/core` version `1.34.0` or later.
+
+## Use ACP as a subagent
+
+Use `AcpAgent` when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent. Create the ACP agent, then register it in the parent agent's `agents` map.
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  name: 'Code Agent',
+  description: 'An ACP-compatible coding agent that can inspect and edit files',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent subagent.',
+  model: 'openai/gpt-5.4',
+  agents: {
+    codeAgent,
+  },
+})
+```
+
+`AcpAgent.generate()` buffers the ACP response and returns it as text. `AcpAgent.stream()` emits Mastra `text-delta` chunks as ACP `agent_message_chunk` updates arrive.
+
+## Use ACP as a tool
+
+Use `createACPTool` when the parent Mastra agent should decide when to call the ACP agent as a tool. The following example creates a code editing tool and registers it on a parent agent:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+import { Agent } from '@mastra/core/agent'
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to inspect and edit code',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+})
+
+export const codeSupervisor = new Agent({
+  id: 'code-supervisor',
+  name: 'Code Supervisor',
+  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
+  model: 'openai/gpt-5.4',
+  tools: {
+    codeAgentTool,
+  },
+})
+```
+
+Use the `command` and `args` required by the ACP-compatible agent you run. The tool input schema has a single `task` string, and the output schema returns the final ACP response as `output`.
+
+If the ACP agent requests permission, the tool can suspend and resume through Mastra's tool suspension flow. Use `onPermissionRequest` when you need custom permission behavior.
+
+## Options reference
+
+`createACPTool` and `AcpAgent` accept the same ACP connection options. `AcpAgent` also accepts `name` to set the display name used during agent delegation.
+
+| Option                | Type                             | Description                                                                             |
+| --------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
+| `id`                  | `string`                         | Unique tool or subagent identifier.                                                     |
+| `description`         | `string`                         | Description shown to the model when it can call the tool or delegate to the subagent.   |
+| `command`             | `string`                         | ACP agent executable to spawn.                                                          |
+| `args`                | `string[]`                       | Arguments passed to the ACP agent executable.                                           |
+| `env`                 | `Record<string, string>`         | Environment variables to merge with the current process environment.                    |
+| `cwd`                 | `string`                         | Working directory for the ACP process, ACP session, and default workspace.              |
+| `session`             | `Partial<NewSessionRequest>`     | ACP session creation options. Defaults to `cwd` or `process.cwd()` and no MCP servers.  |
+| `initialize`          | `Partial<InitializeRequest>`     | ACP initialization options. Defaults to Mastra client information and protocol version. |
+| `authMethodId`        | `string`                         | ACP authentication method ID to invoke after initialization.                            |
+| `persistSession`      | `boolean`                        | Keep the ACP process alive after execution. Defaults to `true`.                         |
+| `onPermissionRequest` | `(request) => Promise<Response>` | Callback for ACP permission requests. Defaults to selecting the first option.           |
+| `workspace`           | `Workspace`                      | Workspace used for ACP file reads and writes.                                           |
+
+## Session lifecycle
+
+`createACPTool` and `AcpAgent` start the configured command on first use and create an ACP session. By default, `persistSession` is `true`, so the child process stays alive across calls.
+
+Use the default persistent session when:
+
+- The ACP agent benefits from keeping conversation or repository context.
+- Startup is expensive and repeated calls should reuse the same process.
+- A parent agent may delegate several related tasks to the same coding agent.
+
+Set `persistSession: false` when each prompt should run in an isolated process:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP coding task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+})
+```
+
+With `persistSession: false`, `@mastra/acp` stops the ACP process after each prompt completes.
+
+## Permission handling
+
+ACP agents may ask the client to choose a permission option before they continue. By default, `@mastra/acp` selects the first option returned by the ACP agent.
+
+Pass `onPermissionRequest` to inspect the request and return the selected option yourself:
+
+```typescript
+import { createACPTool } from '@mastra/acp'
+
+export const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const allowOption = request.options.find(option => option.name === 'Allow')
+
+    if (!allowOption) {
+      return { outcome: { outcome: 'cancelled' } }
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+      },
+    }
+  },
+})
+```
+
+Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+
+## Workspace integration
+
+ACP file operations go through Mastra's workspace abstraction. If you don't pass `workspace`, `@mastra/acp` creates a `Workspace` backed by `LocalFilesystem` and uses `cwd` as the filesystem root.
+
+Pass a custom `Workspace` when the ACP agent should read and write through a specific filesystem implementation:
+
+```typescript
+import { AcpAgent } from '@mastra/acp'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    root: process.cwd(),
+  }),
+})
+
+export const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run coding tasks in a controlled workspace',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  workspace,
+})
+```
+
+Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+
+## Related
+
+- [Agent reference](https://mastra.ai/reference/agents/agent)
+- [Subagents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
+- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/docs/agents/agent-approval.md

@@ -92,6 +92,8 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
+> **Note:** `suspend()` does not throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
+
 ## Tool approval with `generate()`
 
 Tool approval also works with `generate()` for non-streaming use cases. When a tool requires approval, `generate()` returns immediately with `finishReason: 'suspended'`, a `suspendPayload` containing the tool call details (`toolCallId`, `toolName`, `args`), and a `runId`:

package/.docs/docs/agents/background-tasks.md

@@ -40,11 +40,12 @@ The full set of options is listed in the [backgroundTasks configuration referenc
 
 ## Run a tool in the background
 
-Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. You can run a tool in the background at one of three layers, in priority order:
+Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. Tools opt in at one of two layers:
 
-1. **LLM per-call override**: the model decides it should run in the background and includes a `_background` field in the tool arguments.
+1. **Tool-level config**: the tool itself declares it as background-eligible.
 2. **Agent-level config**: the agent declares which of its tools are background-eligible.
-3. **Tool-level config**: the tool itself declares it as background-eligible.
+
+Once a tool has opted in, the LLM can optionally include a `_background` field in the tool arguments to override the resolved config for a specific call (timeout, retries, or to flip the call back to foreground).
 
 ### Tool-level
 
@@ -103,13 +104,15 @@ When a tool is registered on an agent that has background tasks enabled, the mod
 }
 ```
 
+The `_background` override is a _modifier_ on tools the developer has already opted in at the tool or agent layer — it is not a standalone opt-in. If a tool hasn't been opted in, `_background.enabled: true` from the model is ignored and the tool runs in the foreground. This keeps deterministic, foreground-only tools (calculators, lookups, schema validators) from being silently dispatched as tasks.
+
 ### Resolution order
 
 When a tool call is dispatched, the resolved background config is computed in this priority order:
 
-1. LLM `_background` override (if present in the call's arguments).
-2. Agent-level `backgroundTasks.tools` entry for the tool.
-3. Tool-level `backgroundTasks` config.
+1. Agent-level `backgroundTasks.tools` entry for the tool.
+2. Tool-level `backgroundTasks` config.
+3. LLM `_background.enabled` override (only used to enable background dispatch when the tool was opted in at one of the layers above).
 4. Manager defaults (`defaultTimeoutMs`, `defaultRetries`).
 
 If the agent has `backgroundTasks.disabled: true`, every tool call runs synchronously regardless of the layers above.

package/.docs/docs/agents/response-caching.md

@@ -1,5 +1,7 @@
 # Response Caching
 
+> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
 Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. Mastra doesn't provide an agent-level option. To enable caching, register the processor explicitly. This keeps the API surface small while Mastra collects feedback; per-call overrides flow through `RequestContext`.

package/.docs/docs/agents/signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** Agent signals are experimental. Breaking changes may occur without a major version bump until the API is stable.
+> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
 
@@ -86,6 +86,32 @@ agent.sendSignal(
 )
 ```
 
+## Identify users with attributes
+
+Use `attributes` to tag each signal with user identity. The signal type and attributes are rendered as XML so the model can distinguish who said what in a multi-user thread:
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'user',
+    contents: 'Can we simplify the API surface?',
+    attributes: { name: 'Devin', from: 'slack' },
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives:
+
+```xml
+<user name="Devin" from="slack">Can we simplify the API surface?</user>
+```
+
+The UI sees just the message contents but can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
+
 ## Send external event context
 
 Use custom signal types for system-generated context. Non-user signal types are rendered as XML-style user-role context so they can appear inside conversation history without looking like assistant output.
@@ -96,7 +122,7 @@ agent.sendSignal(
     type: 'system-reminder',
     contents: 'User X has left a new PR comment asking for a smaller API surface.',
     attributes: {
-      type: 'github',
+      source: 'github',
       pr: '123',
     },
   },
@@ -110,7 +136,7 @@ agent.sendSignal(
 The model receives the custom signal as context like this:
 
 ```xml
-<system-reminder type="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+<system-reminder source="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
 ```
 
 Use XML-safe signal type names and attribute names. Signal type names and attribute names can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.

package/.docs/docs/evals/evals-with-memory.md

@@ -0,0 +1,146 @@
+# Evals with memory
+
+Agents that use memory in `thread` scope — including observational memory — require a thread ID at run time. When an eval invokes the agent without one, you'll see:
+
+```text
+ObservationalMemory (scope: 'thread') requires a threadId, but none was found in RequestContext or MessageList.
+```
+
+This page covers the three working patterns for running Mastra evals against memory-enabled agents, what each path supports, and which one to pick. A complete runnable repro for all three approaches lives in [`examples/evals-with-memory`](https://github.com/mastra-ai/mastra/tree/main/examples/evals-with-memory).
+
+## When to use which approach
+
+| Goal                                            | Approach                                                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| One shared conversation across every item       | [`runEvals` with global `targetOptions.memory`](#shared-thread-with-runevals)             |
+| One independent thread per item, simple CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
+| Per-item threads driven by a stored `Dataset`   | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
+
+Pre-seeding `RequestContext` with `MastraMemory` is **not** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
+
+## Shared thread with `runEvals`
+
+`runEvals` accepts `targetOptions`, which is forwarded to `agent.generate()`. Passing `memory: { thread, resource }` runs every data item against the same thread — useful for testing recall across a multi-turn conversation.
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { supportAgent } from './support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+await memory!.createThread({ threadId: 'eval-thread', resourceId: 'ci-user' })
+
+const result = await runEvals({
+  target: supportAgent,
+  scorers: [recallScorer],
+  targetOptions: {
+    memory: { thread: 'eval-thread', resource: 'ci-user' },
+  },
+  data: [
+    { input: 'My order number is 12345' },
+    { input: 'What is my order number?', groundTruth: '12345' },
+  ],
+})
+```
+
+`targetOptions` is **global per call**. There is no per-item override on `RunEvalsDataItem` today.
+
+## Per-item threads with `runEvals`
+
+When each data item needs its own thread (the common CI shape), call `runEvals` once per item with a unique `targetOptions.memory` and aggregate the scores yourself.
+
+```typescript
+import { randomUUID } from 'node:crypto'
+import { runEvals } from '@mastra/core/evals'
+import { supportAgent } from './support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+const resourceId = 'ci-user'
+
+const items = [
+  { input: 'Cats are mammals', groundTruth: 'mammals' },
+  { input: 'Dogs are mammals too', groundTruth: 'mammals' },
+]
+
+// `runEvals` returns `{ scores: Record<string, number>; summary: { totalItems } }`.
+const scores: number[] = []
+for (const item of items) {
+  const threadId = `eval-${randomUUID()}`
+  await memory!.createThread({ threadId, resourceId, title: item.input })
+
+  const result = await runEvals({
+    target: supportAgent,
+    scorers: [recallScorer],
+    targetOptions: { memory: { thread: threadId, resource: resourceId } },
+    data: [item],
+  })
+
+  scores.push(result.scores[recallScorer.id])
+}
+
+const average = scores.reduce((a, b) => a + b, 0) / scores.length
+```
+
+> **Note:** Create the thread before running the eval. Observational memory in `thread` scope reads from a record that must already exist.
+
+## Dataset experiments with an inline task
+
+`dataset.startExperiment({ target: agent })` does **not** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+
+```typescript
+import { randomUUID } from 'node:crypto'
+import { mastra } from '../index'
+import { supportAgent } from '../agents/support-agent'
+import { recallScorer } from '../scorers/recall-scorer'
+
+const memory = await supportAgent.getMemory()
+const resourceId = 'ci-user'
+
+const items = [
+  { input: 'Cats are mammals', groundTruth: 'mammals', thread: `ds-${randomUUID()}` },
+  { input: 'Dogs are mammals too', groundTruth: 'mammals', thread: `ds-${randomUUID()}` },
+]
+
+for (const it of items) {
+  await memory!.createThread({ threadId: it.thread, resourceId, title: it.input })
+}
+
+const dataset = await mastra.datasets.create({
+  name: 'support-recall',
+  description: 'Per-item memory via inline task + item metadata',
+})
+
+await dataset.addItems({
+  items: items.map(it => ({
+    input: it.input,
+    groundTruth: it.groundTruth,
+    metadata: { threadId: it.thread, resourceId },
+  })),
+})
+
+const summary = await dataset.startExperiment({
+  scorers: [recallScorer],
+  task: async ({ input, metadata }) => {
+    const { threadId, resourceId: rid } = (metadata ?? {}) as {
+      threadId: string
+      resourceId: string
+    }
+    const result = await supportAgent.generate(input as string, {
+      memory: { thread: threadId, resource: rid },
+    })
+    return result.text
+  },
+})
+```
+
+The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer.
+
+> **Note:** Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
+
+## Related
+
+- [Running scorers in CI](https://mastra.ai/docs/evals/running-in-ci)
+- [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- [runEvals API reference](https://mastra.ai/reference/evals/run-evals)

package/.docs/docs/evals/running-in-ci.md

@@ -121,4 +121,5 @@ describe('Weather Agent Tests', () => {
 
 - Learn about [creating custom scorers](https://mastra.ai/docs/evals/custom-scorers)
 - Explore [built-in scorers](https://mastra.ai/docs/evals/built-in-scorers)
+- Run scorers against [memory-enabled agents](https://mastra.ai/docs/evals/evals-with-memory)
 - Read the [runEvals API reference](https://mastra.ai/reference/evals/run-evals)