feat(sandbox): Add stream_logs() and logs command

[iiilisan]

Summary

Adds live log streaming to the SDK and CLI, enabling researchers to tail sandbox output in real time.

• StreamReader.close() — Cancel the background producer and mark the stream as exhausted, enabling callers to stop follow-mode streams cleanly
• Sandbox.stream_logs() — New SDK method wrapping the StreamLogs gRPC RPC. Returns a StreamReader[str] that yields log lines. Supports follow, tail_lines, since_time, and timestamps options
• cwsandbox logs — CLI command wrapping stream_logs() with --follow, --tail, --since, --timestamps flags
• exec stderr close — Use StreamReader.close() to unblock the stderr drain thread on exec failure
• Bounded response queue — Internal gRPC response buffer uses STREAMING_RESPONSE_QUEUE_SIZE (256) to propagate backpressure, preventing unbounded memory growth in follow mode
• Documentation — New logging guide, updated CLI quickstart with logs examples

Design decisions

• stream_logs() returns StreamReader directly (not wrapped in OperationRef) since iteration is the blocking operation
• The background Future's cancel method is wired into StreamReader.close() so stopping iteration cancels the gRPC stream
• --since accepts click.DateTime() default formats (YYYY-MM-DD, YYYY-MM-DD HH:MM:SS), not full ISO 8601 with timezone designators

Test plan

• Unit tests for StreamReader.close() cancellation behavior
• Unit tests for cwsandbox logs — all options, iteration errors, not-found handling
• Full unit suite passes

Stack: 2/3 — exian/cli-core → exian/logs → exian/shell

[Copilot]

Pull request overview

This PR adds live log streaming capabilities to the Aviato SDK and CLI, enabling researchers to tail sandbox output in real time. The implementation follows established patterns from the existing exec streaming functionality and includes comprehensive test coverage.

Changes:

• Added StreamReader.close() method to cleanly stop streaming operations by canceling the background producer task
• Implemented Sandbox.stream_logs() SDK method wrapping the StreamLogs gRPC RPC with support for follow mode, tail_lines, since_time, and timestamps options
• Added aviato logs CLI command with --follow, --tail, --since, and --timestamps flags
• Introduced bounded response queue (STREAMING_RESPONSE_QUEUE_SIZE = 256) for backpressure in long-lived streams
• Added comprehensive documentation including new logging guide and updated existing guides

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/aviato/_types.py	Added close() method to StreamReader with optional cancel callback support
src/aviato/_sandbox.py	Implemented stream_logs() public API and _stream_logs_async() internal streaming logic with line buffering and error handling
src/aviato/_defaults.py	Added STREAMING_RESPONSE_QUEUE_SIZE constant for backpressure
src/aviato/cli/logs.py	New CLI command with all streaming options and graceful error handling
src/aviato/cli/__init__.py	Registered logs command
tests/unit/aviato/test_types.py	Unit tests for StreamReader.close() behavior including idempotency and cancel callback
tests/unit/aviato/test_sandbox.py	Comprehensive unit tests for stream_logs including partial lines, error handling, and option validation
tests/unit/aviato/test_cli_logs.py	CLI tests covering all options, error scenarios, and signal handling
tests/integration/aviato/test_sandbox.py	Integration test verifying log streaming doesn't disrupt sandbox operation
docs/guides/logging.md	New comprehensive guide for sandbox logging
docs/guides/*.md	Updated existing guides to reference log streaming
examples/interactive_streaming_sandbox.py	Demonstrates log streaming with exec interaction
Various AGENTS.md files	Documentation updates for AI agents

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[NavarrePratt]

Let's make sure it's very clear across docstrings and guides that this method is for getting output of the main command used in the sandbox upon creation, which is different than the commands you start with exec. By default, sandboxes run with tail -f /dev/null and won't have any logs to output here.

[NavarrePratt]

We already have guide material around logs for commands in the execution guide. We should unify these, at least link between them, to help with discovery. That way if a user is trying to figure out how to handle logs of commands they exec and they find this, they still get pointed to the correct information.