updated llm guidance based on observations about how it seemed to decide between exec and execAsync

Author: james-rl

README-SDK.md

@@ -160,13 +160,13 @@ print(f"Devbox {info.name} is {info.status}")
 Execute commands synchronously or asynchronously:
 
 ```python
-# Synchronous command execution (waits for completion)
+# exec blocks until completion - use for commands that return immediately
 result = devbox.cmd.exec("ls -la")
 print("Output:", result.stdout())
 print("Exit code:", result.exit_code)
 print("Success:", result.success)
 
-# Asynchronous command execution (returns immediately)
+# exec_async returns immediately - use for long-running processes
 execution = devbox.cmd.exec_async("npm run dev")
 
 # Check execution status
@@ -393,11 +393,30 @@ async with await runloop.devbox.create(name="temp-devbox") as devbox:
 # devbox is automatically shutdown when exiting the context
 ```
 
+#### Devbox Logs
+
+Retrieve logs from a devbox, optionally filtered by execution ID or shell name:
+
+```python
+# Get all devbox logs
+logs = devbox.logs()
+for log in logs.logs:
+    print(f"[{log.level}] {log.message}")
+
+# Filter logs by execution ID
+result = devbox.cmd.exec('echo "hello"')
+exec_logs = devbox.logs(execution_id=result.execution_id)
+
+# Filter logs by shell name
+shell_logs = devbox.logs(shell_name="my-shell")
+```
+
 **Key methods:**
 
 - `devbox.get_info()` - Get devbox details and status
 - `devbox.cmd.exec()` - Execute commands synchronously
 - `devbox.cmd.exec_async()` - Execute commands asynchronously
+- `devbox.logs()` - Retrieve devbox logs (optionally filter by execution_id or shell_name)
 - `devbox.file.read()` - Read file contents
 - `devbox.file.write()` - Write file contents
 - `devbox.file.upload()` - Upload files

llms.txt

@@ -23,8 +23,8 @@
 - **Prefer `AsyncRunloopSDK` over `RunloopSDK`** for better concurrency and performance; all SDK methods have async equivalents
 - Use `async with await runloop.devbox.create()` for automatic cleanup via context manager
 - For resources without SDK coverage (e.g., secrets, benchmarks), use `runloop.api.*` as a fallback
-- Use `await devbox.cmd.exec('command')` for most commands—blocks until completion, returns `ExecutionResult` with stdout/stderr
-- Use `await devbox.cmd.exec_async('command')` for long-running or background processes (servers, watchers)—returns immediately with `Execution` handle to check status, get result, or kill
+- Use `await devbox.cmd.exec('command')` for commands expected to return immediately (e.g., `echo`, `pwd`, `cat`)—blocks until completion, returns `ExecutionResult` with stdout/stderr
+- Use `await devbox.cmd.exec_async('command')` for long-running or background processes (servers, watchers, builds)—returns immediately with `Execution` handle to check status, get result, or kill
 - Both `exec` and `exec_async` support streaming callbacks (`stdout`, `stderr`, `output`) for real-time output
 - Call `await devbox.shutdown()` to clean up resources that are no longer in use.
 - Streaming callbacks (`stdout`, `stderr`, `output`) must be synchronous functions even with async SDK

tests/smoketests/sdk/test_async_devbox.py

@@ -1064,3 +1064,55 @@ async def test_shell_exec_async_with_both_streams(self, devbox: AsyncDevbox) ->
         # Verify streaming captured same data as result
         assert stdout_combined == await result.stdout()
         assert stderr_combined == await result.stderr()
+
+
+class TestAsyncDevboxLogs:
+    """Test async devbox logs retrieval functionality."""
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    async def test_logs_basic(self, shared_devbox: AsyncDevbox) -> None:
+        """Test retrieving devbox logs returns valid response structure."""
+        test_message = "async basic log test message"
+        result = await shared_devbox.cmd.exec(f'echo "{test_message}"')
+        assert result.exit_code == 0
+
+        logs = await shared_devbox.logs()
+
+        assert logs is not None
+        assert hasattr(logs, "logs")
+        assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    async def test_logs_with_execution_filter(self, shared_devbox: AsyncDevbox) -> None:
+        """Test retrieving devbox logs filtered by execution ID."""
+        test_message = "async filtered log test"
+        result = await shared_devbox.cmd.exec(f'echo "{test_message}"')
+        assert result.exit_code == 0
+
+        logs = await shared_devbox.logs(execution_id=result.execution_id)
+
+        assert logs is not None
+        assert hasattr(logs, "logs")
+        assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content
+
+    @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
+    async def test_logs_with_shell_name_filter(self, shared_devbox: AsyncDevbox) -> None:
+        """Test retrieving devbox logs filtered by shell name."""
+        shell_name = "async-test-logs-shell"
+        shell = shared_devbox.shell(shell_name)
+
+        test_message = "async shell log test"
+        result = await shell.exec(f'echo "{test_message}"')
+        assert result.exit_code == 0
+
+        logs = await shared_devbox.logs(shell_name=shell_name)
+
+        assert logs is not None
+        assert hasattr(logs, "logs")
+        assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content

tests/smoketests/sdk/test_devbox.py

@@ -1058,39 +1058,47 @@ class TestDevboxLogs:
     @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
     def test_logs_basic(self, shared_devbox: Devbox) -> None:
         """Test retrieving devbox logs returns valid response structure."""
-        # Fetch logs - the API may return empty logs depending on timing
+        test_message = "basic log test message"
+        result = shared_devbox.cmd.exec(f'echo "{test_message}"')
+        assert result.exit_code == 0
+
         logs = shared_devbox.logs()
 
         assert logs is not None
         assert hasattr(logs, "logs")
         assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content
 
     @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
     def test_logs_with_execution_filter(self, shared_devbox: Devbox) -> None:
         """Test retrieving devbox logs filtered by execution ID."""
-        # Run a command and get its execution ID
-        execution = shared_devbox.cmd.exec_async('echo "filtered log test"')
-        result = execution.result()
+        test_message = "filtered log test"
+        result = shared_devbox.cmd.exec(f'echo "{test_message}"')
         assert result.exit_code == 0
 
-        # Fetch logs filtered by execution ID - verifies API accepts the filter
-        logs = shared_devbox.logs(execution_id=execution.execution_id)
+        logs = shared_devbox.logs(execution_id=result.execution_id)
 
         assert logs is not None
+        assert hasattr(logs, "logs")
         assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content
 
     @pytest.mark.timeout(THIRTY_SECOND_TIMEOUT)
     def test_logs_with_shell_name_filter(self, shared_devbox: Devbox) -> None:
         """Test retrieving devbox logs filtered by shell name."""
         shell_name = "test-logs-shell"
         shell = shared_devbox.shell(shell_name)
 
-        # Run a command in the named shell
-        result = shell.exec('echo "shell log test"')
+        test_message = "shell log test"
+        result = shell.exec(f'echo "{test_message}"')
         assert result.exit_code == 0
 
-        # Fetch logs filtered by shell name - verifies API accepts the filter
         logs = shared_devbox.logs(shell_name=shell_name)
 
         assert logs is not None
+        assert hasattr(logs, "logs")
         assert isinstance(logs.logs, list)
+        log_content = " ".join(str(log) for log in logs.logs)
+        assert test_message in log_content