@mastra/acp 0.0.0-ag-example-20260516005230

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# @mastra/acp
+
+## 0.0.0-ag-example-20260516005230
+
+### Patch Changes
+
+- Updated dependencies [[`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`4d90188`](https://github.com/mastra-ai/mastra/commit/4d9018840fba28d40e9bc3238727bbc28b29e996), [`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`58aadb8`](https://github.com/mastra-ai/mastra/commit/58aadb8a2ab713c945df04351290bb572dffad21), [`2487b50`](https://github.com/mastra-ai/mastra/commit/2487b50af3b11dada6301afcb2f4da25612da1da), [`db58726`](https://github.com/mastra-ai/mastra/commit/db58726abd9cedd990ef40e85cec82aeb47594af), [`7c3a1ad`](https://github.com/mastra-ai/mastra/commit/7c3a1adedd155d126a15ad74b8985aa355af86e2), [`94556bf`](https://github.com/mastra-ai/mastra/commit/94556bffcf30aa1dae02662b80809df8957f81e1)]:
+  - @mastra/core@0.0.0-ag-example-20260516005230
+
+## 0.1.0
+
+### Minor Changes
+
+- You can now run ACP-compatible coding agents as Mastra tools or lightweight subagents. ACP agents support incremental response streaming and can be used anywhere Mastra accepts a `SubAgent`, including supervisor delegation and workflow steps. ([#16423](https://github.com/mastra-ai/mastra/pull/16423))
+
+  ```ts
+  import { createACPTool, AcpAgent } from '@mastra/acp';
+
+  export const codingTool = createACPTool({
+    id: 'coding-agent',
+    command: 'my-acp-agent',
+  });
+
+  export const codingAgent = new AcpAgent({
+    id: 'coding-agent',
+    command: 'my-acp-agent',
+  });
+  ```
+
+  You can also wire an `AcpAgent` into a supervisor or workflow as a `SubAgent`-compatible implementation:
+
+  ```ts
+  import { Agent } from '@mastra/core/agent';
+
+  export const supervisor = new Agent({
+    name: 'supervisor',
+    instructions: 'Delegate coding tasks to the ACP agent.',
+    model,
+    agents: {
+      codingAgent,
+    },
+  });
+  ```
+
+  Workflows and the Inngest workflow adapter now recognize `SubAgent`-compatible implementations when creating agent-backed workflow steps.
+
+### Patch Changes
+
+- Updated dependencies [[`20787de`](https://github.com/mastra-ai/mastra/commit/20787de5965234a1af28fe35f49437c537dbfa0d), [`784ad98`](https://github.com/mastra-ai/mastra/commit/784ad989549de91dc5d33ab8ef36caa6f7dcd34e), [`fceae1f`](https://github.com/mastra-ai/mastra/commit/fceae1f5f5db4722cb078a663c6eb4bd22944123), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bf02acb`](https://github.com/mastra-ai/mastra/commit/bf02acbb8a6110f638ac844e89f1ebf04cb7fe74), [`090a647`](https://github.com/mastra-ai/mastra/commit/090a647ba5a66d36f203f9f49457e03a1ff4e6fb), [`bdb4cbf`](https://github.com/mastra-ai/mastra/commit/bdb4cbf8ba4b685d7481f28bb9dc3de6c79c9ed2), [`0fd3fbe`](https://github.com/mastra-ai/mastra/commit/0fd3fbe40fb63657aedd72f6e7b38c8e8ee6940d), [`f84447d`](https://github.com/mastra-ai/mastra/commit/f84447d6c80f3471836a9b300d246b331fb47e0d), [`a1a5b3e`](https://github.com/mastra-ai/mastra/commit/a1a5b3e42ab2ca5161ea21db59ebf28442680fa7), [`af84f57`](https://github.com/mastra-ai/mastra/commit/af84f571ed762e92e8e61c5f9a72363520914274), [`8b3c6f9`](https://github.com/mastra-ai/mastra/commit/8b3c6f90f7879833ba7d1bc70937e1d8f69d0804), [`fed0475`](https://github.com/mastra-ai/mastra/commit/fed0475ccfea31e4fc251469ac05640d0742c1f0), [`0d53730`](https://github.com/mastra-ai/mastra/commit/0d53730c1ed87ef80c87caa5701c4170ea8028e6), [`522f44d`](https://github.com/mastra-ai/mastra/commit/522f44d947214bfc06cff50599bae1ef3494880d)]:
+  - @mastra/core@1.34.0
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- You can now run ACP-compatible coding agents as Mastra tools or lightweight subagents. ACP agents support incremental response streaming and can be used anywhere Mastra accepts a `SubAgent`, including supervisor delegation and workflow steps. ([#16423](https://github.com/mastra-ai/mastra/pull/16423))
+
+  ```ts
+  import { createACPTool, AcpAgent } from '@mastra/acp';
+
+  export const codingTool = createACPTool({
+    id: 'coding-agent',
+    command: 'my-acp-agent',
+  });
+
+  export const codingAgent = new AcpAgent({
+    id: 'coding-agent',
+    command: 'my-acp-agent',
+  });
+  ```
+
+  You can also wire an `AcpAgent` into a supervisor or workflow as a `SubAgent`-compatible implementation:
+
+  ```ts
+  import { Agent } from '@mastra/core/agent';
+
+  export const supervisor = new Agent({
+    name: 'supervisor',
+    instructions: 'Delegate coding tasks to the ACP agent.',
+    model,
+    agents: {
+      codingAgent,
+    },
+  });
+  ```
+
+  Workflows and the Inngest workflow adapter now recognize `SubAgent`-compatible implementations when creating agent-backed workflow steps.
+
+### Patch Changes
+
+- Updated dependencies [[`20787de`](https://github.com/mastra-ai/mastra/commit/20787de5965234a1af28fe35f49437c537dbfa0d), [`784ad98`](https://github.com/mastra-ai/mastra/commit/784ad989549de91dc5d33ab8ef36caa6f7dcd34e), [`0d53730`](https://github.com/mastra-ai/mastra/commit/0d53730c1ed87ef80c87caa5701c4170ea8028e6)]:
+  - @mastra/core@1.34.0-alpha.0

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+# @mastra/acp
+
+`@mastra/acp` connects Mastra to coding agents that implement the Agent Client Protocol (ACP). Use it to run an ACP-compatible agent from a Mastra tool or as a Mastra sub-agent.
+
+## Installation
+
+```bash
+npm install @mastra/acp
+```
+
+## Overview
+
+The package exports:
+
+- `createACPTool`: Creates a Mastra tool that sends a task to an ACP agent and returns the completed output.
+- `AcpAgent`: Wraps an ACP agent as a Mastra sub-agent with `generate()` and `stream()` support.
+
+Use `createACPTool` when the ACP agent should be callable as a tool. Use `AcpAgent` when the ACP agent should participate in Mastra agent delegation.
+
+## Create an ACP tool
+
+The following example creates a tool that starts an ACP-compatible agent process and sends the provided task to it.
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { createACPTool } from '@mastra/acp';
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent to make code changes',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+});
+
+export const agent = new Agent({
+  name: 'supervisor',
+  instructions: 'Use the code-agent tool when a task requires editing code.',
+  model,
+  tools: {
+    codeAgentTool,
+  },
+});
+```
+
+The tool accepts a `task` string and returns an `output` string.
+
+```typescript
+const result = await codeAgentTool.execute({
+  context: {
+    task: 'Update the README with setup instructions.',
+  },
+});
+
+console.log(result.output);
+```
+
+## Use an ACP agent as a sub-agent
+
+`AcpAgent` implements Mastra's `SubAgent` interface. Add it to another agent's `agents` configuration to let the supervisor delegate work to the ACP agent.
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { AcpAgent } from '@mastra/acp';
+
+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 supervisor = new Agent({
+  name: 'supervisor',
+  instructions: 'Delegate code editing tasks to the code-agent sub-agent.',
+  model,
+  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.
+
+## Configure permissions
+
+ACP agents may request permission before running actions. By default, `@mastra/acp` selects the first permission option. Pass `onPermissionRequest` to handle permission requests yourself.
+
+```typescript
+import { createACPTool } from '@mastra/acp';
+
+const codeAgentTool = createACPTool({
+  id: 'code-agent',
+  description: 'Use an ACP-compatible coding agent',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  async onPermissionRequest(request) {
+    const option = request.options.find(option => option.name === 'Allow');
+
+    if (!option) {
+      return { outcome: { outcome: 'cancelled' } };
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: option.optionId,
+      },
+    };
+  },
+});
+```
+
+## Session and workspace behavior
+
+`createACPTool` and `AcpAgent` start the configured command on first use and create an ACP session. Sessions persist across calls by default. Set `persistSession: false` to stop the ACP process after each prompt.
+
+```typescript
+const codeAgent = new AcpAgent({
+  id: 'code-agent',
+  description: 'Run one isolated ACP task',
+  command: 'acp-agent',
+  args: ['--stdio'],
+  cwd: process.cwd(),
+  persistSession: false,
+});
+```
+
+By default, the ACP workspace uses `cwd` as its filesystem root. Pass a Mastra `Workspace` with a custom filesystem when you need explicit workspace control.
+
+## Configuration
+
+`createACPTool` and `AcpAgent` accept the same ACP connection options.
+
+| Option                | Type                             | Description                                                                            |
+| --------------------- | -------------------------------- | -------------------------------------------------------------------------------------- |
+| `id`                  | `string`                         | Unique tool or sub-agent identifier.                                                   |
+| `description`         | `string`                         | Description shown to the model when it can call the tool or delegate to the sub-agent. |
+| `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 and default workspace.                           |
+| `session`             | `Partial<NewSessionRequest>`     | ACP session creation options.                                                          |
+| `initialize`          | `Partial<InitializeRequest>`     | ACP initialization options.                                                            |
+| `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.                                                  |
+| `workspace`           | `Workspace`                      | Workspace used for ACP file reads and writes.                                          |
+
+`AcpAgent` also accepts `name` to set the display name used by Mastra agent delegation.

package/dist/agent.d.ts

@@ -0,0 +1,30 @@
+import type { AgentGenerateOptions, AgentStreamOptions, SubAgent, SubAgentGenerateResult, SubAgentStreamResult } from '@mastra/core/agent';
+import type { MessageListInput } from '@mastra/core/agent/message-list';
+import type { Mastra } from '@mastra/core/mastra';
+import type { DynamicArgument } from '@mastra/core/types';
+import { ACPConnection } from './connection.js';
+import type { CreateACPToolOptions } from './types.js';
+export type AcpAgentOptions = CreateACPToolOptions & {
+    name?: string;
+};
+export declare class AcpAgent<TId extends string = string, TRequestContext extends Record<string, any> | unknown = unknown> implements SubAgent<TId, TRequestContext> {
+    readonly id: TId;
+    readonly name: string;
+    readonly connection: ACPConnection;
+    readonly description: string;
+    constructor(options: AcpAgentOptions);
+    __registerMastra(_mastra: Mastra): void;
+    getDescription(): string;
+    getModel(): ReturnType<SubAgent<TId, TRequestContext>['getModel']>;
+    hasOwnMemory(): boolean;
+    __setMemory(_memory: DynamicArgument<any, any>): void;
+    getMemory(): undefined;
+    getInstructions(): string;
+    generate(messages: MessageListInput, options?: AgentGenerateOptions): Promise<SubAgentGenerateResult>;
+    resumeGenerate(): Promise<SubAgentGenerateResult>;
+    resumeStream(): Promise<SubAgentStreamResult>;
+    stream(messages: MessageListInput, options?: AgentStreamOptions): Promise<SubAgentStreamResult>;
+    private getPrompt;
+    private createMessageList;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EAEpB,kBAAkB,EAElB,QAAQ,EACR,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AA0BpD,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,QAAQ,CACnB,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,eAAe,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,GAAG,OAAO,CAC/D,YAAW,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,eAAe;IAOpC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAEvC,cAAc,IAAI,MAAM;IAIxB,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,UAAU,CAAC,CAAC;IAIlE,YAAY,IAAI,OAAO;IAIvB,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IAErD,SAAS,IAAI,SAAS;IAItB,eAAe,IAAI,MAAM;IAInB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmBrG,cAAc,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAIjD,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAI7C,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsErG,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,iBAAiB;CAM1B"}

package/dist/connection.d.ts

@@ -0,0 +1,31 @@
+import type { SessionUpdate } from '@agentclientprotocol/sdk';
+import type { CreateACPToolOptions } from './types.js';
+export type ACPStreamEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'session-update';
+    update: SessionUpdate;
+};
+export declare class ACPConnection {
+    readonly options: CreateACPToolOptions;
+    private agentProcess?;
+    private connection?;
+    private session?;
+    private initializePromise?;
+    private currentPrompt?;
+    private stderr;
+    constructor(options: CreateACPToolOptions);
+    get sessionId(): string | undefined;
+    prompt(task: string, signal?: AbortSignal): Promise<string>;
+    promptStream(task: string, signal?: AbortSignal): AsyncGenerator<ACPStreamEvent>;
+    cancel(): Promise<void>;
+    disconnect(): void;
+    private ensureConnected;
+    private initialize;
+    private getInitializeRequest;
+    private getNewSessionRequest;
+    private throwIfPromptDidNotComplete;
+    private withStderr;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAYV,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAuEhH,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAEvC,OAAO,CAAC,YAAY,CAAC,CAAiC;IACtD,OAAO,CAAC,UAAU,CAAC,CAAuB;IAC1C,OAAO,CAAC,OAAO,CAAC,CAAqB;IACrC,OAAO,CAAC,iBAAiB,CAAC,CAAgB;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAc;IACpC,OAAO,CAAC,MAAM,CAAM;gBAER,OAAO,EAAE,oBAAoB;IAIzC,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAY1D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC;IAgEjF,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,UAAU,IAAI,IAAI;YAaJ,eAAe;YASf,UAAU;IA0CxB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,2BAA2B;IAQnC,OAAO,CAAC,UAAU;CAanB"}