chore(sdk): share sandbox create response mapping and command handle setup

[devin-ai-integration]

Summary

Scheduled dead/duplicated-code sweep of packages/js-sdk/src, packages/python-sdk/e2b, packages/cli/src, using knip, tsc --noUnusedLocals/--noUnusedParameters, vulture, ruff (F/ARG) and jscpd. Generated clients (*.gen.ts, *_pb*, *_connect*, e2b/api/client, e2b/volume/client) were excluded. Every candidate was then grepped across the monorepo, its tests and the docs repo. Behaviour is unchanged. Nothing was removed or renamed in the public API.

This run found no new dead code. The tools flagged nothing in the JS SDK or CLI beyond what is already listed below. Everything vulture/ruff flagged in Python turned out to be either used or public API. This PR only fixes two duplications that were added or still exist since #1907. Per AGENTS.md, the response-mapping change is applied in JS too.

De-duplicated

• SandboxCreateResponse mapping: the same 15-line "API Sandbox model → SandboxCreateResponse" block (narrow domain / envd_access_token / traffic_access_token from Unset to None) was copied 6 times: _create_sandbox, _cls_connect and each _cls_fork result, in both sandbox_sync/sandbox_api.py and sandbox_async/sandbox_api.py. It is now one helper, to_sandbox_create_response(sandbox), in the shared e2b/sandbox/sandbox_api.py.
• JS equivalent: createSandbox, connectSandbox and each forkSandbox result in js-sdk/src/sandbox/sandboxApi.ts built the same object literal. They now call a module-private toSandboxCreateResponse(sandbox). The internal SandboxForkResponse type is now SandboxCreateResponse | Error, and neither type is exported.
• Commands._start / Commands.connect (sync and async): both ended with the same "read start event → extract_start_pid → build CommandHandle / on error close stream + handle_rpc_exception_with_health" block. It now lives in a private _create_handle(events, action, ...). This is the Python version of the JS Commands.createHandle from chore(sdk): remove dead constant/attribute and de-duplicate Commands handle setup #1907. The extract_start_pid error messages ("start process" / "connect to process") are kept.

Patch changeset for @e2b/python-sdk and e2b.

Not repeated here (already in open draft PRs)

#1766 and #1873 already cover the JS/Python uploadUrl/downloadUrl signing duplication, the JS volume/secret response tails, handleProcessStartEvent/handleWatchDirStartEvent, the CLI init/migrate language list and the CLI's superfluous exports. Those were not duplicated here.

Public-API candidates deliberately left in place

• Python Sandbox.default_sandbox_timeout: nothing reads it since Remove SDK-side defaults from API request payloads #1749, but it is a public class attribute and tests/test_client.py asserts it.
• Python secure= on Sandbox.create / JS SandboxOpts.secure: deprecated, accepted and ignored on purpose.
• Python sync stream_idle_timeout (Filesystem.read, Volume.read_file) and request_timeout (sync commands.connect/_start, pty.create/connect): the docstrings say these are ignored, and they are kept so the signatures match async.
• JS Sandbox.getMcpUrl()/getMcpToken(), deprecated SandboxApi.getFullInfo(), ConnectionConfig.envdPort, TemplateBase.toJSON(), LogEntry.toString(); Python get_mcp_url, ConnectionConfig.set_integration (used by tests/integrations).
• JS types that knip reports as unused exports (Branded, PtyCreateOpts, PtyConnectOpts, FilesystemRequestOpts, FilesystemListOpts, WatchOpts, SandboxUrlOpts, McpServer, GitHubMcpServer, CallableTemplate, DockerfileParse*, BasicBuildOptions, *Registry, UploadBody, VolumeApiPaths): they appear in public signatures and the generated SDK reference.
• Python DockerfFileFinalParserInterface: it is the return type of the DockerfileParserInterface.set_start_cmd protocol and appears in the docs.

Left as-is (not mechanical)

• Python Commands.kill / Pty.kill (and the JS Commands/Pty equivalents) are near-identical, but they sit on separate public classes.
• Python volume make_dir/get_info/update_metadata/write_file have similar response tails, but not identical ones: update_metadata skips the VolumeError check. Merging them would change behaviour.
• Template.build vs build_in_background share signature and docs only. CLI template delete/publish share a short interactive-selection block with different prompts.

Verification

• make lint, make format, make typecheck (ruff + ty) on python-sdk all pass.
• Offline: tests/shared, tests/test_*.py, sync/async test_config_propagation (734 passed).
• Live against E2B: sync/async commands/, test_connect, test_fork, test_create, test_snapshot, test_secure (93 passed).
• js-sdk: pnpm run format, pnpm run lint, pnpm run typecheck pass. vitest tests/sandbox/{create,connect,fork,apiDefaults,lifecyclePayload,lifecycleRequest,configPropagation,iam,onResumeRequest,snapshot-api,secure,snapshot,kill}.test.ts pass.

