computesdk 1.11.0 → 1.11.1

package/README.md

@@ -283,6 +283,209 @@ Remove a file or directory.
 await sandbox.filesystem.remove('/tmp/hello.py');
 ```
 
+### Terminal Operations
+
+The sandbox provides terminal access in two modes: **PTY mode** (interactive shell) and **Exec mode** (command tracking).
+
+#### `sandbox.terminal.create(options?)`
+
+Create a new terminal session.
+
+```typescript
+// PTY mode - Interactive shell
+const pty = await sandbox.terminal.create({ pty: true, shell: '/bin/bash' });
+
+// Exec mode - Command tracking (default)
+const exec = await sandbox.terminal.create({ pty: false });
+```
+
+**Options:**
+- `pty?: boolean` - Terminal mode: `true` = PTY (interactive), `false` = exec (command tracking). Default: `false`
+- `shell?: string` - Shell to use (e.g., '/bin/bash'). PTY mode only
+- `encoding?: 'raw' | 'base64'` - Output encoding. Default: `'raw'`
+
+**Returns:** `TerminalInstance`
+
+#### `sandbox.terminal.list()`
+
+List all active terminals.
+
+```typescript
+const terminals = await sandbox.terminal.list();
+console.log(terminals); // [{ id: 'term-1', pty: true, status: 'running', ... }]
+```
+
+#### `sandbox.terminal.retrieve(id)`
+
+Retrieve a specific terminal by ID.
+
+```typescript
+const terminal = await sandbox.terminal.retrieve('term-123');
+console.log(terminal.id, terminal.status);
+```
+
+#### `sandbox.terminal.destroy(id)`
+
+Destroy a terminal by ID.
+
+```typescript
+await sandbox.terminal.destroy('term-123');
+```
+
+### PTY Mode (Interactive Shell)
+
+PTY mode creates an interactive shell session with real-time input/output over WebSocket.
+
+#### `terminal.write(input)`
+
+Send input to the terminal shell.
+
+```typescript
+const pty = await sandbox.terminal.create({ pty: true });
+pty.on('output', (data) => console.log(data));
+pty.write('ls -la\n');
+pty.write('pwd\n');
+await pty.destroy();
+```
+
+#### `terminal.resize(cols, rows)`
+
+Resize the terminal window.
+
+```typescript
+pty.resize(120, 40);
+```
+
+#### `terminal.on(event, handler)`
+
+Register an event handler. Events: `'output'`, `'error'`, `'destroyed'`.
+
+```typescript
+pty.on('output', (data) => console.log('Output:', data));
+pty.on('error', (error) => console.error('Error:', error));
+pty.on('destroyed', () => console.log('Terminal destroyed'));
+```
+
+#### `terminal.off(event, handler)`
+
+Unregister an event handler.
+
+```typescript
+const handler = (data) => console.log(data);
+pty.on('output', handler);
+pty.off('output', handler);
+```
+
+#### Terminal Properties
+
+```typescript
+console.log(pty.id);       // Terminal ID
+console.log(pty.status);   // 'running' | 'stopped' | 'active' | 'ready'
+console.log(pty.channel);  // WebSocket channel (PTY only)
+console.log(pty.pty);      // true for PTY mode
+```
+
+### Exec Mode (Command Tracking)
+
+Exec mode executes commands with structured result tracking, suitable for automation.
+
+#### `terminal.command.run(command, options?)`
+
+Execute a command in the terminal.
+
+```typescript
+const exec = await sandbox.terminal.create({ pty: false });
+
+// Foreground execution (waits for completion)
+const cmd = await exec.command.run('npm test');
+console.log(cmd.stdout);
+console.log(cmd.stderr);
+console.log(cmd.exitCode);
+
+// Background execution (returns immediately)
+const bgCmd = await exec.command.run('npm install', { background: true });
+console.log(bgCmd.status); // 'running'
+await bgCmd.wait(); // Wait for completion
+console.log(bgCmd.exitCode);
+```
+
+**Parameters:**
+- `command: string` - The command to execute
+- `options?: { background?: boolean }` - Execution options
+
+**Returns:** `Command` object
+
+#### `terminal.command.list()`
+
+List all commands executed in this terminal.
+
+```typescript
+const commands = await exec.command.list();
+commands.forEach(cmd => {
+  console.log(cmd.id, cmd.command, cmd.status, cmd.exitCode);
+});
+```
+
+#### `terminal.command.retrieve(cmdId)`
+
+Retrieve a specific command by ID.
+
+```typescript
+const cmd = await exec.command.retrieve('cmd-123');
+console.log(cmd.stdout);
+```
+
+### Command Object
+
+The `Command` object represents a command execution result.
+
+#### Command Properties
+
+```typescript
+console.log(cmd.id);          // Command ID
+console.log(cmd.terminalId);  // Parent terminal ID
+console.log(cmd.command);     // Executed command
+console.log(cmd.status);      // 'running' | 'completed' | 'failed'
+console.log(cmd.stdout);      // Standard output
+console.log(cmd.stderr);      // Standard error
+console.log(cmd.exitCode);    // Exit code (undefined if running)
+console.log(cmd.durationMs);  // Execution time in milliseconds
+console.log(cmd.startedAt);   // Start timestamp
+console.log(cmd.finishedAt);  // Finish timestamp (undefined if running)
+```
+
+#### `command.wait(timeout?)`
+
+Wait for a background command to complete.
+
+```typescript
+const cmd = await exec.command.run('sleep 5', { background: true });
+await cmd.wait(); // Waits up to default timeout
+console.log(cmd.exitCode);
+
+// With custom timeout (in seconds, 0 = no timeout)
+await cmd.wait(10);
+```
+
+#### `command.refresh()`
+
+Refresh the command status from the server.
+
+```typescript
+const cmd = await exec.command.run('npm build', { background: true });
+// ... later ...
+await cmd.refresh();
+console.log(cmd.status, cmd.exitCode);
+```
+
+#### `terminal.destroy()`
+
+Destroy the terminal and clean up resources.
+
+```typescript
+await exec.destroy();
+```
+
 ## Examples
 
 ### Data Science Workflow
@@ -391,6 +594,82 @@ console.log(runResult.stdout);
 await sandbox.destroy();
 ```
 
