[OndrejDrapalik]

Moved from #2025 so CI runs with repo secrets: GitHub does not pass them to PRs from forks. Same branch and commits by @max-sudolabs, history kept. Review threads are on #2025.

Summary

Adds @e2b/acp (packages/acp-js) for running Agent Client Protocol agents (goose, OpenCode, Claude Code through its ACP adapter) inside an E2B sandbox and driving them with the official TypeScript ACP client, @agentclientprotocol/sdk (peer dependency).

ACPAgent.start(sandbox, command, client, opts?) starts the agent with stdin open, speaks newline-delimited JSON-RPC over its stdin/stdout, connects your client() app from the ACP SDK to it, and returns an ACPAgent with the ClientConnection plus pid, wait(), stop() and kill(). The client filesystem and terminal capabilities are turned off in initialize, and agent requests for fs/* / terminal/* are rejected in the transport, so the agent edits files and runs commands with its own tools inside the sandbox. Network access and MCP servers passed to the agent are not restricted.

The agent is started with commands.run(cmd, { background: true, retainOutput: false }) from #2044 (SDK-407), so a long-running agent does not grow the handle's buffers. No core changes. SDK-408 tracks dropping retained output for background commands in the next major.

Split out of #1992 together with the Python package (#2061). The two PRs are independent and can merge in either order.

Usage

import { Sandbox } from 'e2b'
import { ACPAgent } from '@e2b/acp'
import { client, methods, PROTOCOL_VERSION } from '@agentclientprotocol/sdk'

const app = client()
  .onRequest(methods.client.session.requestPermission, async ({ params }) => ({
    outcome: { outcome: 'selected', optionId: params.options[0].optionId },
  }))
  .onNotification(methods.client.session.update, ({ params }) => console.log(params.update))

const sandbox = await Sandbox.create('goose')
const agent = await ACPAgent.start(sandbox, 'goose acp --with-builtin developer', app, { envs })
try {
  await agent.connection.agent.request(methods.agent.initialize, { protocolVersion: PROTOCOL_VERSION })
  const { sessionId } = await agent.connection.agent.request(methods.agent.session.new, {
    cwd: '/home/user',
    mcpServers: [],
  })
  await agent.connection.agent.request(methods.agent.session.prompt, {
    sessionId,
    prompt: [{ type: 'text', text: 'Write fizzbuzz.py and run it' }],
  })
} finally {
  await agent.stop()
  await sandbox.kill()
}

Review guide

Worth reading (~686 lines):

File	Lines	What it holds
packages/acp-js/src/transport.ts	389	Process start, line framing, read queue, write queue, stop and kill
packages/acp-js/src/utils.ts	154	Incremental line splitter with size limit, initialize rewrite, fs/* / terminal/* rejection
packages/acp-js/src/index.ts	143	Public ACPAgent and ACPAgent.start

Skim: .github/workflows/acp_js_tests.yml and the ACP JS entries in sdk_tests.yml / release.yml (mirror code-interpreter), package.json, README, .changeset/acp-js-package.md.

For automated reviewers

Behaviour the code is meant to guarantee, and the test that fails if it breaks. Offline tests use a fake command handle and need no API key; live tests start a scripted Python agent in a sandbox.

Guarantee	Code	Test
Agent cannot use the client's filesystem or terminal: initialize forces them off (also inside a batch), agent fs/* / terminal/* requests get -32601, notifications are dropped	restrictClientCapabilities, filterAgentMessage	utils.test.ts; end to end in transport.test.ts
Client writes, automatic replies to the agent and EOF never interleave on stdin	enqueueWrite	offline: writes and replies never overlap
stop(timeoutMs): EOF and exit are bounded by timeoutMs from the call; then kill unless an exit status is known; rejects if the kill fails	ACPTransport.close	offline: close … tests
kill() releases output waiting on a full read queue, so the handle sees the exit and wait() resolves	ACPTransport.kill	offline: kill lets wait() see the exit
After stop(), messages already queued stay readable and later ones are dropped, including later lines of a chunk that was waiting on backpressure	closing checks in onStdout and deliver	offline: keeps buffered messages / drops later lines of a chunk
Read queue is bounded at 64 messages	CountQueuingStrategy + resumeReading	offline: full queue
One message is capped at 32 MiB by bytes, and the limit is validated; a long message is joined once, not rescanned per chunk	LineSplitter	utils tests (incl. 8 MiB in 1 KiB chunks); live: over the limit
A failed exit errors the stream with the exit code and the stderr tail	exit handler	live: agent failure
A failed output stream (aborted signal, throwing onStderr) kills the agent and keeps the original error	exit handler	offline: a failed output stream kills the agent
A throwing onConnect handler does not leak the started process; an oversized message that arrives before run() returns still stops the agent	ACPAgent.start, closeTransport	offline: start kills the agent when an onConnect handler throws / output over the limit before start returns
Closing the ClientConnection stops the agent	readable cancel / writable abort → closeTransport	offline: closing the connection stops the agent

Out of scope: restricting network or MCP, batch semantics beyond the boundary check, reconnecting to a running agent.

# offline, no key
pnpm --filter @e2b/acp exec vitest run tests/utils.test.ts tests/transport.offline.test.ts
# full, needs E2B_API_KEY
pnpm --filter @e2b/acp test

Testing

• @e2b/acp: 35 tests (unit, offline, live), typecheck and lint on this branch rebased on current main (includes feat(sdk): add retainOutput option to command handles #2044).
• Offline guards are checked by breaking each guard and confirming a test fails.
• After moving to ACPAgent.start and client(): goose with gpt-5.6-luna ran the README example end to end (file written, exit 0).
• Real agents through the package before that change: goose 1.54.0, OpenCode 1.19.0 and Claude Code (claude-agent-acp 0.90.0) wrote and ran a file in the sandbox. The client received no fs/* or terminal/* calls, and the agent process was gone after it was stopped.

Release notes for maintainers

• @e2b/acp depends on e2b through workspace:^, so it requires the core version released with it; it needs retainOutput from feat(sdk): add retainOutput option to command handles #2044, which is not released yet.
• npm @e2b/acp needs trusted publishing configured before the first release.
• Not wired yet: pkg_artifacts.yml preview builds (an ACP preview needs the matching preview core) and staging jobs in sdk_tests.yml. Happy to add either if you want them.

Co-authored-by: Maksim Obukhov maksimobukhov@sudolabs.io
Co-authored-by: Mish Ushakov 10400064+mishushakov@users.noreply.github.com
Co-authored-by: Ondrej Drapalik 43215019+OndrejDrapalik@users.noreply.github.com

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[linear-code]

INT-155

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-29T14:20:36.983286Z	336eea0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[changeset-bot]

🦋 Changeset detected

Latest commit: d477fbc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@e2b/acp	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Package Artifacts

Built from 3404a9d. Download artifacts from this workflow run.

JS SDK (e2b@2.62.1-int-155-acp-js.0, with @e2b/dockerfile-utils@0.1.2-int-155-acp-js.0):

npm install ./e2b-dockerfile-utils-0.1.2-int-155-acp-js.0.tgz ./e2b-2.62.1-int-155-acp-js.0.tgz

CLI (@e2b/cli@2.23.1-int-155-acp-js.0):

npm install ./e2b-cli-2.23.1-int-155-acp-js.0.tgz

Code Interpreter JS SDK (@e2b/code-interpreter@2.9.1-int-155-acp-js.0):

npm install ./e2b-code-interpreter-2.9.1-int-155-acp-js.0.tgz

Desktop JS SDK (@e2b/desktop@2.5.1-int-155-acp-js.0):

npm install ./e2b-desktop-2.5.1-int-155-acp-js.0.tgz

Python SDK (e2b==2.62.0+int.155.acp.js, with e2b-dockerfile-utils==0.1.1+int.155.acp.js):

pip install ./e2b_dockerfile_utils-0.1.1+int.155.acp.js-py3-none-any.whl ./e2b-2.62.0+int.155.acp.js-py3-none-any.whl

Code Interpreter Python SDK (e2b-code-interpreter==2.11.6+int.155.acp.js):

pip install ./e2b_code_interpreter-2.11.6+int.155.acp.js-py3-none-any.whl

Desktop Python SDK (e2b-desktop==2.7.2+int.155.acp.js):

pip install ./e2b_desktop-2.7.2+int.155.acp.js-py3-none-any.whl