@mastra/mcp-docs-server 1.1.42 → 1.1.43

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

@@ -1,8 +1,8 @@
-# ACP (Agent Client Protocol)
+# 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.
+ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.
 
 ## When to use ACP
 
@@ -23,14 +23,14 @@ The flow is:
 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`.
+6. Mastra returns the buffered output, emits streaming chunks, or handles permission input.
+7. The ACP connection stops the process after the prompt when `persistSession` is `false`; `AcpAgent` can keep a reusable process alive across calls by default.
 
 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`:
+Install `@mastra/acp` in a project that already uses `@mastra/core`. The package requires `@mastra/core` version `1.34.0` or later.
 
 **npm**:
 
@@ -58,14 +58,12 @@ 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.
+- [`createACPTool()`](https://mastra.ai/reference/acp/create-acp-tool): Create a Mastra tool that sends a `task` string to an ACP agent and returns an `output` string.
+- [`AcpAgent`](https://mastra.ai/reference/acp/acp-agent): Wrap an ACP agent as a Mastra subagent with `generate()` and `stream()` support.
 
 ## 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.
+Use `AcpAgent` when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent.
 
 ```typescript
 import { AcpAgent } from '@mastra/acp'
@@ -91,11 +89,11 @@ export const codeSupervisor = new Agent({
 })
 ```
 
-`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.
+See the [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent) for all options, methods, and configuration.
 
 ## 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:
+Use `createACPTool()` when the parent Mastra agent should decide when to call the ACP agent as a tool.
 
 ```typescript
 import { createACPTool } from '@mastra/acp'
@@ -120,171 +118,36 @@ export const codeSupervisor = new Agent({
 })
 ```
 
-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.                                           |
-| `model`               | `string`                         | Model ID to select after session creation via the ACP `session/set_model` method.       |
+See the [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool) for all options and configuration.
 
 ## Model selection
 
-ACP agents may expose selectable models. Instead of setting an environment variable like `ANTHROPIC_MODEL`, you can pass a `model` ID directly in the configuration.
-
-### Discover available models
-
-Call `getAvailableModels()` to see which models the ACP agent supports. This starts the agent process and returns the model list from the session:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-
-const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'An ACP-compatible coding agent',
-  command: 'claude',
-  args: ['--acp'],
-})
-
-const models = await codeAgent.getAvailableModels()
-// [{ modelId: 'claude-sonnet-4-20250514', name: 'Claude Sonnet' }, ...]
-```
-
-### Set the model
+ACP agents may expose selectable models. Pass `model` in the ACP configuration to select a model after session creation, or use `AcpAgent.getAvailableModels()` and `AcpAgent.setModel()` to manage models at runtime.
 
-Pass the `model` option to select a model at connection time:
-
-```typescript
-import { AcpAgent } from '@mastra/acp'
-
-export const codeAgent = new AcpAgent({
-  id: 'code-agent',
-  description: 'An ACP-compatible coding agent',
-  command: 'claude',
-  args: ['--acp'],
-  model: 'claude-sonnet-4-6',
-})
-```
-
-You can also change the model at runtime with `setModel()`:
-
-```typescript
-await codeAgent.setModel('claude-sonnet-4-6')
-```
-
-If the ACP agent advertises available models and your model ID doesn't match any of them, Mastra throws an error listing the valid options:
-
-```text
-Model "bad-model-id" is not available. Available models: claude-sonnet-4-20250514, claude-haiku-4-20250514
-```
-
-If the agent doesn't advertise a model list, the value is passed through without validation.
+See the [AcpAgent model management methods](https://mastra.ai/reference/acp/acp-agent) for examples.
 
 ## 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.
+`AcpAgent` starts the configured command on first use and creates an ACP session. By default, `persistSession` is `true`, so the child process stays alive across calls. Set `persistSession: false` when each prompt should run in an isolated process.
 
-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.
+See the [AcpAgent session lifecycle](https://mastra.ai/reference/acp/acp-agent) section for details.
 
 ## 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,
-      },
-    }
-  },
-})
-```
+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` when you need custom permission behavior.
 
-Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.
+See the [createACPTool() permission handling](https://mastra.ai/reference/acp/create-acp-tool) section for a complete example.
 
 ## 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,
-})
-```
+ACP file operations go through Mastra's workspace abstraction. `AcpAgent` can use a `workspace` option, and `createACPTool()` uses the current Mastra workspace from the tool execution context when one is available. Without a workspace, `@mastra/acp` falls back to a `Workspace` backed by `LocalFilesystem` at `cwd` or `process.cwd()`.
 
-Use `cwd` and `workspace` together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.
+See the [AcpAgent workspace integration](https://mastra.ai/reference/acp/acp-agent) section for custom workspace examples.
 
 ## Related
 
+- [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent)
+- [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
 - [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)

package/.docs/docs/agents/processors.md

@@ -425,6 +425,149 @@ Add `ProviderHistoryCompat` explicitly when you need provider history compatibil
 
 See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processors/provider-history-compat) for setup, built-in rules, and custom rule options.
 
+## Response caching
+
+> **Alpha:** 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`.
+
+### When to use response caching
+
+Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
+
+### Quickstart
+
+Add a `ResponseCache` to the agent's `inputProcessors` and pass any `MastraServerCache` as the backend. For development, `InMemoryServerCache` works out of the box:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+export const searchAgent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })], // 10 minutes
+})
+```
+
+The first call runs the LLM normally and writes the response to the cache. Subsequent calls with an identical resolved prompt return the cached response without invoking the LLM.
+
+### Per-call overrides via RequestContext
+
+Per-call config flows through `RequestContext`. Use `ResponseCache.context()` to build a fresh context, or `ResponseCache.applyContext()` to merge into one you already have:
+
+```typescript
+import { ResponseCache } from '@mastra/core/processors'
+import { RequestContext } from '@mastra/core/request-context'
+
+// Fresh context with the override
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom-key', bust: true }),
+})
+
+// Or merge into an existing context
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+Three fields are overridable per call:
+
+- `key`: String or function. Overrides the auto-derived cache key for this request only.
+- `scope`: String or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
+- `bust`: Boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
+
+`cache`, `ttl`, and `agentId` stay on the constructor. They're instance-level concerns and not safe to vary per call.
+
+### Tenant scoping
+
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically. Two users never see each other's cached responses.
+
+Override explicitly when you need a different scope:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: [
+    new ResponseCache({
+      cache,
+      scope: 'org-123', // explicit tenant scope
+    }),
+  ],
+})
+```
+
+Pass `scope: null` to deliberately share entries across all callers. Only use this for known-public, non-personalized content.
+
+### Custom cache backend
+
+`ResponseCache` accepts any `MastraServerCache`. For production, use `RedisCache` from `@mastra/redis`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ResponseCache } from '@mastra/core/processors'
+import { RedisCache } from '@mastra/redis'
+
+const cache = new RedisCache({ url: process.env.REDIS_URL })
+
+export const agent = new Agent({
+  name: 'Cached Agent',
+  instructions: '...',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache })],
+})
+```
+
+For a custom backend, extend `MastraServerCache` and implement its abstract methods (the processor only calls `get` and `set`).
+
+### How caching is implemented
+
+`ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
+
+This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model. The key is created _after_ memory has loaded and earlier input processors have run, and each step in an agentic tool loop is independently cached.
+
+### What's in the cache key
+
+When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
+
+#### Customize the cache key
+
+Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):
+
+```typescript
+import { ResponseCache, buildResponseCacheKey } from '@mastra/core/processors'
+
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    // Cache only on the model id and the resolved prompt tail — ignore
+    // step number, scope, etc.
+    key: ({ model, prompt }) => `qa:${model.modelId}:${JSON.stringify(prompt).slice(-200)}`,
+  }),
+})
+
+// Or reuse the deterministic helper while overriding individual fields:
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    key: inputs => buildResponseCacheKey({ ...inputs, scope: 'global' }),
+  }),
+})
+```
+
+If the function throws, the processor falls back to the default key derivation so the call still benefits from caching.
+
+### How cache hits work
+
+When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
+
+Cache writes happen after the response completes. Failed runs (errors, tripwire activations) aren't cached, so the next call retries cleanly.
+
 ## Advanced patterns
 
 ### Ensure a final response with `maxSteps`