+### Terminal Command Execution
+
+```typescript
+import { compute } from 'computesdk';
+
+const sandbox = await compute.sandbox.create({ runtime: 'node' });
+
+// Create exec mode terminal for command tracking
+const terminal = await sandbox.terminal.create({ pty: false });
+
+// Run build commands with tracking
+const install = await terminal.command.run('npm install');
+console.log('Install exit code:', install.exitCode);
+
+const build = await terminal.command.run('npm run build');
+console.log('Build output:', build.stdout);
+
+// Run tests in background
+const tests = await terminal.command.run('npm test', { background: true });
+console.log('Tests started:', tests.status);
+
+// Wait for tests to complete
+await tests.wait(60); // 60 second timeout
+console.log('Tests completed:', tests.exitCode === 0 ? 'PASSED' : 'FAILED');
+console.log('Test output:', tests.stdout);
+
+// List all commands
+const commands = await terminal.command.list();
+console.log(`Executed ${commands.length} commands`);
+
+await terminal.destroy();
+await sandbox.destroy();
+```
+
+### Interactive Terminal Session
+
+```typescript
+import { compute } from 'computesdk';
+
+const sandbox = await compute.sandbox.create({ runtime: 'node' });
+
+// Create PTY terminal for interactive shell
+const pty = await sandbox.terminal.create({ 
+  pty: true, 
+  shell: '/bin/bash' 
+});
+
+// Collect all output
+let output = '';
+pty.on('output', (data) => {
+  output += data;
+  console.log(data);
+});
+
+pty.on('error', (error) => {
+  console.error('Terminal error:', error);
+});
+
+// Execute interactive commands
+pty.write('echo "Starting project setup"\n');
+pty.write('mkdir -p /workspace/myproject\n');
+pty.write('cd /workspace/myproject\n');
+pty.write('npm init -y\n');
+pty.write('npm install express\n');
+pty.write('echo "Setup complete"\n');
+
+// Wait for operations to complete
+await new Promise(resolve => setTimeout(resolve, 5000));
+
+// Clean up
+await pty.destroy();
+await sandbox.destroy();
+
+console.log('Complete output:', output);
+```
+
 ### Using Different Providers
 
 ```typescript

package/dist/index.js

@@ -3620,6 +3620,34 @@ async function gatewayFetch(url, config, options = {}) {
     throw error;
   }
 }
+async function waitForSandboxStatus(config, endpoint, body, options = {}) {
+  const maxWaitMs = options.maxWaitMs ?? 6e4;
+  const initialDelayMs = 500;
+  const maxDelayMs = 2e3;
+  const backoffFactor = 1.5;
+  const startTime = Date.now();
+  let currentDelay = initialDelayMs;
+  while (Date.now() - startTime < maxWaitMs) {
+    const result = await gatewayFetch(endpoint, config, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (!result.success || !result.data) {
+      return result;
+    }
+    if (result.data.status !== "creating") {
+      return result;
+    }
+    if (process.env.COMPUTESDK_DEBUG) {
+      console.log(`[Compute] Sandbox still creating, waiting ${currentDelay}ms...`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+  }
+  throw new Error(
+    `Sandbox is still being created after ${maxWaitMs}ms. This may indicate the sandbox failed to start. Check your provider dashboard.`
+  );
+}
 var ComputeManager = class {
   constructor() {
     this.config = null;
@@ -3707,14 +3735,15 @@ var ComputeManager = class {
       findOrCreate: async (options) => {
         const config = this.getGatewayConfig();
         const { name, namespace, ...restOptions } = options;
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find-or-create`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find-or-create`,
+          {
             namespace: namespace || "default",
             name,
             ...restOptions
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           throw new Error(`Gateway returned invalid response`);
         }
@@ -3744,13 +3773,14 @@ var ComputeManager = class {
        */
       find: async (options) => {
         const config = this.getGatewayConfig();
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find`,
+          {
             namespace: options.namespace || "default",
             name: options.name
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           return null;
         }