feat: Debug Sandboxes through CLI (#163)

* wip

* working version

Author: christianalfoni

CHANGELOG.md

@@ -5,21 +5,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Build Commands
+
 - `npm run build` - Full production build (clean, esbuild, generate types for both CJS and ESM)
 - `npm run build:esbuild` - Run esbuild bundling only
 - `npm run clean` - Remove dist directory
 - `npm run dev:cli` - Development mode with file watching for CLI (watches src/bin)
 
 ### Type Checking and Linting
+
 - `npm run typecheck` - Run TypeScript type checking without emitting files
 - `npm run format` - Format code using Prettier
 
 ### CLI Development
+
 - `npm run dev:cli` - Start development mode with file watching specifically for CLI changes
 - The CLI binary is built to `dist/bin/codesandbox.mjs` and made executable
 - CLI can be run with `./dist/bin/codesandbox.mjs` or just `csb` if installed globally
 
 ### API Client Generation
+
 - `npm run build-openapi` - Generate API clients from production OpenAPI spec
 - `npm run build-openapi:staging` - Generate API clients from staging OpenAPI spec
 - Generated clients are placed in `src/api-clients/` directory
@@ -29,35 +33,41 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ### Core Components
 
 **SDK Entry Points:**
+
 - `src/index.ts` - Main SDK export with `CodeSandbox` class
 - `src/browser/index.ts` - Browser-specific SDK build
 - `src/node/index.ts` - Node.js-specific SDK build
 
 **Key Classes:**
+
 - `CodeSandbox` - Main SDK class providing `sandboxes` and `hosts` properties
-- `Sandboxes` (src/Sandboxes.ts) - Manages sandbox operations (create, list, get, fork)  
+- `Sandboxes` (src/Sandboxes.ts) - Manages sandbox operations (create, list, get, fork)
 - `Sandbox` (src/Sandbox.ts) - Individual sandbox instance with connection and session management
 - `SandboxClient` (src/SandboxClient/index.ts) - High-level client for sandbox interactions
 - `API` (src/API.ts) - Low-level API wrapper for all CodeSandbox REST endpoints
 
 **Communication Layer:**
+
 - `src/pitcher-protocol/` - WebSocket protocol definitions and message types for real-time sandbox communication
 - `src/AgentClient/` - WebSocket client implementation for connecting to sandbox agents
 
 **CLI:**
+
 - `src/bin/main.tsx` - CLI entry point using Ink (React for CLI)
 - `src/bin/commands/` - Individual CLI commands (build, sandbox, previewHosts, hostTokens)
 - `src/bin/ui/` - Ink-based UI components for the interactive CLI
 
 ### Build System
 
 **Multi-Format Output:**
+
 - ESM build: `dist/esm/` (primary format, "type": "module")
 - CommonJS build: `dist/cjs/` (compatibility)
 - Browser build: Separate bundles with browser polyfills
 - CLI build: Standalone executable with shebang
 
 **Key Build Features:**
+
 - esbuild for bundling with custom plugins for module replacement
 - Separate TypeScript compilation for type definitions
 - Browser polyfills for Node.js modules (os, path, crypto, etc.)
@@ -66,22 +76,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ### Type System
 
 **Configuration:**
-- Main tsconfig.json excludes `src/bin` and `src/api-clients` 
+
+- Main tsconfig.json excludes `src/bin` and `src/api-clients`
 - Separate build configs for CJS (`tsconfig.build-cjs.json`) and ESM (`tsconfig.build-esm.json`)
 - Strict TypeScript configuration with comprehensive type checking
 
 **Generated Types:**
+
 - `src/api-clients/` contains auto-generated API clients and types from OpenAPI specs
 - Multiple API client modules for different sandbox services (fs, git, shell, etc.)
 
 ### Authentication & Configuration
 
 **API Authentication:**
+
 - Requires CodeSandbox API token (CSB_API_KEY environment variable)
 - Token creation: https://codesandbox.io/t/api
 - Automatic User-Agent header injection with SDK version
 
 **Environment Detection:**
+
 - Automatic base URL inference based on API key format
 - Support for different CodeSandbox environments (production, staging)
 
@@ -93,24 +107,28 @@ The codebase includes a `test-template/` directory with a Vite + React + TypeScr
 
 **SDK Documentation:** https://codesandbox.io/docs/sdk
 
-**Contributing to Documentation:** 
+**Contributing to Documentation:**
+
 - Documentation source is located at https://github.com/codesandbox/docs
 - SDK-specific docs are in `packages/projects-docs/pages/sdk/` folder
 - Update documentation there when making changes to SDK functionality
 
 ## Key Patterns
 
 **Error Handling:**
+
 - `handleResponse` utility for consistent API error handling
 - Retry logic with exponential backoff for critical operations
 - OpenTelemetry tracing integration for observability
 
 **Session Management:**
+
 - Support for custom sessions with git credentials and environment variables
 - Browser session creation for web-based sandbox interactions
 - Automatic session cleanup and disposal
 
 **Resource Management:**
-- VM tier scaling and hibernation timeout management  
+
+- VM tier scaling and hibernation timeout management
 - Cluster and bootup type tracking
-- Agent version management and update detection
+- Agent version management and update detection

CLAUDE.md

@@ -1,6 +1,6 @@
 {
   "name": "@codesandbox/sdk",
-  "version": "2.0.7",
+  "version": "2.1.0-rc.4",
   "description": "The CodeSandbox SDK",
   "author": "CodeSandbox",
   "license": "MIT",
@@ -97,6 +97,8 @@
     "@inkjs/ui": "^2.0.0",
     "@msgpack/msgpack": "^3.1.0",
     "@opentelemetry/api": "^1.9.0",
+    "@xterm/addon-serialize": "^0.13.0",
+    "@xterm/headless": "^5.5.0",
     "blessed": "^0.1.81",
     "blessed-contrib": "^4.11.0",
     "chalk": "^5.4.1",

package-lock.json

@@ -90,9 +90,9 @@ export class Sandbox {
   async updateTier(tier: VMTier): Promise<void> {
     return this.withSpan(
       "sandbox.updateTier",
-      { 
+      {
         "sandbox.id": this.id,
-        "tier.name": tier.name
+        "tier.name": tier.name,
       },
       async () => {
         await this.api.updateSpecs(this.id, {
@@ -111,7 +111,7 @@ export class Sandbox {
       "sandbox.updateHibernationTimeout",
       {
         "sandbox.id": this.id,
-        "hibernation.timeoutSeconds": timeoutSeconds
+        "hibernation.timeoutSeconds": timeoutSeconds,
       },
       async () => {
         await this.api.updateHibernationTimeout(this.id, {
@@ -126,8 +126,12 @@ export class Sandbox {
     session: SandboxSession
   ) {
     const client = await SandboxClient.create(
-      session, 
-      async () => this.getSession(await this.api.startVm(this.id, { retryDelay: 200 }), customSession),
+      session,
+      async () =>
+        this.getSession(
+          await this.api.startVm(this.id, { retryDelay: 200 }),
+          customSession
+        ),
       undefined,
       this.tracer
     );
@@ -220,7 +224,7 @@ export class Sandbox {
       {
         "sandbox.id": this.id,
         "session.hasCustomSession": !!customSession,
-        "session.id": customSession?.id || "default"
+        "session.id": customSession?.id || "default",
       },
       async () => {
         return await retryWithDelay(
@@ -234,14 +238,21 @@ export class Sandbox {
 
             // We might create a client here if git or env is configured, we can reuse that
             if (customSession) {
-              client = await this.initializeCustomSession(customSession, session);
+              client = await this.initializeCustomSession(
+                customSession,
+                session
+              );
             }
 
             return (
               client ||
               SandboxClient.create(
-                session, 
-                async () => this.getSession(await this.api.startVm(this.id, { retryDelay: 200 }), customSession),
+                session,
+                async () =>
+                  this.getSession(
+                    await this.api.startVm(this.id, { retryDelay: 200 }),
+                    customSession
+                  ),
                 undefined,
                 this.tracer
               )
@@ -271,7 +282,7 @@ export class Sandbox {
         "session.hasCustomSession": !!customSession,
         "session.id": customSession?.id || "default",
         "session.hasGit": !!customSession?.git,
-        "session.hasEnv": !!customSession?.env
+        "session.hasEnv": !!customSession?.env,
       },
       async () => {
         if (customSession?.git || customSession?.env) {

package.json

@@ -88,7 +88,7 @@ export class SandboxCommands {
         "command.text": cmdString,
         "command.cwd": opts?.cwd || "/project",
         "command.asGlobalSession": opts?.asGlobalSession || false,
-        "command.name": opts?.name || ""
+        "command.name": opts?.name || "",
       },
       async () => {
         const disposableStore = new DisposableStore();
@@ -168,7 +168,7 @@ export class SandboxCommands {
       {
         "command.text": cmdString,
         "command.cwd": opts?.cwd || "/project",
-        "command.asGlobalSession": opts?.asGlobalSession || false
+        "command.asGlobalSession": opts?.asGlobalSession || false,
       },
       async () => {
         const cmd = await this.runBackground(command, opts);
@@ -181,21 +181,23 @@ export class SandboxCommands {
    * Get all running commands.
    */
   async getAll(): Promise<Command[]> {
-    return this.withSpan(
-      "commands.getAll",
-      {},
-      async () => {
-        const shells = await this.agentClient.shells.getShells();
-
-        return shells
-          .filter(
-            (shell) => shell.shellType === "TERMINAL" && isCommandShell(shell)
-          )
-          .map(
-            (shell) => new Command(this.agentClient, shell, JSON.parse(shell.name), this.tracer)
-          );
-      }
-    );
+    return this.withSpan("commands.getAll", {}, async () => {
+      const shells = await this.agentClient.shells.getShells();
+
+      return shells
+        .filter(
+          (shell) => shell.shellType === "TERMINAL" && isCommandShell(shell)
+        )
+        .map(
+          (shell) =>
+            new Command(
+              this.agentClient,
+              shell,
+              JSON.parse(shell.name),
+              this.tracer
+            )
+        );
+    });
   }
 }
 
@@ -348,7 +350,7 @@ export class Command {
         "command.shellId": this.shell.shellId,
         "command.text": this.command,
         "command.dimensions.cols": dimensions.cols,
-        "command.dimensions.rows": dimensions.rows
+        "command.dimensions.rows": dimensions.rows,
       },
       async () => {
         const shell = await this.agentClient.shells.open(
@@ -372,7 +374,7 @@ export class Command {
       {
         "command.shellId": this.shell.shellId,
         "command.text": this.command,
-        "command.status": this.status
+        "command.status": this.status,
       },
       async () => {
         await this.barrier.wait();
@@ -403,7 +405,7 @@ export class Command {
       {
         "command.shellId": this.shell.shellId,
         "command.text": this.command,
-        "command.status": this.status
+        "command.status": this.status,
       },
       async () => {
         this.disposable.dispose();
@@ -421,7 +423,7 @@ export class Command {
       {
         "command.shellId": this.shell.shellId,
         "command.text": this.command,
-        "command.status": this.status
+        "command.status": this.status,
       },
       async () => {
         if (this.status !== "RUNNING") {