Add PTY (pseudo-terminal) API documentation

Documentation for PR #310 which adds interactive terminal support.

New documentation:
- API reference: /sandbox/api/pty/
- How-to guide: /sandbox/guides/terminal-shells/
- Updated navigation and index pages

Covers PTY creation, session attachment, terminal I/O, resizing,
lifecycle management, and WebSocket transport for lower latency.

Author: github-actions[bot]

src/content/docs/sandbox/api/index.mdx

@@ -67,4 +67,12 @@ The Sandbox SDK provides a comprehensive API for executing code, managing files,
 	Create isolated execution contexts within a sandbox. Each session maintains its own shell state, environment variables, and working directory.
 </LinkTitleCard>
 
+<LinkTitleCard
+	title="PTY (Terminal)"
+	href="/sandbox/api/pty/"
+	icon="terminal"
+>
+	Create interactive pseudo-terminal sessions for shells and terminal-based applications. Full terminal control with ANSI escape codes.
+</LinkTitleCard>
+
 </CardGrid>

src/content/docs/sandbox/api/pty.mdx

@@ -0,0 +1,322 @@
+---
+title: PTY (Terminal)
+pcx_content_type: concept
+sidebar:
+  order: 9
+---
+
+import { TypeScriptExample } from "~/components";
+
+Create and manage interactive pseudo-terminal (PTY) sessions for shell access and terminal-based applications.
+
+PTY sessions provide a full terminal environment with ANSI escape codes, terminal resizing, and proper signal handling. Use PTY for interactive shells, terminal-based editors, or applications that require terminal control.
+
+## Methods
+
+### `sandbox.pty.create()`
+
+Create a new PTY session with a fresh terminal environment.
+
+```ts
+const pty = await sandbox.pty.create(options?: CreatePtyOptions): Promise<Pty>
+```
+
+**Parameters**:
+- `options` (optional):
+  - `cols` - Terminal width in columns (default: `80`)
+  - `rows` - Terminal height in rows (default: `24`)
+  - `command` - Command to run (default: `['/bin/bash']`)
+  - `cwd` - Working directory (default: `/home/user`)
+  - `env` - Environment variables to set
+  - `disconnectTimeout` - Milliseconds before orphaned PTY is killed (default: `30000`)
+
+**Returns**: `Promise<Pty>` - PTY handle for interacting with the terminal
+
+<TypeScriptExample>
+```ts
+// Create a default bash terminal
+const pty = await sandbox.pty.create({ cols: 80, rows: 24 });
+
+// Listen for output
+pty.onData((data) => {
+  console.log('Terminal output:', data);
+});
+
+// Send commands
+await pty.write('ls -la\n');
+await pty.write('pwd\n');
+
+// Wait for exit
+const { exitCode } = await pty.exited;
+console.log('Terminal exited with code:', exitCode);
+```
+</TypeScriptExample>
+
+### `sandbox.pty.attach()`
+
+Attach a PTY to an existing session, inheriting its working directory and environment variables.
+
+```ts
+const pty = await sandbox.pty.attach(sessionId: string, options?: AttachPtyOptions): Promise<Pty>
+```
+
+**Parameters**:
+- `sessionId` - Session ID to attach to
+- `options` (optional):
+  - `cols` - Terminal width in columns (default: `80`)
+  - `rows` - Terminal height in rows (default: `24`)
+  - `command` - Command to run (default: `['/bin/bash']`)
+  - `disconnectTimeout` - Milliseconds before orphaned PTY is killed (default: `30000`)
+
+**Returns**: `Promise<Pty>` - PTY handle
+
+<TypeScriptExample>
+```ts
+// Create a session and run some commands
+const session = await sandbox.sessions.create({ cwd: '/workspace' });
+await sandbox.exec('cd /workspace/project', { sessionId: session.id });
+
+// Attach PTY to existing session - inherits /workspace/project cwd
+const pty = await sandbox.pty.attach(session.id, { cols: 100, rows: 30 });
+
+// PTY starts in the session working directory
+pty.onData((data) => console.log(data));
+await pty.write('pwd\n'); // Outputs: /workspace/project
+```
+</TypeScriptExample>
+
+### `sandbox.pty.getById()`
+
+Reconnect to an existing PTY session by ID.
+
+```ts
+const pty = await sandbox.pty.getById(id: string): Promise<Pty>
+```
+
+**Parameters**:
+- `id` - PTY ID (e.g., `'pty_123'`)
+
+**Returns**: `Promise<Pty>` - PTY handle
+
+<TypeScriptExample>
+```ts
+// Store PTY ID for later reconnection
+const pty = await sandbox.pty.create();
+const ptyId = pty.id;
+
+// Later: reconnect to the same PTY
+const reconnected = await sandbox.pty.getById(ptyId);
+reconnected.onData((data) => console.log(data));
+```
+</TypeScriptExample>
+
+### `sandbox.pty.list()`
+
+List all active PTY sessions in the sandbox.
+
+```ts
+const ptys = await sandbox.pty.list(): Promise<PtyInfo[]>
+```
+
+**Returns**: `Promise<PtyInfo[]>` - Array of PTY information objects with:
+- `id` - PTY identifier
+- `sessionId` - Associated session ID (if attached)
+- `cols` - Terminal width
+- `rows` - Terminal height
+- `command` - Command being run
+- `cwd` - Working directory
+- `state` - PTY state (`'running'` or `'exited'`)
+- `exitCode` - Exit code (if exited)
+- `createdAt` - Creation timestamp
+
+<TypeScriptExample>
+```ts
+const ptys = await sandbox.pty.list();
+console.log(`Found ${ptys.length} active PTY sessions`);
+
+for (const pty of ptys) {
+  console.log(`PTY ${pty.id}: ${pty.state} (${pty.cols}x${pty.rows})`);
+}
+```
+</TypeScriptExample>
+
+## PTY Handle
+
+All `create()`, `attach()`, and `getById()` methods return a `Pty` handle with the following interface:
+
+### Properties
+
+- `id: string` - Unique PTY identifier
+- `sessionId?: string` - Associated session ID (if attached to session)
+- `exited: Promise<{ exitCode: number }>` - Promise that resolves when PTY exits
+
+### Methods
+
+#### `write()`
+
+Send input to the PTY terminal.
+
+```ts
+await pty.write(data: string): Promise<void>
+```
+
+<TypeScriptExample>
+```ts
+// Interactive commands
+await pty.write('npm install\n');
+await pty.write('git status\n');
+
+// Control sequences
+await pty.write('\x03'); // Ctrl+C
+await pty.write('\x04'); // Ctrl+D (EOF)
+```
+</TypeScriptExample>
+
+#### `resize()`
+
+Resize the terminal dimensions. The application running in the PTY receives a SIGWINCH signal.
+
+```ts
+await pty.resize(cols: number, rows: number): Promise<void>
+```
+
+<TypeScriptExample>
+```ts
+// Resize to match client terminal
+await pty.resize(120, 40);
+```
+</TypeScriptExample>
+
+#### `kill()`
+
+Terminate the PTY process.
+
+```ts
+await pty.kill(signal?: string): Promise<void>
+```
+
+<TypeScriptExample>
+```ts
+// Graceful termination
+await pty.kill('SIGTERM');
+
+// Force kill
+await pty.kill('SIGKILL');
+
+// Default signal (SIGTERM)
+await pty.kill();
+```
+</TypeScriptExample>
+
+#### `onData()`
+
+Register a callback to receive terminal output.
+
+```ts
+const unsubscribe = pty.onData(callback: (data: string) => void): () => void
+```
+
+Returns an unsubscribe function to stop receiving data.
+
+<TypeScriptExample>
+```ts
+const unsubscribe = pty.onData((data) => {
+  console.log('Terminal output:', data);
+});
+
+// Later: stop listening
+unsubscribe();
+```
+</TypeScriptExample>
+
+#### `onExit()`
+
+Register a callback to handle PTY exit.
+
+```ts
+const unsubscribe = pty.onExit(callback: (exitCode: number) => void): () => void
+```
+
+Returns an unsubscribe function to remove the callback.
+
+<TypeScriptExample>
+```ts
+pty.onExit((exitCode) => {
+  console.log('PTY exited with code:', exitCode);
+});
+```
+</TypeScriptExample>
+
+#### `close()`
+
+Detach from the PTY without killing it. The PTY continues running until the `disconnectTimeout` expires.
+
+```ts
+pty.close(): void
+```
+
+<TypeScriptExample>
+```ts
+// Detach from PTY
+pty.close();
+
+// PTY continues running for disconnectTimeout period
+// Can reconnect with getById() before timeout expires
+```
+</TypeScriptExample>
+
+### Async Iteration
+
+PTY handles support async iteration for scripting scenarios:
+
+<TypeScriptExample>
+```ts
+const pty = await sandbox.pty.create();
+await pty.write('find / -name "*.log" 2>/dev/null\n');
+await pty.write('exit\n');
+
+// Collect output using async iteration
+let output = '';
+for await (const chunk of pty) {
+  output += chunk;
+}
+
+console.log('Found log files:', output);
+```
+</TypeScriptExample>
+
+## Transport Modes
+
+PTY operations work with both HTTP and WebSocket transports:
+
+**HTTP Transport** (default):
+- `write()` and `resize()` return promises that resolve when the container confirms the operation
+- `onData()` uses Server-Sent Events (SSE) for output streaming
+- Higher latency but works in all Workers environments
+
+**WebSocket Transport** (opt-in):
+- `write()` and `resize()` send messages over WebSocket and resolve immediately
+- `onData()` receives output over the same WebSocket connection
+- Lower latency for real-time terminal interaction
+- Requires WebSocket support in your Worker environment
+
+Enable WebSocket transport when creating the sandbox:
+
+<TypeScriptExample>
+```ts
+import { getSandbox } from '@cloudflare/sandbox';
+
+const sandbox = await getSandbox(env.Sandbox, 'my-sandbox', {
+  useWebSocket: true
+});
+
+// PTY operations now use WebSocket for lower latency
+const pty = await sandbox.pty.create({ cols: 80, rows: 24 });
+```
+</TypeScriptExample>
+
+## Related Resources
+
+- [Terminal Shells Guide](/sandbox/guides/terminal-shells/) - Build interactive terminal applications
+- [Commands API](/sandbox/api/commands/) - Execute one-off commands without PTY overhead
+- [Sessions API](/sandbox/api/sessions/) - Manage execution contexts