Link to Devin session: https://app.devin.ai/sessions/4e5922ccd81b4c6e83225fa6d158e84b
Open in Devin Desktop: https://app.devin.ai/desktop/session/4e5922ccd81b4c6e83225fa6d158e84b?variant=devin

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: d027dca

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

This PR includes changesets to release 2 packages

Name	Type
@e2b/python-sdk	Patch
e2b	Patch

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

[devin-ai-integration]

🔍 Devin Review: 1 flag

Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[github-actions]

Package Artifacts

Built from 68e65e0. Download artifacts from this workflow run.

JS SDK (e2b@2.52.1-devin-1791183890-sdk-dead-code.0):

npm install ./e2b-2.52.1-devin-1791183890-sdk-dead-code.0.tgz

CLI (@e2b/cli@2.21.1-devin-1791183890-sdk-dead-code.0):

npm install ./e2b-cli-2.21.1-devin-1791183890-sdk-dead-code.0.tgz

Code Interpreter JS SDK (@e2b/code-interpreter@2.8.1-devin-1791183890-sdk-dead-code.0):

npm install ./e2b-code-interpreter-2.8.1-devin-1791183890-sdk-dead-code.0.tgz

Desktop JS SDK (@e2b/desktop@2.4.1-devin-1791183890-sdk-dead-code.0):

npm install ./e2b-desktop-2.4.1-devin-1791183890-sdk-dead-code.0.tgz

Python SDK (e2b==2.52.0+devin.1791183890.sdk.dead.code):

pip install ./e2b-2.52.0+devin.1791183890.sdk.dead.code-py3-none-any.whl

Code Interpreter Python SDK (e2b-code-interpreter==2.10.1+devin.1791183890.sdk.dead.code):

pip install ./e2b_code_interpreter-2.10.1+devin.1791183890.sdk.dead.code-py3-none-any.whl

Desktop Python SDK (e2b-desktop==2.6.0+devin.1791183890.sdk.dead.code):

pip install ./e2b_desktop-2.6.0+devin.1791183890.sdk.dead.code-py3-none-any.whl

[devin-ai-integration]

TASTE.md review: complies, 0 violations. Checked T-1/T-2 (sync/async parity; shared logic goes in sandbox/), T-3a, T-18 (generated Sandbox model mapped to SDK-owned SandboxCreateResponse), T-28 (sync _create_handle doesn't take on_stdout/on_stderr/request_timeout, which T-28 allows), T-54 and T-69/T-71. The public surface is unchanged and both new helpers are internal.

Written by Devin

[claude]

LGTM — straightforward, behavior-preserving refactor.

What was reviewed: the new to_sandbox_create_response() helper in sandbox/sandbox_api.py and its six call sites in the sync/async sandbox_api.py create/connect/fork paths — the extracted logic is byte-for-byte identical to the inlined code it replaces, just parameterized by the sandbox object. The new _create_handle() in sync/async commands/command.py — compared the extracted try/except body against the original _start/connect implementations line by line; the only parameterized difference is the action string used in extract_start_pid error messages, and all other arguments (on_stdout/on_stderr in async, generator typing in sync) are threaded through unchanged.

Extended reasoning...

Single-commit, Python-SDK-only refactor touching sandbox_api.py (sync/async/shared) and commands/command.py (sync/async) to deduplicate repeated SandboxCreateResponse mapping and command-handle setup logic; no new logic, no touched auth/crypto surface, just code motion with a parameter added for the one varying string. Diffed each extracted block against its six prior inlined copies and confirmed exact equivalence, and a changeset is included as required by CLAUDE.md for python-sdk public-surface-adjacent changes even though behavior is unchanged.

[mishushakov]

check comments above

[devin-ai-integration]

@mishushakov Addressed Codex's parity comment in d027dca: the JS SDK now has the same shared toSandboxCreateResponse mapping as Python. The command handle dedupe already existed in JS (Commands.createHandle from #1907), so this PR now leaves the JS and Python SDKs aligned. I updated the PR description and changeset to match.

The earlier red Staging Python jobs came from staging infra, not this change: 500: Failed to place sandbox, xdist workers crashing, and a code-interpreter sandbox was not found error. The same suites passed on Production for both ubuntu and windows.

[devin-ai-integration]

CI on d027dca: 41 passed, 2 test jobs failed (plus the SDK Tests Status aggregate). I don't think either failure comes from this change:

• Staging / Python SDK (ubuntu): 1356 passed, 1 failed. test_snapshot_api.py::test_create_sandbox_from_snapshot got a 500: Error creating snapshot template from the staging API on create_snapshot. This PR doesn't touch snapshot code, and the same suite passed on staging Windows and on both production runners.
• Production / Desktop JS SDK – deno: all 19 tests passed. The suite failed because the afterAll in desktop-js/tests/client.test.ts timed out (10s) while closing its local mock HTTP server. Locally on this branch with deno, tests/client.test.ts passed 3/3 runs. The desktop node/bun/cloudflare runs passed.

A re-run of these two jobs should clear them.

Written by Devin