fix(sdks): raise typed, actionable errors when sandbox dies mid-request

[mishushakov]

Problem

When a sandbox is killed (or reaches its end of life) while a request is in flight, both SDKs surfaced unusable errors:

• JS: SandboxError: 2: [unknown] terminated — typed, but cryptic and says nothing about the sandbox being killed.
• Python: leaked a completely raw httpcore.RemoteProtocolError: <StreamReset stream_id:1, error_code:2, remote_reset:True>.

This affected the whole envd streaming family (commands.run, PTY sessions, files.watchDir/watch_dir) and the files.read/write HTTP transfers.

The stream-reset signature alone can't distinguish the sandbox dying from an intermediary (load balancer, network) dropping the connection — so the SDKs now actively check, and only transform the error when the sandbox is confirmed gone.

Fix

Health-check disambiguation. When the connection-terminated signature appears (JS: ConnectError Code.Unknown + terminated or Undici TypeError: terminated; Python: httpcore/httpx RemoteProtocolError), the SDK probes envd's /health endpoint:

• 502 (sandbox confirmed gone) → TimeoutError (JS) / TimeoutException (Python): "The sandbox was killed or reached its end of life while the request was in flight." This matches how requests to an already-dead sandbox surface today (the 502 / Code.Unavailable mappings raise the timeout error type), so the exception type no longer depends on whether the sandbox died just before or just during the request.
• Anything else (still running, or probe inconclusive) → the original error propagates unchanged, exactly as before this PR.

The probe (5s timeout) runs only on the termination signature, never on the happy path or for other errors. A health-check closure is plumbed into Commands/Pty/Filesystem and the command/watch handles in JS and sync/async Python; Commands/Pty now receive the envd API client in their constructors (internal signature change).

Cleanup (e2b_connect/client.py): removed the @_retry(RemoteProtocolError, 3) decorators from call_server_stream/acall_server_stream. They never executed — inspect.iscoroutinefunction is false for (async) generator functions, and calling a generator function doesn't run its body, so the wrapper's try/except could never fire. A working mid-stream retry would be wrong anyway (it would replay already-delivered events). Unary retries are unchanged.

Before / after

const sandbox = await Sandbox.create()
const cmd = await sandbox.commands.run('sleep 60', { background: true })
await sandbox.kill() // e.g. from another process
await cmd.wait()
// before: SandboxError: 2: [unknown] terminated
// after:  TimeoutError: [unknown] terminated: The sandbox was killed or reached
//         its end of life while the request was in flight.

sandbox = Sandbox.create()
cmd = sandbox.commands.run("sleep 60", background=True)
sandbox.kill()
cmd.wait()
# before: httpcore.RemoteProtocolError: <StreamReset stream_id:1, error_code:2, remote_reset:True>  (not an e2b type!)
# after:  e2b.exceptions.TimeoutException: <StreamReset ...>: The sandbox was killed
#         or reached its end of life while the request was in flight.

If the health probe does not confirm the sandbox is gone (e.g. a load balancer dropped the connection, or local envd in debug mode), the original error propagates unchanged — the SDK only makes a claim when it has verified it.

Notes

• Not covered: errors raised while consuming a format: 'stream' body after files.read returns (JS ReadableStream consumption happens in user code). Python is fully covered since httpx buffers non-streaming responses inside the request call.

Tests

• Unit: confirmed-kill → TimeoutError/TimeoutException, raw-error passthrough for running/unknown/probe-failure, health check skipped for unrelated errors — 28 Python + 25 JS assertions pass.
• Integration (run against live sandboxes, all passing): start sleep 60, kill the sandbox, assert wait() raises TimeoutError/TimeoutException with the confirmed kill message — JS, sync Python, and async Python.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 5520ce5

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

This PR includes changesets to release 2 packages

Name	Type
e2b	Patch
@e2b/python-sdk	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

[cursor]

PR Summary

Medium Risk
Broad error-path changes across streaming commands, PTY, filesystem, and watch in both SDKs; behavior only changes when health confirms the sandbox is dead, but mis-probes could affect error typing.

Overview
When a connection drops mid-request (streaming RPC for commands, PTY, directory watch, and HTTP filesystem read/write), both JS and Python SDKs now probe envd /health (5s timeout) only for the known “terminated” / stream-reset signatures. If the probe returns 502 (sandbox gone), callers get TimeoutError / TimeoutException with a message that the sandbox was killed or reached end of life—aligned with errors for requests to an already-dead sandbox. If the sandbox is still up or the probe is inconclusive, the original error is unchanged.

Health-check plumbing is wired through Commands, Pty, Filesystem, and command/watch handles; internal constructors now take the envd API client where needed for probes. Python sync Commands/Pty use thread-local httpx clients for health checks.

Python e2b_connect: removed non-functional @_retry on server-stream RPC helpers (generators never hit the wrapper); added a comment that mid-stream retry would replay events.

Unit and live-sandbox integration tests cover confirmed-kill vs passthrough behavior.

^{Reviewed by Cursor Bugbot for commit 5520ce5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Package Artifacts

Built from d5f2929. Download artifacts from this workflow run.

JS SDK (e2b@2.29.2-mishushakov-sandbox-kill-stream-errors.0):

npm install ./e2b-2.29.2-mishushakov-sandbox-kill-stream-errors.0.tgz

CLI (@e2b/cli@2.11.2-mishushakov-sandbox-kill-stream-errors.0):

npm install ./e2b-cli-2.11.2-mishushakov-sandbox-kill-stream-errors.0.tgz

Python SDK (e2b==2.28.2+mishushakov-sandbox-kill-stream-errors):

pip install ./e2b-2.28.2+mishushakov.sandbox.kill.stream.errors-py3-none-any.whl

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 32365fe. Configure here.}