@mastra/code-sdk 1.8.4-alpha.6 → 1.9.0-alpha.8

package/README.md

@@ -58,6 +58,196 @@ The handle stays in memory and isn't restart-safe. The plugin still owns its con
 
 `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](https://mastra.ai/reference/code-sdk/acp-server) for
+startup options, capabilities, and client behavior.
+
+Start the installed CLI with `mastracode --acp`, or start the SDK server directly:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```sh
+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:
+
+```sh
+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](https://agentclientprotocol.com/protocol/v1/overview).
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+1. Run the focused adapter tests and affected core tests.
+2. Build and typecheck the affected packages with matching workspace dependencies
+   in CI, then run this gate against the resulting SDK artifact.
+3. Smoke-test the packaged `mastracode --acp` entry in an ACP client with a real
+   authenticated provider, including a reply, approved and denied tools, and cancellation.
+4. 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.
+
 ## Documentation
 
 - [@mastra/code-sdk documentation](https://mastra.ai/reference/code-sdk/mount-agent-controller)

package/dist/acp/agent.d.ts

@@ -1,26 +1,39 @@
-import type { Agent, AgentSideConnection, InitializeRequest, InitializeResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, CancelNotification, ContentBlock } from '@agentclientprotocol/sdk';
+import type { Agent, AgentSideConnection, InitializeRequest, InitializeResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, CancelNotification, ContentBlock, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse } from '@agentclientprotocol/sdk';
 import type { AgentController, AgentControllerMode, Session } from '@mastra/core/agent-controller';
-/**
- * ACP Agent implementation that wraps a mastracode Controller.
- * Each instance represents one ACP connection from a client.
- */
+import type { ThinkingLevelSetting } from '../thinking.js';
+import type { AcpSkills } from './skills.js';
+export interface AcpSessionRuntime {
+    controller: AgentController;
+    session: Session;
+    modes: AgentControllerMode[];
+    getThinkingLevel?: () => ThinkingLevelSetting;
+    getSkills?: () => Promise<AcpSkills | undefined>;
+    cleanup?: () => Promise<void>;
+}
+export type AcpSessionFactory = (request: NewSessionRequest) => Promise<AcpSessionRuntime>;
+/** One ACP connection, with an independent Mastra Code runtime for each conversation. */
 export declare class MastraCodeAcpAgent implements Agent {
     private readonly connection;
-    private readonly controller;
-    private readonly session;
-    private readonly modes;
-    private readonly unsubscribeSessionEvents;
-    private readonly sessionMap;
-    private currentPromptState;
-    private promptMutex;
-    private getThreadIdOrThrow;
-    constructor(connection: AgentSideConnection, controller: AgentController, session: Session, modes: AgentControllerMode[]);
-    dispose(): void;
+    private readonly createSession;
+    private readonly sessions;
+    private readonly pendingCreations;
+    private readonly startupCleanupFailures;
+    private disposed;
+    private disposal?;
+    constructor(connection: AgentSideConnection, createSession: AcpSessionFactory);
+    private getSession;
+    private enqueue;
+    dispose(): Promise<void>;
     initialize(_request: InitializeRequest): Promise<InitializeResponse>;
     authenticate(): Promise<void>;
-    newSession(_request: NewSessionRequest): Promise<NewSessionResponse>;
+    newSession(request: NewSessionRequest): Promise<NewSessionResponse>;
+    private createNewSession;
+    private refreshCommands;
+    private configOptions;
+    private thinkingLevel;
+    setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
     prompt(request: PromptRequest): Promise<PromptResponse>;
-    cancel(_notification: CancelNotification): Promise<void>;
+    cancel(notification: CancelNotification): Promise<void>;
     setSessionMode(params: {
         sessionId: string;
         modeId: string;

package/dist/acp/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/acp/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAInG;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,KAAK;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,WAAW,CAAoC;IAEvD,OAAO,CAAC,kBAAkB;gBASxB,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,mBAAmB,EAAE;IAa9B,OAAO,IAAI,IAAI;IAIT,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAcpE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0CpE,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IAsEvD,MAAM,CAAC,aAAa,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,cAAc,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5E,wBAAwB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAK9F;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAY3E;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GACrD,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,mBAAmB,GAAG,SAAS,CAW3E"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/acp/agent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,YAAY,EAEZ,6BAA6B,EAC7B,8BAA8B,EAE/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAEnG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAM3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,oBAAoB,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACjD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAW3F,yFAAyF;AACzF,qBAAa,kBAAmB,YAAW,KAAK;IAQ5C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IARhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0C;IAC3E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAiB;IACxD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,CAAgB;gBAGd,UAAU,EAAE,mBAAmB,EAC/B,aAAa,EAAE,iBAAiB;IAGnD,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,OAAO;IASf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgClB,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQpE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAUrD,gBAAgB;YAkGhB,eAAe;IAa7B,OAAO,CAAC,aAAa;IAqCrB,OAAO,CAAC,aAAa;IAMf,sBAAsB,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,8BAA8B,CAAC;IA0BtG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;IA2DvD,MAAM,CAAC,YAAY,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BvD,cAAc,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,wBAAwB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAiB9F;AASD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAiB3E;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GACrD,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,mBAAmB,GAAG,SAAS,CAW3E"}