|
History
|
||
|---|---|---|
| .. | ||
| scripts | ||
| src | ||
| CHANGELOG.md | ||
| lint-staged.config.js | ||
| oxlint.config.ts | ||
| package.json | ||
| README.md | ||
| tsconfig.acp.json | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| tsdown.config.ts | ||
| turbo.json | ||
| vitest.acp.config.ts | ||
| vitest.config.ts | ||
@mastra/code-sdk
The agent core behind Mastra Code — everything except the terminal UI. Use it to build your own UIs and surfaces (web apps, editors, bots) on top of the Mastra Code coding agent.
The published mastracode CLI/TUI and the Mastra Code web surface are both built on this SDK.
Installation
npm install @mastra/code-sdk
Usage
Mount the Mastra Code agent controller on a Mastra instance:
import { mountAgentControllerOnMastra } from '@mastra/code-sdk';
// Creates a Mastra instance that hosts the Mastra Code agent controller
// (thread management, modes, tools, memory) and starts its workers.
const { mastra, controller } = await mountAgentControllerOnMastra({
cwd: process.cwd(),
});
Plugin background execution
With the experimental backgroundTools.enabled setting on, plugin tools are eligible for native background execution only when they declare their own configuration:
background: {
enabled: true,
defaultDisposition: 'foreground',
maxRetries: 0,
}
The SDK doesn't infer support from tool names or serialize plugin calls. When the setting is off, it disables plugin-declared background execution without modifying the original tool.
Tools that already await their work need no separate execution path. For a tool that returns an acknowledgement while continuing independently, native execution exposes context.background. Adopt the existing operation before returning:
const operation = startResearch(input, context.abortSignal);
if (context.background) {
context.background.adopt({
completion: operation.finished,
cancel: reason => operation.cancel(reason),
});
return { answer: 'Research started' };
}
return await operation.finished;
Here, startResearch represents the plugin's own operation API. Its finished promise must resolve with the terminal tool result only after work and cleanup finish, or reject on failure. The native task tracks that promise instead of the acknowledgement. Adopt at most one operation, before execute() returns. Forward cancellation through the supplied signal or the operation's cancel callback. Without adoption, execute() must itself await the complete operation.
The handle stays in memory and isn't restart-safe. The plugin still owns its conversation-level queue and answer signals. Adoption doesn't suppress host completion notifications; keep progress rendering active until the adopted operation finishes.
defaultDisposition: 'foreground' preserves normal calls unless the caller explicitly requests _background.disposition: 'deferred' or 'awaited'. Plugins without a declaration remain usable in the foreground, including older versions of mastra_expert.
ACP server
See the ACP server reference for startup options, capabilities, and client behavior.
Start the installed CLI with mastracode --acp, or start the SDK server directly:
import { acpMain } from '@mastra/code-sdk/acp/index';
await acpMain();
The server uses newline-delimited JSON-RPC on standard input and output. Configure
provider authentication through Mastra Code before launching the client, or pass
API keys in the server's environment. ACP sessions do not load project .env
files into the shared process environment.
Each session/new creates its own runtime rooted at the request's absolute
cwd, including client-supplied MCP servers. Mode and model changes wait for
the current turn. Cancelling a session stops its active turn and cancels its
queued prompts.
Clients can use configOptions to select a model, mode, and requested reasoning
level. The reasoning choices follow Mastra Code's existing model policy; a
provider may adjust the requested level. For example:
await connection.setSessionConfigOption({
sessionId,
configId: 'thought_level',
value: 'high',
});
Tool approvals and sandbox access requests go through the client's permission
UI. The ask_user tool is disabled because ACP has no free-text tool response
method. Internal signals, including user input and system reminders, are not
sent as assistant messages. Failed turns return protocol errors.
Model choices include authenticated providers and the session's saved current
selection. Labels retain the full provider/model ID, so an OpenRouter route such
as openrouter/openai/gpt-4.1-mini cannot be confused with a Netlify route.
Unauthenticated gateway catalogs are omitted; stale model choices must be refreshed.
Session loading is not supported yet. Configure authentication outside ACP; the server does not advertise an interactive authentication method.
Skills
The server advertises workspace skills through available_commands_update when
a session starts and refreshes the list before each prompt. Clients that support
ACP command discovery can offer /skill/<name> completions. Skills marked
user-invocable: false are omitted and cannot be explicitly invoked this way.
Skills are resolved through Mastra Code's existing project and global skill directories.
Duplicate names use the first user-invokable file in the workspace's catalog order.
Send the command as an ordinary text prompt, optionally followed by arguments:
await connection.prompt({
sessionId,
prompt: [{ type: 'text', text: '/skill/review Check the current changes' }],
});
The server loads the named skill's instructions and resource listings into the
turn. Missing or hidden skills return an invalid-parameters error without
starting inference. Each session uses its own workspace. Terminal commands such
as /goal are not advertised or implemented by this command handler.
Focused adapter tests
From the repository root, install dependencies and build core with its dependencies before the first run:
pnpm turbo build --filter @mastra/core...
pnpm --filter @mastra/code-sdk test:acp
pnpm --filter @mastra/code-sdk check:acp
This suite runs the adapter and stdio protocol tests without building the TUI.
check:acp checks agent.ts, event-mapper.ts, server.ts, and skills.ts
against the repository's ES2023 library target. It does not check runtime.ts
or index.ts. Run pnpm --filter @mastra/code-sdk check for the full SDK
typecheck, including those entrypoints. CI runs the full check after building
the workspace dependencies.
It requires built workspace imports, including @mastra/core/workspace; the signal
factory alone is aliased to source. Runtime factory tests mock SDK startup. Use a running
ACP client to verify provider authentication and actual tool execution.
Build ACP without rebuilding the workspace
For local adapter development, bundle the SDK source against an existing installation of Mastra Code's published dependencies:
npm install --prefix /tmp/mastracode-runtime mastracode
pnpm --filter @mastra/code-sdk build:acp:dev /tmp/mastracode-runtime
node mastracode/sdk/node_modules/.acp-dev/local-acp.mjs
Point the ACP client's command at node with that generated file as its argument.
Rebuild after source changes. This development bundle uses absolute dependency
paths and is not a release artifact. It checks the local SDK against the installed
dependency versions; changes to other workspace packages still need their own
builds and tests.
Validate the ACP wire protocol
Mastra Code implements Agent Client Protocol v1.
The similarly named @acprotocol/conformance package tests Agent Control
Protocol, a different protocol, and cannot validate this server.
The Mastra Code CI job builds matching workspace packages, runs the SDK typecheck
and ACP unit tests, then tests the built SDK with the conformance gate. Reports
are uploaded as the acp-conformance artifact.
Run that same conformance gate locally against a built SDK:
pnpm --filter @mastra/code-sdk test:acp:conformance
Build the SDK and its relevant workspace dependencies first. The command fails
if dist/acp/index.js is missing. It downloads the upstream v1 schema at revision
367c56fb6115f391bc7550288363f87416cd0af8, verifies its SHA-256 checksum, and installs
locked AJV validators with lifecycle scripts disabled. The first run needs network
access. Generated files stay under node_modules/.acp-conformance. The command
runs EOF, SIGINT and SIGTERM shutdown checks sequentially, with one server process
at a time.
To check a development bundle instead:
pnpm --filter @mastra/code-sdk build:acp:dev /tmp/mastracode-runtime --local-core
pnpm --filter @mastra/code-sdk test:acp:conformance node_modules/.acp-dev/local-acp.mjs
--local-core also bundles local @mastra/core source. Other workspace dependencies
still come from the supplied installation. This keeps local verification small;
it does not establish that the publishable packages build together.
The checker validates actual stdio JSON-RPC messages with AJV, independently of the client's generated SDK validators. Local deterministic model and MCP fixtures exercise the real runtime without model credentials or inherited user credentials.
| Supported behavior | Verification |
|---|---|
| Initialization, protocol version, capabilities | Wire responses and upstream schemas |
| New sessions, absolute working directories, concurrent isolation | Separate runtime sessions and concurrent model requests |
| Text prompts, assistant streaming, usage and tool updates | Wire schemas and adapter regressions |
| Permissions | Approved writes execute; denied writes leave no file |
| Cancellation | Streaming, parked approvals, follow-up turns, and core startup regressions |
| MCP stdio | Real tool calls with session working directory and environment |
| MCP HTTP | Real tool calls with supplied headers |
| Modes, models and reasoning configuration | Selection validation, configuration updates and legacy mode notifications |
| Errors and stop reasons | Invalid requests, failed MCP setup, provider errors, token limits and refusals |
| Process lifecycle | Disconnect, SIGINT/SIGTERM, MCP child exit, protocol-only stdout |
Session loading/resuming, image/audio prompts, binary resources, interactive ACP authentication, and free-text tool questions are outside this release profile. They are not advertised as supported. Unsupported prompt attachments fail explicitly. Clients supply credentials through the existing Mastra Code setup.
node_modules/.acp-conformance/report/report.json records the checks, errors,
observed message count, and SHA-256 hashes of the schema, server entry and checker.
The EOF report is at that path; SIGINT and SIGTERM reports are in the
report/sigint and report/sigterm subdirectories. Checks assert that started MCP
children exit after failed initialization and final shutdown.
The server hash covers the selected entry file; for the default release wrapper, it does not fingerprint the entire dependency tree. Archive the package tarballs and lockfile alongside the report for release provenance. Nonzero exit, malformed stdout, timeout, or forced shutdown fails the gate.
Before publishing:
- Run the focused adapter tests and affected core tests.
- Build and typecheck the affected packages with matching workspace dependencies in CI, then run this gate against the resulting SDK artifact.
- Smoke-test the packaged
mastracode --acpentry in an ACP client with a real authenticated provider, including a reply, approved and denied tools, and cancellation. - Archive the reports with the exact package versions and checksums.
Passing this gate supports a claim of tested compatibility with the documented ACP v1 profile. It is not upstream certification or proof of every optional protocol feature. Live-provider authentication remains a separate integration test.
Experimental durable and evented agents
Mastra Code can run its coding agent through DurableAgent or EventedAgent for experimental validation. The experiment is off by default. Select an implementation with the MASTRACODE_EXPERIMENTAL_AGENT environment variable:
MASTRACODE_EXPERIMENTAL_AGENT=durable mastracode
MASTRACODE_EXPERIMENTAL_AGENT=evented mastracode
Or persist the selection in the Mastra Code settings file:
{
"experimentalAgent": "evented"
}
The environment variable takes precedence over the persisted setting. Unset the variable and store null to use the standard coding agent. Any other value fails at startup instead of silently disabling or changing the requested experiment.
The evented selection also fails at startup unless the agent is registered on a Mastra host whose workflow storage reports atomic concurrent-update support. LibSQL and PostgreSQL satisfy this requirement. On successful startup, Mastra Code prints the selected implementation and resolved workflow engine, for example Experimental agent: evented (workflow engine: evented).
This experiment does not make controller-local approvals or adopted background-operation handles restart-safe. Restarting the TUI still ends in-flight background operations, stale task recovery remains disabled, and distributed ownership, lease-loss, and pubsub limitations remain unchanged.
Documentation
Changelog
See the package changelog for version history and release notes.
Support
We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.