feat: add ExecStream class, dispose guard, and tsup npm packaging

Author: richiemcilroy

bun.lock

@@ -1,17 +1,36 @@
 {
   "name": "@sandchest/sdk",
-  "version": "0.0.1",
+  "version": "0.1.0",
+  "description": "Sandchest SDK — isolated Linux sandbox environments for AI agent code execution",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
+  "files": ["dist"],
+  "keywords": ["sandbox", "firecracker", "microvm", "code-execution", "mcp", "ai-agent"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sandchest/sandchest",
+    "directory": "packages/sdk-ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "build": "tsc",
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "bun test"
@@ -21,6 +40,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",
-    "@types/node": "^25.3.0"
+    "@types/node": "^25.3.0",
+    "tsup": "^8.5.1"
   }
 }

packages/sdk-ts/package.json

@@ -1,6 +1,7 @@
 export { Sandchest } from './client.js'
 export { Sandbox } from './sandbox.js'
 export { Session } from './session.js'
+export { ExecStream } from './stream.js'
 export {
   SandchestError,
   NotFoundError,
@@ -27,3 +28,4 @@ export type {
   ArtifactOperations,
   SessionManager,
 } from './types.js'
+export type { ExecStreamEvent } from '@sandchest/contract'

packages/sdk-ts/src/index.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test'
 import { Sandbox } from './sandbox.js'
 import { Session } from './session.js'
+import { ExecStream } from './stream.js'
 import { HttpClient } from './http.js'
 import { TimeoutError } from './errors.js'
 
@@ -120,7 +121,7 @@ describe('Sandbox', () => {
   })
 
   describe('exec (streaming)', () => {
-    test('returns async iterable of SSE events', async () => {
+    test('returns ExecStream that yields SSE events', async () => {
       let callCount = 0
       globalThis.fetch = mock(async () => {
         callCount++
@@ -135,8 +136,13 @@ describe('Sandbox', () => {
       }) as unknown as typeof fetch
 
       const sandbox = new Sandbox('sb_x', 'running', 'https://replay.sandchest.com/sb_x', createMockHttp())
+      const stream = await sandbox.exec('echo hello', { stream: true })
+
+      expect(stream).toBeInstanceOf(ExecStream)
+      expect(stream.execId).toBe('ex_s1')
+
       const events = []
-      for await (const event of sandbox.exec('echo hello', { stream: true })) {
+      for await (const event of stream) {
         events.push(event)
       }
 
@@ -145,6 +151,31 @@ describe('Sandbox', () => {
       expect(events[1]).toEqual({ seq: 2, t: 'stderr', data: 'warn\n' })
       expect(events[2]!.t).toBe('exit')
     })
+
+    test('ExecStream.collect() returns aggregated result', async () => {
+      let callCount = 0
+      globalThis.fetch = mock(async () => {
+        callCount++
+        if (callCount === 1) {
+          return jsonResponse({ exec_id: 'ex_c1', status: 'queued' }, 202)
+        }
+        return sseResponse([
+          { data: '{"seq":1,"t":"stdout","data":"out\\n"}' },
+          { data: '{"seq":2,"t":"stderr","data":"err\\n"}' },
+          { data: '{"seq":3,"t":"exit","code":0,"duration_ms":30,"resource_usage":{"cpu_ms":5,"peak_memory_bytes":512}}' },
+        ])
+      }) as unknown as typeof fetch
+
+      const sandbox = new Sandbox('sb_x', 'running', 'https://replay.sandchest.com/sb_x', createMockHttp())
+      const stream = await sandbox.exec('echo hello', { stream: true })
+      const result = await stream.collect()
+
+      expect(result.execId).toBe('ex_c1')
+      expect(result.stdout).toBe('out\n')
+      expect(result.stderr).toBe('err\n')
+      expect(result.exitCode).toBe(0)
+      expect(result.durationMs).toBe(30)
+    })
   })
 
   describe('exec (with callbacks)', () => {
@@ -356,7 +387,7 @@ describe('Sandbox', () => {
   })
 
   describe('Symbol.asyncDispose', () => {
-    test('calls stop()', async () => {
+    test('calls stop() when status is running', async () => {
       globalThis.fetch = mock(async () =>
         jsonResponse({ sandbox_id: 'sb_x', status: 'stopping' }, 202),
       ) as unknown as typeof fetch
@@ -365,6 +396,33 @@ describe('Sandbox', () => {
       await sandbox[Symbol.asyncDispose]()
       expect(sandbox.status).toBe('stopping')
     })
+
+    test('skips stop() when status is stopped', async () => {
+      let fetchCalled = false
+      globalThis.fetch = mock(async () => {
+        fetchCalled = true
+        return jsonResponse({ sandbox_id: 'sb_x', status: 'stopped' })
+      }) as unknown as typeof fetch
+
+      const sandbox = new Sandbox('sb_x', 'stopped', 'https://replay.sandchest.com/sb_x', createMockHttp())
+      await sandbox[Symbol.asyncDispose]()
+
+      expect(fetchCalled).toBe(false)
+      expect(sandbox.status).toBe('stopped')
+    })
+
+    test('skips stop() when status is deleted', async () => {
+      let fetchCalled = false
+      globalThis.fetch = mock(async () => {
+        fetchCalled = true
+        return jsonResponse({ sandbox_id: 'sb_x', status: 'deleted' })
+      }) as unknown as typeof fetch
+
+      const sandbox = new Sandbox('sb_x', 'deleted', 'https://replay.sandchest.com/sb_x', createMockHttp())
+      await sandbox[Symbol.asyncDispose]()
+
+      expect(fetchCalled).toBe(false)
+    })
   })
 
   describe('fs operations', () => {

packages/sdk-ts/src/sandbox.test.ts

@@ -28,41 +28,11 @@ import type {
 } from './types.js'
 import { Session } from './session.js'
 import { TimeoutError } from './errors.js'
+import { parseSSE, ExecStream } from './stream.js'
 
 const WAIT_READY_DEFAULT_TIMEOUT = 120_000
 const WAIT_READY_POLL_INTERVAL = 1_000
 
-/** Parse SSE events from a streaming Response. */
-async function* parseSSE<T>(response: Response): AsyncGenerator<T> {
-  const reader = response.body!.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-
-      buffer += decoder.decode(value, { stream: true })
-      const parts = buffer.split('\n\n')
-      buffer = parts.pop()!
-
-      for (const part of parts) {
-        for (const line of part.split('\n')) {
-          if (line.startsWith('data: ')) {
-            const data = line.slice(6)
-            if (data) {
-              yield JSON.parse(data) as T
-            }
-          }
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock()
-  }
-}
-
 /**
  * A Sandchest sandbox — an isolated Firecracker microVM.
  * All operations hang off this instance. No ID passing needed.
@@ -169,12 +139,12 @@ export class Sandbox {
 
   /** Execute a command (blocking, returns result). */
   exec(cmd: string | string[], options?: ExecOptions): Promise<ExecResult>
-  /** Execute a command (streaming, returns async iterable of events). */
-  exec(cmd: string | string[], options: StreamExecOptions): AsyncIterable<ExecStreamEvent>
+  /** Execute a command (streaming, returns ExecStream). */
+  exec(cmd: string | string[], options: StreamExecOptions): Promise<ExecStream>
   exec(
     cmd: string | string[],
     options?: ExecOptions | StreamExecOptions,
-  ): Promise<ExecResult> | AsyncIterable<ExecStreamEvent> {
+  ): Promise<ExecResult> | Promise<ExecStream> {
     if (options && 'stream' in options && options.stream === true) {
       return this._execStream(cmd, options)
     }
@@ -251,9 +221,11 @@ export class Sandbox {
     }
   }
 
-  /** Auto-cleanup via Explicit Resource Management. Calls stop(). */
+  /** Auto-cleanup via Explicit Resource Management. Calls stop() if running. */
   async [Symbol.asyncDispose](): Promise<void> {
-    await this.stop()
+    if (this.status === 'running') {
+      await this.stop()
+    }
   }
 
   private async _execBlocking(
@@ -332,10 +304,10 @@ export class Sandbox {
     return { execId: asyncRes.exec_id, exitCode, stdout, stderr, durationMs }
   }
 
-  private async *_execStream(
+  private async _execStream(
     cmd: string | string[],
     options: StreamExecOptions,
-  ): AsyncIterable<ExecStreamEvent> {
+  ): Promise<ExecStream> {
     const asyncRes = await this._http.request<ExecAsyncResponse>({
       method: 'POST',
       path: `/v1/sandboxes/${this.id}/exec`,
@@ -354,6 +326,6 @@ export class Sandbox {
       headers: { Accept: 'text/event-stream' },
     })
 
-    yield* parseSSE<ExecStreamEvent>(response)
+    return new ExecStream(asyncRes.exec_id, parseSSE<ExecStreamEvent>(response))
   }
 }

packages/sdk-ts/src/sandbox.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from 'bun:test'
+import { ExecStream, parseSSE } from './stream.js'
+import type { ExecStreamEvent } from '@sandchest/contract'
+
+function sseResponse(events: Array<{ data: string }>): Response {
+  const text = events.map((e) => `data: ${e.data}\n\n`).join('')
+  return new Response(text, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+describe('parseSSE', () => {
+  test('parses SSE data lines into typed objects', async () => {
+    const response = sseResponse([
+      { data: '{"seq":1,"t":"stdout","data":"hello\\n"}' },
+      { data: '{"seq":2,"t":"exit","code":0,"duration_ms":10,"resource_usage":{"cpu_ms":5,"peak_memory_bytes":256}}' },
+    ])
+
+    const events: ExecStreamEvent[] = []
+    for await (const event of parseSSE<ExecStreamEvent>(response)) {
+      events.push(event)
+    }
+
+    expect(events).toHaveLength(2)
+    expect(events[0]!.t).toBe('stdout')
+    expect(events[1]!.t).toBe('exit')
+  })
+
+  test('skips empty data lines', async () => {
+    const text = 'data: \n\ndata: {"seq":1,"t":"stdout","data":"ok"}\n\n'
+    const response = new Response(text, { status: 200 })
+
+    const events: unknown[] = []
+    for await (const event of parseSSE(response)) {
+      events.push(event)
+    }
+
+    expect(events).toHaveLength(1)
+  })
+
+  test('handles chunked delivery across event boundaries', async () => {
+    const fullText = 'data: {"seq":1,"t":"stdout","data":"a"}\n\ndata: {"seq":2,"t":"stdout","data":"b"}\n\n'
+    const encoder = new TextEncoder()
+    const bytes = encoder.encode(fullText)
+    const chunks: Uint8Array[] = []
+    for (let i = 0; i < bytes.length; i += 5) {
+      chunks.push(bytes.slice(i, i + 5))
+    }
+
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        for (const chunk of chunks) {
+          controller.enqueue(chunk)
+        }
+        controller.close()
+      },
+    })
+
+    const response = new Response(stream, { status: 200 })
+    const events: ExecStreamEvent[] = []
+    for await (const event of parseSSE<ExecStreamEvent>(response)) {
+      events.push(event)
+    }
+
+    expect(events).toHaveLength(2)
+  })
+})
+
+describe('ExecStream', () => {
+  function makeGenerator(events: ExecStreamEvent[]): AsyncGenerator<ExecStreamEvent> {
+    return (async function* () {
+      for (const event of events) {
+        yield event
+      }
+    })()
+  }
+
+  test('exposes execId', () => {
+    const stream = new ExecStream('ex_123', makeGenerator([]))
+    expect(stream.execId).toBe('ex_123')
+  })
+
+  test('is async iterable', async () => {
+    const events: ExecStreamEvent[] = [
+      { seq: 1, t: 'stdout', data: 'hello\n' },
+      { seq: 2, t: 'exit', code: 0, duration_ms: 10, resource_usage: { cpu_ms: 5, peak_memory_bytes: 256 } },
+    ]
+
+    const stream = new ExecStream('ex_123', makeGenerator(events))
+    const collected: ExecStreamEvent[] = []
+    for await (const event of stream) {
+      collected.push(event)
+    }
+
+    expect(collected).toHaveLength(2)
+    expect(collected[0]!.t).toBe('stdout')
+    expect(collected[1]!.t).toBe('exit')
+  })
+
+  test('collect() returns aggregated ExecResult', async () => {
+    const events: ExecStreamEvent[] = [
+      { seq: 1, t: 'stdout', data: 'line1\n' },
+      { seq: 2, t: 'stderr', data: 'warn\n' },
+      { seq: 3, t: 'stdout', data: 'line2\n' },
+      { seq: 4, t: 'exit', code: 0, duration_ms: 50, resource_usage: { cpu_ms: 10, peak_memory_bytes: 1024 } },
+    ]
+
+    const stream = new ExecStream('ex_456', makeGenerator(events))
+    const result = await stream.collect()
+
+    expect(result.execId).toBe('ex_456')
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toBe('line1\nline2\n')
+    expect(result.stderr).toBe('warn\n')
+    expect(result.durationMs).toBe(50)
+  })
+
+  test('collect() handles stream with no output', async () => {
+    const events: ExecStreamEvent[] = [
+      { seq: 1, t: 'exit', code: 1, duration_ms: 5, resource_usage: { cpu_ms: 1, peak_memory_bytes: 128 } },
+    ]
+
+    const stream = new ExecStream('ex_789', makeGenerator(events))
+    const result = await stream.collect()
+
+    expect(result.execId).toBe('ex_789')
+    expect(result.exitCode).toBe(1)
+    expect(result.stdout).toBe('')
+    expect(result.stderr).toBe('')
+    expect(result.durationMs).toBe(5)
+  })
+})