From 7a439b782be156586991ef0996a28d6fcbbe1936 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 3 Dec 2025 17:27:15 +0000
Subject: [PATCH] Document process callback improvements and log capture fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <noreply@anthropic.com>
---
 src/content/docs/sandbox/api/commands.mdx     | 26 +++++++++++
 .../sandbox/guides/background-processes.mdx   | 44 +++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/src/content/docs/sandbox/api/commands.mdx b/src/content/docs/sandbox/api/commands.mdx
index 324dcbe5df5a311..a19f4e2f1bff941 100644
--- a/src/content/docs/sandbox/api/commands.mdx
+++ b/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
diff --git a/src/content/docs/sandbox/guides/background-processes.mdx b/src/content/docs/sandbox/guides/background-processes.mdx
index 229587d8106e971..ddd1a2be1747fb4 100644
--- a/src/content/docs/sandbox/guides/background-processes.mdx
+++ b/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: