## Description
`createACPTool()` and `AcpAgent` hardcoded the ACP client inside
`ACPConnection`, so there was no way to answer agent-initiated extension
methods (`extMethod` / `extNotification`). Agents that use them (e.g.
Grok CLI) fail — the default client rejects any custom method with
JSON-RPC `-32601 "Method not found"` and the agent aborts its turn — and
the only workaround was forking ~300 lines of connection/spawn/stream
plumbing just to swap one class. This PR exposes the injection point the
underlying `@agentclientprotocol/sdk` already has.
- Add `createClient?: (defaultClient: Client) => Client` to
`CreateACPToolOptions` (inherited by `AcpAgentOptions`); the callback
receives the default client so it can be wrapped/extended or fully
replaced, and the returned client is passed to `ClientSideConnection`
- Re-export the SDK `Client` type from `@mastra/acp` for fully custom
implementations
- Handle child-process spawn failures: previously a bad `command`
(ENOENT) emitted an unhandled `'error'` event and crashed the host
process; initialization is now raced against process `error`/`exit` so
the tool call rejects with the spawn error (stderr attached) instead
- Extract the init sequence into `initializeSession()` so it can be
raced; default-path behavior is unchanged
- Tests: mock child process is now an `EventEmitter`; 4 new tests cover
custom client wiring (ext methods handled, default handlers preserved),
omitted option, spawn ENOENT rejection, and early process exit
- Docs: `createClient` parameter on both reference pages plus a new
"Extension methods" section with a usage example
Verified end-to-end: a protocol-exact fake agent calling `_grok/ping`
fails on main and succeeds with `createClient`; a real ACP agent
(`@zed-industries/claude-code-acp`, live Anthropic API) works on both
the default and wrapped-client paths; full customer-shaped run (real
model → Mastra agent loop → tool-call → ACP process → ext method
answered → output returned) passes.
## Related Issue(s)
Fixes#19109
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This update lets you plug in your own “ACP client” so the SDK can handle
agent requests your way (including custom extension actions), without
you having to copy the SDK’s complex connection code. It also prevents
agent startup failures from crashing your app by turning
spawn/early-exit problems into normal rejected tool calls.
## What changed
- Added an optional `createClient` hook to `createACPTool()` /
`CreateACPToolOptions`, and it’s inherited by `AcpAgentOptions`.
- The factory receives the SDK’s default ACP `Client` and can
wrap/extend/replace it (enabling custom extension handlers like
`extMethod` and `extNotification`).
- Re-exported the ACP `Client` type from `@mastra/acp` to support fully
custom client implementations.
- Fixed child-process failure handling during initialization:
- Initialization failures now reject tool calls with
spawn/initialization errors instead of causing unhandled host-process
crashes.
- Agent startup failure detection was implemented using
`initializeSession()` and failure/early-exit handling; cleanup is added
when the client factory throws.
- Added tests for:
- custom client wiring + extension availability
- omitted options (default behavior)
- client-factory errors (including cleanup)
- spawn failures (`error` event)
- early process exits (`exit` during initialization)
- Updated documentation for `createClient` and added an “Extension
methods” section with an example.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This fixes ACP tool session persistence so a single `createACPTool`
instance reuses its ACP connection across executions by default.
`persistSession: false` still keeps prompts isolated by creating and
disconnecting a fresh connection each time.
Before, repeated calls to the same ACP tool started a new ACP connection
even though sessions were documented as persistent. After this change,
repeated calls through the same tool instance share the session/process
unless persistence is disabled.
Test plan:
- `pnpm --filter ./packages/acp test`
- `pnpm --filter ./packages/acp build:lib`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Imagine you're using a tool that needs to talk to an AI assistant.
Before this change, every time you used the tool, it would hang up and
make a brand new phone call. Now, it stays on the same call the whole
time (unless you specifically ask it to hang up), which is faster and
lets the assistant remember what you've been talking about.
## Overview
This PR fixes ACP tool session persistence to ensure a single
`createACPTool` instance reuses its ACP connection across multiple
executions by default, rather than creating a new connection each time.
## Changes
### Core Implementation
**New `ACPToolSession` class** (`agent-sdks/acp/src/session.ts`):
- Manages connection lifecycle for ACP tools
- `getConnection(workspace)` returns a fresh connection when
`persistSession === false`, otherwise lazily creates and caches a
connection on first use and reuses it for all subsequent calls
- `createConnection(workspace)` helper constructs the `ACPConnection`
with proper workspace resolution
**Updated `createACPTool` function** (`agent-sdks/acp/src/tool.ts`):
- Now instantiates an `ACPToolSession` from provided options
- Tool's `execute` handler calls `session.getConnection(workspace)`
instead of directly creating new `ACPConnection` instances
### Testing
**New test coverage** (`agent-sdks/acp/src/__tests__/tool.test.ts`):
- Verifies default session reuse: repeated `execute` calls with the same
tool instance reuse the same `sessionId`
- Verifies non-persistent mode: when `persistSession: false`, each
`execute` creates a fresh connection and calls process `kill`
- Confirms ACP file access uses the runtime Mastra workspace by mocking
`mastra.getWorkspace().filesystem.readFile`
### Documentation
**Changeset** (`.changeset/free-doors-laugh.md`):
- Patch version bump for `@mastra/acp`
- Documents fix ensuring ACP tools keep their default session alive
across executions
## Impact
Fixes prior behavior where repeated calls to the same ACP tool started a
new ACP connection despite sessions being documented as persistent.
After this change, repeated calls through the same tool instance share
the session/process by default, unless `persistSession: false` is
explicitly set.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>