Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
fix(sdk): correct filesystem watch handle callback and timeout behavior (#1480)
Mish Ushakovde0c401626c7
diff --git a/.changeset/watch-handle-fixes.md b/.changeset/watch-handle-fixes.mdnew file mode 100644index 000000000..4db54305e--- /dev/null+++ b/.changeset/watch-handle-fixes.md@@ -0,0 +1,10 @@+---+"@e2b/python-sdk": patch+"e2b": patch+---++Fix three filesystem watch handle bugs:++- **JS**: `WatchHandle` now awaits async `onEvent`/`onExit` callbacks. A rejecting async `onEvent` is routed to `onExit` and stops the watch instead of becoming an unhandled promise rejection that can crash Node, and async callbacks get backpressure/ordering — matching `CommandHandle`.+- **Python (sync)**: `WatchHandle.get_new_events()` and `stop()` now send a request timeout (default 60s, overridable via `request_timeout`) so a stalled call can't hang the thread forever, and include the authentication header so the polling/stop calls aren't sent unauthenticated on older envd.+- **Python (async)**: `AsyncWatchHandle` now invokes `on_exit` when the stream ends cleanly (with `None`) and when `stop()` is called, in addition to on error — matching the JS SDK.diff --git a/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts b/packages/js-sdk/src/sandbox/filesystem/watchHandle.tsindex 9d55573b6..cf16fc6a7 100644--- a/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts+++ b/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts@@ -109,6 +109,7 @@ export class WatchHandle {}private async handleEvents() {+ let iterationError: Error | undefinedtry {for await (const event of this.iterateEvents()) {const eventType = mapEventType(event.value.type)@@ -116,7 +117,11 @@ export class WatchHandle {continue}- this.onEvent?.({+ // Await the callback so an async `onEvent` that rejects is routed to+ // `onExit` below (instead of becoming an unhandled promise rejection+ // that can crash Node) and so the user can apply backpressure. Mirrors+ // `CommandHandle.handleEvents`.+ await this.onEvent?.({name: event.value.name,type: eventType,entry: event.value.entry@@ -124,9 +129,22 @@ export class WatchHandle {: undefined,})}- this.onExit?.()} catch (err) {- this.onExit?.(err as Error)+ iterationError = err as Error+ }++ try {+ // Invoke `onExit` exactly once: with the error when the watch ended+ // because of one, or with no argument on a clean end.+ if (iterationError) {+ await this.onExit?.(iterationError)+ } else {+ await this.onExit?.()+ }+ } catch {+ // `onExit` is the terminal callback; an error it throws has nowhere to+ // propagate in this detached handler, so it's swallowed to avoid an+ // unhandled promise rejection (the failure mode this guards against).} finally {this.handleStop()}diff --git a/packages/js-sdk/tests/sandbox/files/watchHandle.test.ts b/packages/js-sdk/tests/sandbox/files/watchHandle.test.tsnew file mode 100644index 000000000..d4c4dc4f1--- /dev/null+++ b/packages/js-sdk/tests/sandbox/files/watchHandle.test.ts@@ -0,0 +1,134 @@+import { describe, expect, it, vi } from 'vitest'++import { EventType } from '../../../src/envd/filesystem/filesystem_pb'+import {+ FilesystemEventType,+ WatchHandle,+} from '../../../src/sandbox/filesystem/watchHandle'++function filesystemEvent(name: string, type: EventType = EventType.WRITE) {+ return {+ event: {+ case: 'filesystem' as const,+ value: { name, type, entry: undefined },+ },+ }+}++function events(items: ReturnType<typeof filesystemEvent>[]) {+ async function* gen() {+ for (const item of items) {+ yield item as any+ }+ }+ return gen()+}++describe('WatchHandle', () => {+ it('awaits an async onEvent before finishing and firing onExit', async () => {+ let callbackStarted = false+ let releaseCallback: (() => void) | undefined+ const callbackBlocked = new Promise<void>((resolve) => {+ releaseCallback = resolve+ })++ const onEvent = async () => {+ callbackStarted = true+ await callbackBlocked+ }++ let exitCalled = false+ const onExit = () => {+ exitCalled = true+ }++ new WatchHandle(+ () => {},+ events([filesystemEvent('a.txt')]),+ onEvent,+ onExit+ )++ await vi.waitFor(() => {+ expect(callbackStarted).toBe(true)+ })+ // onExit must not fire while onEvent is still pending.+ expect(exitCalled).toBe(false)++ releaseCallback?.()+ await vi.waitFor(() => {+ expect(exitCalled).toBe(true)+ })+ })++ it('routes a rejecting async onEvent to onExit and stops the watch', async () => {+ const error = new Error('callback failed')++ let stopped = false+ let exitErr: Error | undefined | 'unset' = 'unset'++ new WatchHandle(+ () => {+ stopped = true+ },+ events([filesystemEvent('a.txt')]),+ async () => {+ throw error+ },+ (err) => {+ exitErr = err ?? undefined+ }+ )++ await vi.waitFor(() => {+ expect(exitErr).not.toBe('unset')+ })+ expect(exitErr).toBe(error)+ expect(stopped).toBe(true)+ })++ it('calls onExit with no argument when the stream ends cleanly', async () => {+ const received: FilesystemEventType[] = []+ let exitArgs: unknown[] | undefined++ new WatchHandle(+ () => {},+ events([filesystemEvent('a.txt')]),+ (event) => {+ received.push(event.type)+ },+ (...args: unknown[]) => {+ exitArgs = args+ }+ )++ await vi.waitFor(() => {+ expect(exitArgs).toBeDefined()+ })+ // No error is passed on a clean exit — onExit is called with zero args.+ expect(exitArgs).toEqual([])+ expect(received).toEqual([FilesystemEventType.WRITE])+ })++ it('does not let a throwing onExit become an unhandled rejection', async () => {+ let stopped = false++ new WatchHandle(+ () => {+ stopped = true+ },+ events([filesystemEvent('a.txt')]),+ () => {},+ () => {+ throw new Error('onExit failed')+ }+ )++ // handleStop runs after onExit, so observing the stop confirms the loop+ // ran the throwing onExit to completion. A leaked rejection would fail the+ // test run instead.+ await vi.waitFor(() => {+ expect(stopped).toBe(true)+ })+ })+})diff --git a/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py b/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.pyindex eb6dd82c2..63306ebc3 100644--- a/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py+++ b/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py@@ -639,7 +639,7 @@ class Filesystem:self,path: str,on_event: OutputHandler[FilesystemEvent],- on_exit: Optional[OutputHandler[Exception]] = None,+ on_exit: Optional[OutputHandler[Optional[Exception]]] = None,user: Optional[Username] = None,request_timeout: Optional[float] = None,timeout: Optional[float] = 60,@@ -652,7 +652,7 @@ class Filesystem::param path: Path to a directory to watch:param on_event: Callback to call on each event in the directory- :param on_exit: Callback to call when the watching ends+ :param on_exit: Callback to call when the watching ends. It receives the error that ended the watch, or `None` on a clean end or when `stop()` is called:param user: Run the operation as this user:param request_timeout: Timeout for the request in **seconds**:param timeout: Timeout for the watch operation in **seconds**. Using `0` will not limit the watch timediff --git a/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py b/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.pyindex 092b066f3..814b46508 100644--- a/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py+++ b/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py@@ -21,7 +21,7 @@ class AsyncWatchHandle:self,events: AsyncGenerator[WatchDirResponse, Any],on_event: OutputHandler[FilesystemEvent],- on_exit: Optional[OutputHandler[Exception]] = None,+ on_exit: Optional[OutputHandler[Optional[Exception]]] = None,check_health: Optional[Callable[[], Awaitable[Optional[bool]]]] = None,):self._events = events@@ -60,14 +60,38 @@ class AsyncWatchHandle:except Exception as e:raise await ahandle_rpc_exception_with_health(e, self._check_health)+ async def _call_on_exit(self, error: Optional[Exception]):+ if self._on_exit is None:+ return+ try:+ cb = self._on_exit(error)+ if inspect.isawaitable(cb):+ await cb+ except Exception:+ # `on_exit` is the terminal callback; an error it raises has nowhere+ # to propagate in this background task, so it's swallowed to avoid an+ # "Task exception was never retrieved" warning. A `CancelledError`+ # (a `BaseException`) is intentionally not caught here.+ pass+async def _handle_events(self):+ error: Optional[Exception] = Nonetry:async for event in self._iterate_events():cb = self._on_event(event)if inspect.isawaitable(cb):await cb+ except asyncio.CancelledError:+ # `stop()` cancels this task to end the watch. Treat it as a clean,+ # user-initiated end: fire `on_exit` (with no error), then propagate+ # the cancellation so the task still finishes as cancelled.+ await self._call_on_exit(None)+ raiseexcept Exception as e:- if self._on_exit:- cb = self._on_exit(e)- if inspect.isawaitable(cb):- await cb+ error = e++ # `on_exit` fires exactly once when the watch ends — with the error when+ # the stream failed, or with `None` on a clean end. This matches the JS+ # SDK, which calls `onExit()` after the loop completes and `onExit(err)`+ # on error.+ await self._call_on_exit(error)diff --git a/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py b/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.pyindex 69ed1a001..b652572f7 100644--- a/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py+++ b/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py@@ -700,5 +700,8 @@ class Filesystem:return WatchHandle(lambda: self._rpc,r.watcher_id,+ self._connection_config,+ self._envd_version,+ user,lambda: check_sandbox_health(self._envd_api),)diff --git a/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py b/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.pyindex 84370e013..7d14b25f0 100644--- a/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py+++ b/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py@@ -1,12 +1,15 @@from typing import Callable, List, Optional+from packaging.version import Version+from e2b import SandboxException+from e2b.connection_config import ConnectionConfig, Usernamefrom e2b.envd.filesystem import filesystem_connectfrom e2b.envd.filesystem.filesystem_pb2 import (GetWatcherEventsRequest,RemoveWatcherRequest,)-from e2b.envd.rpc import handle_rpc_exception_with_health+from e2b.envd.rpc import authentication_header, handle_rpc_exception_with_healthfrom e2b.sandbox.filesystem.filesystem import map_entry_infofrom e2b.sandbox.filesystem.watch_handle import FilesystemEvent, map_event_type@@ -23,31 +26,47 @@ class WatchHandle:self,get_rpc: Callable[[], filesystem_connect.FilesystemClient],watcher_id: str,+ connection_config: ConnectionConfig,+ envd_version: Version,+ user: Optional[Username] = None,check_health: Optional[Callable[[], Optional[bool]]] = None,):self._get_rpc = get_rpcself._watcher_id = watcher_id+ self._connection_config = connection_config+ self._envd_version = envd_version+ self._user = userself._check_health = check_healthself._closed = False- def stop(self):+ def stop(self, request_timeout: Optional[float] = None):"""Stop watching the directory.After you stop the watcher you won't be able to get the events anymore.++ :param request_timeout: Timeout for the request in **seconds**"""try:self._get_rpc().remove_watcher(- RemoveWatcherRequest(watcher_id=self._watcher_id)+ RemoveWatcherRequest(watcher_id=self._watcher_id),+ request_timeout=self._connection_config.get_request_timeout(+ request_timeout+ ),+ headers=authentication_header(self._envd_version, self._user),)except Exception as e:raise handle_rpc_exception_with_health(e, self._check_health)self._closed = True- def get_new_events(self) -> List[FilesystemEvent]:+ def get_new_events(+ self, request_timeout: Optional[float] = None+ ) -> List[FilesystemEvent]:"""Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up until now.+ :param request_timeout: Timeout for the request in **seconds**+:return: List of filesystem events"""if self._closed:@@ -55,7 +74,11 @@ class WatchHandle:try:r = self._get_rpc().get_watcher_events(- GetWatcherEventsRequest(watcher_id=self._watcher_id)+ GetWatcherEventsRequest(watcher_id=self._watcher_id),+ request_timeout=self._connection_config.get_request_timeout(+ request_timeout+ ),+ headers=authentication_header(self._envd_version, self._user),)except Exception as e:raise handle_rpc_exception_with_health(e, self._check_health)diff --git a/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py b/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.pyindex 40052669c..d447087cd 100644--- a/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py+++ b/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py@@ -277,22 +277,24 @@ def test_sync_pty_rpc_clients_are_bound_per_calling_thread(monkeypatch, test_apiassert pty._rpc is main_rpc-def test_sync_watch_handle_uses_calling_thread_rpc():+def test_sync_watch_handle_uses_calling_thread_rpc(test_api_key):class FakeRpc:def __init__(self, name):self.name = nameself.calls = []- def remove_watcher(self, request):+ def remove_watcher(self, request, **opts):self.calls.append(("remove", request.watcher_id))+ config = ConnectionConfig(api_key=test_api_key)+main_rpc = FakeRpc("main")worker_rpc = FakeRpc("worker")- handle = WatchHandle(lambda: main_rpc, "watcher-id")+ handle = WatchHandle(lambda: main_rpc, "watcher-id", config, ENVD_VERSION)handle.stop()assert main_rpc.calls == [("remove", "watcher-id")]- handle = WatchHandle(lambda: worker_rpc, "watcher-id")+ handle = WatchHandle(lambda: worker_rpc, "watcher-id", config, ENVD_VERSION)run_in_worker_thread(handle.stop)assert worker_rpc.calls == [("remove", "watcher-id")]diff --git a/packages/python-sdk/tests/test_watch_handle.py b/packages/python-sdk/tests/test_watch_handle.pynew file mode 100644index 000000000..2e49f4854--- /dev/null+++ b/packages/python-sdk/tests/test_watch_handle.py@@ -0,0 +1,214 @@+import asyncio++from packaging.version import Version++from e2b.connection_config import ConnectionConfig+from e2b.envd.filesystem import filesystem_pb2+from e2b.envd.versions import ENVD_DEFAULT_USER+from e2b.sandbox_async.filesystem.watch_handle import AsyncWatchHandle+from e2b.sandbox_sync.filesystem.watch_handle import WatchHandle+++def _fs_event(+ name: str,+ event_type=filesystem_pb2.EventType.EVENT_TYPE_WRITE,+) -> filesystem_pb2.WatchDirResponse:+ return filesystem_pb2.WatchDirResponse(+ filesystem=filesystem_pb2.FilesystemEvent(name=name, type=event_type)+ )+++# --- Sync WatchHandle: request timeout + auth header (bug 28) ---+++class _FakeSyncRpc:+ def __init__(self):+ self.calls = []++ def get_watcher_events(self, req, **opts):+ self.calls.append(("get_watcher_events", req, opts))+ return filesystem_pb2.GetWatcherEventsResponse(events=[])++ def remove_watcher(self, req, **opts):+ self.calls.append(("remove_watcher", req, opts))+ return filesystem_pb2.RemoveWatcherResponse()+++def _make_sync_handle(rpc, envd_version: Version, user=None) -> WatchHandle:+ return WatchHandle(+ get_rpc=lambda: rpc,+ watcher_id="watcher-1",+ connection_config=ConnectionConfig(),+ envd_version=envd_version,+ user=user,+ )+++def test_sync_get_new_events_passes_request_timeout_and_auth_header():+ rpc = _FakeSyncRpc()+ # envd < 0.4.0 has no default user, so the auth header must be sent.+ handle = _make_sync_handle(rpc, Version("0.3.0"))++ handle.get_new_events()++ name, _, opts = rpc.calls[0]+ assert name == "get_watcher_events"+ # A request timeout is always supplied so a stalled call can't hang forever.+ assert opts["request_timeout"] == 60.0+ assert opts["headers"].get("Authorization", "").startswith("Basic ")+++def test_sync_stop_passes_request_timeout_and_auth_header():+ rpc = _FakeSyncRpc()+ handle = _make_sync_handle(rpc, Version("0.3.0"))++ handle.stop()++ name, _, opts = rpc.calls[0]+ assert name == "remove_watcher"+ assert opts["request_timeout"] == 60.0+ assert opts["headers"].get("Authorization", "").startswith("Basic ")+++def test_sync_caller_supplied_request_timeout_is_forwarded():+ rpc = _FakeSyncRpc()+ handle = _make_sync_handle(rpc, ENVD_DEFAULT_USER)++ handle.get_new_events(request_timeout=5)+ handle.stop(request_timeout=7)++ assert rpc.calls[0][2]["request_timeout"] == 5+ assert rpc.calls[1][2]["request_timeout"] == 7+ # No explicit user on a recent envd → no auth header forced.+ assert "Authorization" not in rpc.calls[0][2]["headers"]+++# --- Async WatchHandle: on_exit lifecycle (bug 29) ---+++async def test_async_on_exit_fires_with_none_on_clean_end():+ async def events():+ yield _fs_event("a.txt")++ received = []+ exit_calls = []++ handle = AsyncWatchHandle(+ events=events(),+ on_event=received.append,+ on_exit=exit_calls.append,+ )++ await handle._wait++ assert [e.name for e in received] == ["a.txt"]+ assert exit_calls == [None]+++async def test_async_on_exit_fires_with_error_on_stream_error():+ error = RuntimeError("stream died")++ async def events():+ raise error+ yield # pragma: no cover - makes this an async generator++ exit_calls = []++ handle = AsyncWatchHandle(+ events=events(),+ on_event=lambda e: None,+ on_exit=exit_calls.append,+ )++ await handle._wait++ assert exit_calls == [error]+++async def test_async_on_exit_fires_on_stop():+ started = asyncio.Event()++ async def events():+ started.set()+ await asyncio.Event().wait() # block until cancelled by stop()+ yield # pragma: no cover - never reached++ exit_calls = []++ handle = AsyncWatchHandle(+ events=events(),+ on_event=lambda e: None,+ on_exit=exit_calls.append,+ )++ await started.wait()+ await handle.stop()++ assert exit_calls == [None]+++async def test_async_on_exit_awaits_async_callback():+ async def events():+ yield _fs_event("a.txt")++ exit_calls = []++ async def on_exit(err):+ exit_calls.append(err)++ handle = AsyncWatchHandle(+ events=events(),+ on_event=lambda e: None,+ on_exit=on_exit,+ )++ await handle._wait++ assert exit_calls == [None]+++async def test_async_on_exit_awaits_async_callback_on_stop():+ started = asyncio.Event()++ async def events():+ started.set()+ await asyncio.Event().wait() # block until cancelled by stop()+ yield # pragma: no cover - never reached++ exit_done = []++ async def on_exit(err):+ # A real suspension proves the cancellation path drives the async+ # callback to completion rather than dropping it mid-await.+ await asyncio.sleep(0)+ exit_done.append(err)++ handle = AsyncWatchHandle(+ events=events(),+ on_event=lambda e: None,+ on_exit=on_exit,+ )++ await started.wait()+ await handle.stop()++ assert exit_done == [None]+++async def test_async_on_exit_error_does_not_leak():+ async def events():+ yield _fs_event("a.txt")++ async def on_exit(err):+ raise RuntimeError("on_exit failed")++ handle = AsyncWatchHandle(+ events=events(),+ on_event=lambda e: None,+ on_exit=on_exit,+ )++ # A raising on_exit must not surface as an unretrieved task exception.+ await handle._wait+ assert handle._wait.done()+ assert handle._wait.exception() is None