feat(sandbox): Add interactive TTY shell

[iiilisan]

Summary

Adds interactive terminal sessions to the SDK and CLI, enabling researchers to drop into a running sandbox like a normal SSH session.

• TerminalSession / TerminalResult — New types for TTY sessions. Unlike Process, output is raw bytes (no UTF-8 decode/re-encode), there is no output accumulation (streamed via queues), and the result contains only an exit code
• StreamReader generic — StreamReader[_S] parameterized over str (text streams) and bytes (raw TTY output)
• Sandbox.shell() — New SDK method that opens a bidirectional TTY stream via StreamExec with tty=True. Supports custom commands and terminal resize
• cwsandbox sh — Unix-only CLI command for interactive shell sessions. Raw terminal mode forwards all keystrokes (including Ctrl+C) to the remote process. SIGWINCH handler keeps remote PTY dimensions in sync
• Waitable / wait() extended — TerminalSession added to the Waitable type alias and wait() utility
• Documentation — New interactive shells guide, updated CLI quickstart with shell examples

Design decisions

• TTY output is raw bytes to avoid decode/re-encode overhead and preserve terminal escape sequences exactly
• No client-side timeout for interactive sessions (they are open-ended by nature)
• shell() defaults to ["/bin/bash"] matching the most common container setup
• The isatty() check runs before sandbox connection to fail fast when piped or under CI

Test plan

• Unit tests for TerminalSession and TerminalResult types
• Unit tests for cwsandbox sh — happy path, Windows guard, non-TTY guard, custom cmd, not-found, nonzero exit, keyboard interrupt
• Full unit suite passes (609 tests)

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

[Copilot]

Pull request overview

Adds interactive TTY shell support to the Aviato Python SDK and exposes it via a new aviato shell CLI command, with accompanying docs and tests.

Changes:

• Introduce TerminalSession / TerminalResult and generic StreamReader[T] to support raw-byte streaming for TTY sessions.
• Add Sandbox.shell() backed by a new streaming TTY exec path with resize + stdin multiplexing.
• Register aviato shell CLI command and add docs + unit/integration coverage.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/aviato/test_utilities.py	Extends wait() mixed-type tests to include TerminalSession.
tests/unit/aviato/test_types.py	Adds unit tests for TerminalResult and TerminalSession.
tests/unit/aviato/test_sandbox.py	Adds unit tests for Sandbox.shell() and a stream_logs close/cancel case.
tests/unit/aviato/test_cli_shell.py	New unit tests for aviato shell behavior and guards.
tests/integration/aviato/test_sandbox.py	Adds integration test ensuring shell sessions don’t disrupt a running sandbox.
tests/AGENTS.md	Documents new CLI shell test coverage.
src/aviato/cli/shell.py	Implements aviato shell interactive TTY command (Unix-only).
src/aviato/cli/init.py	Registers the new shell command with the CLI group.
src/aviato/_types.py	Adds TerminalSession/TerminalResult; makes StreamReader generic for bytes/text.
src/aviato/_sandbox.py	Implements TTY streaming exec and Sandbox.shell() entrypoint.
src/aviato/init.py	Exports new types and extends Waitable/wait() to cover TTY sessions.
src/aviato/AGENTS.md	Updates internal package map to include TerminalSession and cli/shell.py.
mkdocs.yml	Adds “Interactive Shells” guide to documentation nav.
docs/guides/troubleshooting.md	Adds troubleshooting notes for aviato shell on Windows / raw terminal recovery.
docs/guides/sync-vs-async.md	Documents shell() behavior in sync vs async contexts.
docs/guides/interactive-shells.md	New guide explaining TTY sessions, resize, and CLI usage.
docs/guides/execution.md	Links to shell() for interactive use cases.
docs/guides/AGENTS.md	Documents guidance conventions for TerminalSession / shell().
DEVELOPMENT.md	Adds aviato shell to dev command examples.
AGENTS.md	Updates top-level usage docs to include shell() and interactive session types.

---

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

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 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 23 out of 23 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]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 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.