Document process callback improvements and log capture fixes

Updates documentation to reflect bug fixes in sandbox-sdk PR #267:
- Add onStart, onOutput, onExit, and onError callback documentation
- Clarify that PID is now reliably available in process responses
- Document that getProcessLogs() now correctly captures output from fast commands
- Add guidance on when to use callbacks vs polling for process monitoring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: github-actions[bot]

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

@@ -95,6 +95,10 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
 - `options` (optional):
   - `cwd` - Working directory
   - `env` - Environment variables
+  - `onStart` - Callback invoked when process starts: `(process: ProcessInfo) => void`
+  - `onOutput` - Callback for real-time output: `(stream: 'stdout' | 'stderr', data: string) => void`
+  - `onExit` - Callback invoked when process exits: `(exitCode: number | null) => void`
+  - `onError` - Callback for errors: `(error: Error) => void`
 
 **Returns**: `Promise<ProcessInfo>` with `id`, `pid`, `command`, `status`
 
@@ -108,6 +112,14 @@ const app = await sandbox.startProcess('node app.js', {
   cwd: '/workspace/my-app',
   env: { NODE_ENV: 'production', PORT: '3000' }
 });
+
+// With callbacks for monitoring
+const service = await sandbox.startProcess('node service.js', {
+  onStart: (process) => console.log(`Started with PID ${process.pid}`),
+  onOutput: (stream, data) => console.log(`[${stream}] ${data}`),
+  onExit: (exitCode) => console.log(`Exited with code ${exitCode}`),
+  onError: (error) => console.error('Process error:', error)
+});
 ```
 </TypeScriptExample>
 
@@ -210,9 +222,23 @@ await new Promise(resolve => setTimeout(resolve, 5000));
 
 const logs = await sandbox.getProcessLogs(server.id);
 console.log('Server logs:', logs);
+
+// For fast commands, logs are available immediately after completion
+const build = await sandbox.startProcess('npm run build');
+// Wait for completion
+const processes = await sandbox.listProcesses();
+const buildProcess = processes.find(p => p.id === build.id);
+if (buildProcess?.status === 'completed') {
+  const buildLogs = await sandbox.getProcessLogs(build.id);
+  console.log('Build output:', buildLogs);
+}
 ```
 </TypeScriptExample>
 
+:::note
+For completed processes, `getProcessLogs()` automatically waits for all output to be captured before returning, ensuring complete logs even for fast-executing commands.
+:::
+
 ## Related resources
 
 - [Background processes guide](/sandbox/guides/background-processes/) - Managing long-running processes

src/content/docs/sandbox/guides/background-processes.mdx

@@ -64,6 +64,50 @@ console.log('API server started');
 ```
 </TypeScriptExample>
 
+## Use callbacks for real-time monitoring
+
+Monitor process lifecycle and output using callbacks instead of polling:
+
+<TypeScriptExample>
+```
+const server = await sandbox.startProcess('node server.js', {
+  onStart: (process) => {
+    console.log(`Server started with PID ${process.pid}`);
+  },
+  onOutput: (stream, data) => {
+    // Handle output in real-time
+    if (stream === 'stdout') {
+      console.log('Output:', data);
+    } else {
+      console.error('Error:', data);
+    }
+  },
+  onExit: (exitCode) => {
+    console.log(`Server exited with code ${exitCode}`);
+  },
+  onError: (error) => {
+    console.error('Process error:', error);
+  }
+});
+
+// Process continues running in background
+// Callbacks fire automatically as events occur
+```
+</TypeScriptExample>
+
+**When to use callbacks:**
+
+- **Real-time monitoring** - React immediately to process events
+- **Error detection** - Catch failures as they happen
+- **Progress tracking** - Monitor long-running operations
+- **Integration** - Forward output to logging systems or user interfaces
+
+**When to use polling:**
+
+- **Periodic checks** - Query status at intervals
+- **Batch processing** - Collect accumulated logs after completion
+- **Simpler logic** - When immediate notification is not required
+
 ## Monitor process status
 
 List and check running processes: