fix(js-sdk): treat a watch stopped via handle.stop() as a clean exit

.changeset/watch-stop-clean-exit.md

@@ -0,0 +1,5 @@
+---
+"e2b": patch
+---
+
+Fire the filesystem watch `onExit` callback with no error when the watch is stopped with `handle.stop()`. Stopping a watch aborts the underlying request, which the transport surfaces as a canceled error — the same code a request timeout maps to — so every clean, user-initiated stop reported a `TimeoutError` telling the user to raise `requestTimeoutMs`. The cancellation `stop()` itself triggers is now treated as the clean end of the watch, matching the Python SDK; a cancellation from anywhere else (e.g. a request timeout) still fires `onExit` with the error.

packages/js-sdk/src/sandbox/filesystem/watchHandle.ts

@@ -1,3 +1,5 @@
+import { Code, ConnectError } from '@connectrpc/connect'
+
 import {
   handleRpcErrorWithHealthCheck,
   SandboxHealthCheck,
@@ -77,6 +79,8 @@ export interface FilesystemEvent {
  * Use {@link WatchHandle.stop} to stop watching the directory.
  */
 export class WatchHandle {
+  private stopped = false
+
   constructor(
     private readonly handleStop: () => void,
     private readonly events: AsyncIterable<WatchDirResponse>,
@@ -91,6 +95,7 @@ export class WatchHandle {
    * Stop watching the directory.
    */
   async stop() {
+    this.stopped = true
     this.handleStop()
   }
 
@@ -104,6 +109,17 @@ export class WatchHandle {
         }
       }
     } catch (err) {
+      if (
+        this.stopped &&
+        err instanceof ConnectError &&
+        err.code === Code.Canceled
+      ) {
+        // stop() aborts the request, which the transport surfaces as a
+        // canceled error — the same code a request timeout maps to. That
+        // cancellation is the clean, user-initiated end of the watch, so end
+        // the stream without an error and let onExit fire with none.
+        return
+      }
       throw await handleRpcErrorWithHealthCheck(err, this.checkHealth)
     }
   }

packages/js-sdk/tests/sandbox/files/watchHandle.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it, vi } from 'vitest'
 
+import { Code, ConnectError } from '@connectrpc/connect'
+
 import { EventType } from '../../../src/envd/filesystem/filesystem_pb'
+import { TimeoutError } from '../../../src/errors'
 import {
   FilesystemEventType,
   WatchHandle,
@@ -110,6 +113,71 @@ describe('WatchHandle', () => {
     expect(received).toEqual([FilesystemEventType.WRITE])
   })
 
+  it('fires onExit with no error when stop() cancels the stream', async () => {
+    // stop() aborts the request, which the transport surfaces as a canceled
+    // ConnectError ("This operation was aborted"). The watch must treat that
+    // cancellation as the clean, user-initiated end — onExit with no error —
+    // not as the request-timeout error the canceled code maps to.
+    let abortStream: (() => void) | undefined
+    const streamAborted = new Promise<void>((resolve) => {
+      abortStream = resolve
+    })
+
+    async function* canceledOnStop() {
+      yield filesystemEvent('a.txt') as any
+      await streamAborted
+      throw new ConnectError('This operation was aborted', Code.Canceled)
+    }
+
+    let exitArgs: unknown[] | undefined
+
+    const handle = new WatchHandle(
+      () => abortStream?.(),
+      canceledOnStop(),
+      () => {},
+      (...args: unknown[]) => {
+        exitArgs = args
+      }
+    )
+
+    await handle.stop()
+
+    await vi.waitFor(() => {
+      expect(exitArgs).toBeDefined()
+    })
+    // A user-initiated stop is a clean end — onExit is called with zero args.
+    expect(exitArgs).toEqual([])
+  })
+
+  it('fires onExit with the error when the stream is canceled without stop()', async () => {
+    // Only the cancellation stop() itself triggers is a clean end. A
+    // cancellation from anywhere else (e.g. a request timeout aborting the
+    // signal) is still an error.
+    async function* canceledStream() {
+      yield filesystemEvent('a.txt') as any
+      throw new ConnectError(
+        'The operation was aborted due to timeout',
+        Code.Canceled
+      )
+    }
+
+    let exitErr: Error | undefined | 'unset' = 'unset'
+
+    new WatchHandle(
+      () => {},
+      canceledStream(),
+      () => {},
+      (err) => {
+        exitErr = err ?? undefined
+      }
+    )
+
+    await vi.waitFor(() => {
+      expect(exitErr).not.toBe('unset')
+    })
+    expect(exitErr).toBeInstanceOf(TimeoutError)
+  })
+
   it('does not let a throwing onExit become an unhandled rejection', async () => {
     let stopped = false