diff --git a/docs/research/alknet-tty/phase-0-findings.md b/docs/research/alknet-tty/phase-0-findings.md new file mode 100644 index 0000000..5fc4c8f --- /dev/null +++ b/docs/research/alknet-tty/phase-0-findings.md @@ -0,0 +1,617 @@ +--- +status: draft +last_updated: 2026-07-03 +--- + +# alknet-tty — Phase 0 Research Findings + +This document captures Phase 0 (Exploration) findings for the `alknet-tty` +crate. The objective of Phase 0 per `docs/sdd_process.md` is: *"Capture vision +and guiding principles; research options; validate approaches; converge on a +recommended approach."* It is the input to Phase 1 (Architecture), where the +Architect will produce `docs/architecture/crates/tty/*.md` specs, ADRs, and +open questions. + +This document was drafted 2026-07-03, immediately after the `alknet-docker` +POC (`docs/research/alknet-docker/poc-summary.md`) validated that bollard's +container attach maps cleanly onto a framed bidi stream with a 1-byte +stream-type multiplexer. The POC's raw chunk format is the seed of +`alknet-tty`'s wire format. + +## Vision Recap + +`alknet-tty` is a terminal session protocol handler for the ALPN-as-service +architecture (ADR-001). It registers the `alknet/tty` ALPN on the shared +`AlknetEndpoint` and implements the `ProtocolHandler` trait (ADR-002, +ADR-007). + +The guiding insight, surfaced during the alknet-docker POC and recognized in +the conversation that followed: + +> **A terminal session is not an SSH concern, or a Docker concern — it is a +> terminal concern. SSH and Docker are just two backends that can allocate +> a PTY.** + +The alknet-docker POC proved that the hard part of interactive attach — +bidirectional byte pumping over a framed stream with a multiplexing header — +is the same problem regardless of whether the backend is `bollard::attach_container()` +or russh's `pty_request` + session channel. The POC's raw chunk format +(`[stream_type: u8][length: u32 be][payload bytes]`, with stream_type +0=stdin, 1=stdout, 2=stderr) is a deliberately impoverished version of SSH's +channel multiplexer: fixed set of channel types, no negotiation, no +open/close handshake, no windowing (QUIC provides flow control on the bidi +stream). That impoverishment is the feature — a terminal session needs +exactly those channels and no more. + +`alknet-tty` extracts that pattern into its own crate and ALPN. The +backends (Docker, SSH, local process) implement a `TtyBackend` trait; the +`alknet/tty` handler is backend-agnostic. This dissolves the PTY hedge in +the alknet-ssh research (`docs/research/alknet-ssh/phase-0-findings.md` +DP-5: "shell_request and pty_request default-reject; interactive shell is +an explicit opt-in") — PTY is not an SSH feature, it's a tty feature that +SSH happens to be able to provide. + +Beyond terminals, the same wire format and backend trait support a general +"runner" pattern: a process (local `std::process::Command`, docker +container, SSH exec) whose stdin/stdout/stderr/exit-code are streamed over +a framed bidi connection. The dispatch project +(`/workspace/@alkdev/dispatch/`) is a reverse runner that currently requires +an SSH server on the remote end; with `alknet-tty` and a local-process +backend, the same runner pattern works without SSH at all — the endpoint +runs the process directly and streams its I/O back. This is the same shape +as GitHub/Gitea Actions runners, just over alknet's transport instead of +HTTP polling. + +## Sources Investigated + +| Source | Path | Note | +|--------|------|------| +| alknet-docker POC | `/workspace/alknet-docker-poc/` | Validated raw chunk format, two-carriage model, bidirectional pumping against live docker. The POC's `src/raw.rs` is the seed of alknet-tty's wire format. | +| alknet-docker POC summary | `docs/research/alknet-docker/poc-summary.md` | Documents the two-carriage model (JSON negotiation → raw bytes), the three validated targets, the open unknowns. | +| alknet-ssh phase-0 findings | `docs/research/alknet-ssh/phase-0-findings.md` | DP-5 hedges PTY as an SSH concern; the channel decomposition (Layers 1-7) treats PTY as part of Layer 4 (Session/exec). This document dissolves that hedge. | +| alknet-core types | `crates/alknet-core/src/types.rs` | `ProtocolHandler`, `Connection`, `SendStream`, `RecvStream` — the handler interface alknet-tty implements. | +| alknet-call wire format | `crates/alknet-call/src/protocol/wire.rs` | `EventEnvelope`, `FrameFramedReader/Writer` — the JSON carriage layer alknet-tty uses for the initial `call.requested` negotiation frame. | +| alknet-call dispatch | `crates/alknet-call/src/protocol/dispatch.rs` | `handle_stream` (:295), `pump_stream` (:340) — the streaming pump pattern. alknet-tty's raw-carriage path is a sibling to this, not a consumer of it. | +| bollard source | `/workspace/bollard/src/` | `container.rs` (`attach_container` :540, `LogOutput` :96, `AttachContainerResults` :80), `read.rs` (`NewlineLogOutputDecoder` :32 — the 8-byte header format our chunk format mirrors), `exec.rs` (`StartExecResults` enum :99) | +| bollard examples | `/workspace/bollard/examples/attach_container.rs` | Reliable attach + TTY passthrough. | +| dispatch project | `/workspace/@alkdev/dispatch/` | The "reverse runner" — axum + russh SSH client for exec/forwarding/sync over Docker/vast.ai. `src/handlers.rs` (`start_job`, `job_status`, `job_logs`) is the runner pattern alknet-tty generalizes. Currently requires SSH on the remote; alknet-tty with a local-process backend removes that requirement. | +| russh source | `/workspace/russh/` | `server::Handler` — `pty_request` (allocates PTY), `window_change` (resize), `signal` (signal forwarding), `shell_request`/`exec_request`. These are the SSH-side operations a `SshTtyBackend` wraps. | +| alknet-runtime research | `docs/research/alknet-runtime/summary.md` | The "operation host" pattern — a node that exposes ops on a registry. alknet-tty is the same pattern for process execution: a node that can run a process and stream its I/O. | +| Rust std::process | stdlib | `Command`, `Stdio` (piped stdin/stdout/stderr), `Child::wait` (exit code). The local-process backend. The threading/deadlock caveat (must read stdout/stderr concurrently with writing stdin to avoid pipe-buffer deadlock) is handled by the bidirectional pump, same as docker attach. | + +## The Wire Format: From POC to Spec + +### What the alknet-docker POC validated + +The POC's `src/raw.rs` defines a chunk format for raw carriage on a bidi +stream: + +```text +[stream_type: u8][length: u32 be][payload bytes] +``` + +- `stream_type` mirrors bollard's `NewlineLogOutputDecoder` header byte + (`/workspace/bollard/src/read.rs:46`): 0=stdin, 1=stdout, 2=stderr. +- `length` is the payload length in bytes (u32 big-endian, max 16 MiB). +- A zero-length chunk is a sentinel (used for completion notification). + +The POC proved this format works for: +- **server→client stdout/stderr**: each `LogOutput` from bollard's attach + stream becomes a chunk with the matching stream_type. +- **client→server stdin**: `ChunkWriter::write_stdin(bytes)` writes a + type-0 chunk; the server reads it and writes the bytes to bollard's + `container_input` (`AsyncWrite`). +- **completion**: when bollard's output stream ends (container exited), + the server sends a zero-length type-1 chunk as a "drained" sentinel. + +### What alknet-tty adds + +A terminal session needs two things the docker attach POC didn't: + +1. **Control messages during the raw phase.** Window resize (SIGWINCH) and + signal forwarding (Ctrl-C → SIGINT) must ride *during* the byte stream, + not as a new request. The chunk format handles this by reserving a 4th + stream_type: + + | stream_type | channel | direction | payload | + |---|---|---|---| + | 0 | data-in (stdin) | client→server | raw bytes | + | 1 | data-out (stdout) | server→client | raw bytes | + | 2 | data-err (stderr) | server→client | raw bytes | + | 3 | control | bidirectional | JSON control message | + + Control chunks carry a small JSON payload: + - `{"type":"resize","cols":80,"rows":24,"pixel_width":0,"pixel_height":0}` — + window resize (maps to SSH `window-change`, docker exec resize, or + `ioctl(TIOCSWINSZ)` on a local PTY). + - `{"type":"signal","name":"INT"}` — signal forwarding (maps to SSH + `signal`, docker exec signal, or `kill(pid, sig)` on a local process). + - `{"type":"eof"}` — client signals no more stdin (maps to SSH channel + EOF, docker stdin close, or `ChildStdin::drop`). + - `{"type":"exit","code":0}` — server signals process exit (terminal, + no more data chunks follow; the stream then closes). + +2. **Terminal parameters at negotiation time.** The initial `call.requested` + frame (JSON carriage, same as the POC) carries the terminal attributes + that the backend needs to allocate the PTY: + + ```json + { + "operationId": "/tty/open", + "carriage": "raw", + "backend": "docker", + "container": "abc123", + "tty": { + "term": "xterm-256color", + "cols": 80, + "rows": 24, + "pixel_width": 0, + "pixel_height": 0, + "modes": {} + }, + "cmd": ["/bin/bash"] + } + ``` + + The `tty` block maps directly to SSH's `pty_request` parameters + (term, cols, rows, pixel_width, pixel_height, modes) and to docker's + `CreateExecOptions { tty: true }`. A local-process backend passes them + to `portable_pty::PtySystem::openpty` (or equivalent). + +### Why fixed channel set, not extensible + +SSH's channels are `ChannelId(u32)` with string-named types negotiated per +channel. alknet-tty's channels are a fixed `u8` set with no negotiation. +This is a one-way door (adding a 5th channel type is a wire-format change), +and it's the right one-way door: + +- **The use cases are bounded.** A terminal session has stdin, stdout, + stderr, and control. If something genuinely new appears (say, a + sideband file-transfer channel alongside the terminal), that's a + different ALPN, not a 5th tty channel type. The ALPN model handles + extensibility at the protocol level — a new ALPN is cheap, a wire-format + change is not. +- **1 byte vs length-prefixed string + negotiation round-trip.** The fixed + set is faster, simpler, and the demuxing is a `match` instead of a hash + lookup. For a terminal session where every chunk is hot, this matters. +- **The comparison to SSH channels is the justification, not the + constraint.** SSH needs dynamic channels because it multiplexes + *arbitrary* services (forwarding, SFTP, agent, X11) over one connection. + alknet-tty multiplexes *one* service (a terminal session) with a fixed + channel structure. The impoverishment is the feature. + +## The Backend Trait + +The `TtyBackend` trait is the inversion point that keeps alknet-tty +decoupled from its backends: + +```rust +#[async_trait] +pub trait TtyBackend: Send + Sync { + async fn allocate(&self, params: &TtyParams) -> Result; +} + +pub struct TtyParams { + pub backend_params: BackendParams, // backend-specific (container id, ssh host, command) + pub terminal: TerminalParams, // term, cols, rows, modes + pub cmd: Vec, +} + +pub enum BackendParams { + Docker { container: String }, + Ssh { channel: SshChannelRef }, + Local { cwd: Option, env: HashMap }, +} + +pub struct TtyHandle { + pub stdin: Box, + pub stdout: Pin + Send>>, + pub stderr: Option + Send>>>, // None if PTY (merged into stdout) + pub exit_code: BoxFuture<'static, Result>, + pub control: Box, // resize, signal +} +``` + +The `TtyAdapter` (the `ProtocolHandler` for `alknet/tty`) receives the +`Connection`, reads the `call.requested` frame, selects the backend by the +`backend` field, calls `allocate()`, and pumps bytes bidirectionally using +the chunk format. Control chunks are dispatched to `TtyHandle::control`. +When `exit_code` resolves, the server sends a `{"type":"exit","code":N}` +control chunk and closes the stream. + +Three implementations, each in its own crate (the no-handler-depends-on- +another-handler rule from ADR-003 is preserved — backends depend on +alknet-tty for the trait, alknet-tty doesn't depend on them): + +- **`DockerTtyBackend`** (in alknet-docker, or a thin adapter): wraps + `bollard::attach_container()` → `AttachContainerResults { output, input }` + for interactive attach, or `bollard::exec::start_exec` with `tty: true` + for exec-with-PTY. The POC's `drive_attach_raw` *is* this backend, + inlined; with the trait, it becomes `impl TtyBackend for DockerTtyBackend`. + `control.resize()` calls `bollard::exec::resize_exec` or + `bollard::container::resize_container`. + +- **`SshTtyBackend`** (in alknet-ssh): wraps russh's `pty_request` + + `shell_request` (or `exec_request` with a PTY) on a session channel. + `channel.into_stream()` gives `(AsyncRead, AsyncWrite)` — the stream + *is* the PTY; russh handles kernel PTY allocation on the server side. + `control.resize()` sends a `window_change` channel request; + `control.signal()` sends a `signal` channel request. stdout and stderr + are merged (PTY property), so `TtyHandle.stderr` is `None`. + +- **`LocalTtyBackend`** (in alknet-tty or a sibling crate): wraps + `std::process::Command` with `Stdio::piped()` for stdin/stdout/stderr, + OR `portable_pty` for a real PTY (needed for terminal escape sequences, + signal delivery, window resize). Without a PTY, it's a "runner" (piped + process); with a PTY, it's a terminal. `control.resize()` calls + `ioctl(TIOCSWINSZ)` on the PTY master; `control.signal()` calls + `kill(child.pid, sig)`. The threading/deadlock caveat (must read + stdout/stderr concurrently with writing stdin to avoid pipe-buffer + deadlock) is handled by the bidirectional pump — the same pattern as + docker attach, where `tokio::spawn` runs the two directions concurrently. + +### The runner generalization + +The `LocalTtyBackend` without a PTY is the "runner" pattern: a process +whose stdin/stdout/stderr/exit-code are streamed over a framed bidi +connection. This is functionally identical to GitHub/Gitea Actions runners, +just over alknet's transport instead of HTTP polling: + +- A coordinator sends `{"backend":"local","cmd":["cargo","test"],"tty":null}` + — no terminal, just a command. +- The endpoint runs `cargo test` with piped stdio, streams stdout/stderr + chunks back, sends `{"type":"exit","code":N}` when it finishes. +- The coordinator gets reliable completion notification (the exit control + chunk + stream close) — the same stopgap property as the docker logs + subscription. + +The dispatch project (`/workspace/@alkdev/dispatch/`) is a reverse runner +that currently requires an SSH server on the remote end (it uses russh to +exec commands and stream output). With `LocalTtyBackend`, the same pattern +works without SSH — the endpoint runs the process directly. SSH becomes +one transport option (for reaching hosts that don't run alknet), not a +requirement. This is "discuss afterwards" territory per the conversation, +but the trait shape preserves the option. + +## What This Dissolves in alknet-ssh + +### DP-5's PTY hedge + +The alknet-ssh research (`phase-0-findings.md` DP-5) says: + +> `shell_request` and `pty_request` default-reject; `exec_request` +> permitted (gated by ACL). This keeps alknet-ssh a focused forwarding/exec +> appliance rather than a general-purpose interactive login server. +> Interactive shell is an explicit opt-in (two-way door). + +With alknet-tty, PTY is not an SSH feature — it's a tty feature. alknet-ssh +implements `TtyBackend` for SSH session channels; alknet-tty owns the +terminal session lifecycle. alknet-ssh's session channel (Layer 4) still +does `exec` (structured, JSON carriage, exit code on completion) but +*delegates* PTY to alknet-tty. The "default-reject" stance stays for the +SSH channel policy (alknet-ssh still rejects `pty_request` on its own +session channels — it doesn't serve terminals directly), but the PTY +capability is provided by a separate crate via a separate ALPN, not hedged +inside alknet-ssh. + +### Layer 4 simplifies + +The alknet-ssh build order was "1-4 first (SSH+exec), then 5 (forwarding), +then 6/7 (SOCKS5/SFTP)." PTY was a deferred wart on Layer 4. With +alknet-tty, Layer 4 is just `exec` (one-shot command, JSON carriage, exit +code on completion) — clean and complete. PTY is a *different ALPN* +(`alknet/tty`) that happens to use SSH as its backend. + +### The browser case gets a terminal for free + +The alknet-ssh research notes the browser runs a WASM SSH client over +WebTransport (ADR-040). But a browser terminal (xterm.js) doesn't want SSH +— it wants a terminal. With `alknet/tty` as an ALPN, xterm.js connects via +WebTransport to `/alknet/tty`, negotiates a session (docker container, SSH +PTY, or local process), and gets raw bytes. The browser doesn't need to +implement SSH at all for the terminal use case — it only needs SSH if it +wants SSH-specific features (port forwarding, SFTP). This is a cleaner +browser story than "run a WASM SSH client." + +## Straightforward Parts + +These are settled by the POC, existing ADRs, and the wire format above. +Phase 1 should document them as spec rather than re-litigate. + +### 1. alknet-tty is a `ProtocolHandler` on `alknet/tty` + +Same pattern as every other handler: `TtyAdapter` implements +`ProtocolHandler::handle(&self, connection: Connection, auth: &AuthContext)` +with `alpn() = b"alknet/tty"`. The handler owns the entire `Connection` +lifecycle (ADR-006) and accepts one bidi stream per terminal session. + +### 2. The two-carriage model is inherited from the POC + +The initial `call.requested` frame is JSON (length-prefixed `EventEnvelope`, +identical to alknet-call's `FrameFramedReader/Writer`). After the request, +the stream switches to raw chunks. The `carriage` field in the request +payload is `"raw"` for terminal sessions. This is the same mechanism the +POC validated; no new wire-format invention. + +### 3. Raw chunk format is POC-validated + +The `[stream_type: u8][length: u32 be][payload]` format, the `ChunkReader`/ +`ChunkWriter` types, and the bidirectional pump pattern are all directly +from the POC's `src/raw.rs`. The only addition is `stream_type: 3` for +control messages, which is a 1-byte extension to a validated format. + +### 4. Backend trait is the inversion point + +alknet-tty defines `TtyBackend`; the backend crates (alknet-docker, +alknet-ssh, local) implement it. The `TtyAdapter` is backend-agnostic. +This preserves ADR-003's no-handler-depends-on-another-handler rule: +alknet-tty depends on alknet-core; the backend crates depend on alknet-tty +(for the trait); alknet-tty doesn't depend on any backend. + +### 5. Completion notification is free + +The exit control chunk (`{"type":"exit","code":N}`) + stream close gives +the coordinator deterministic completion notification — the same stopgap +property the docker POC validated for logs subscriptions. No plugin state, +no polling. The container/process exiting is the signal. + +## Less Straightforward Parts (Decision Points) + +### DP-1: Local-process backend in alknet-tty or a sibling crate? + +*(Recommended: two-way door — start in alknet-tty, extract if warranted)* + +The `LocalTtyBackend` (std::process::Command / portable_pty) is the +simplest backend and the one that enables the runner pattern. It has no +heavy dependencies (no bollard, no russh — just std + optionally +`portable_pty`). Two options: + +- **(a) In alknet-tty**: the crate ships with the local backend built-in. + Pro: zero-config runner, one crate gets you a terminal/process-streaming + endpoint. Con: alknet-tty pulls in `portable_pty` even for deployments + that only use docker/ssh backends. +- **(b) In a sibling crate (`alknet-tty-local`)**: alknet-tty defines the + trait; the local backend is a separate crate. Pro: alknet-tty stays + dependency-light; consumers opt into the local backend explicitly. Con: + one extra crate for the common case. + +**Recommendation**: **(b) sibling crate**, behind a feature flag on +alknet-tty for the common case (`features = ["local"]` → re-export from +`alknet-tty-local`). This keeps alknet-tty's default dependency surface +minimal while making the local backend a one-feature opt-in. The local +backend is where the `portable_pty` dependency lives; alknet-tty itself +depends only on alknet-core and the frame/raw codec. Extraction is cheap +because the trait is the seam. + +### DP-2: PTY vs pipe for the local backend + +*(Recommended: two-way door — support both, PTY is opt-in)* + +`std::process::Command` with `Stdio::piped()` gives pipes (no terminal +semantics — no signal delivery, no window resize, no escape-sequence +handling). `portable_pty` gives a real PTY (terminal semantics, resize, +signals, escape sequences). The `TtyParams.terminal` field distinguishes: +if `terminal` is `Some(TerminalParams { ... })`, the backend allocates a +PTY; if `None`, it uses pipes (the runner case). + +**Recommendation**: support both. The `TtyHandle.stderr` field is `None` +for PTY (stdout/stderr merged) and `Some` for pipes (separate streams). +The `control` field is a no-op impl for pipes (resize/signal don't apply +without a PTY — though `kill(pid, sig)` still works for signal forwarding). +The decision is per-session, not per-deployment. + +### DP-3: Control message format — JSON vs binary + +*(Recommended: two-way door — JSON first, binary if hot)* + +Control chunks (stream_type 3) carry a JSON payload (`{"type":"resize", +"cols":80,"rows":24}`). This is consistent with the call protocol's +JSON-everything stance and easy to extend. A binary format +(`[control_type: u8][params...]`) would be faster but harder to extend and +inconsistent with the negotiation layer. + +**Recommendation**: JSON first. Control messages are rare (resize happens +on window drag, signal on Ctrl-C) — the serialization cost is negligible +compared to the data chunks. If a hot control path appears (unlikely for +terminals), a binary format can be added as a `control_type` extension +without breaking the chunk format. + +### DP-4: The threading/deadlock caveat for piped processes + +*(Recommended: acknowledged constraint — the bidirectional pump handles it)* + +`std::process::Command` with piped stdio can deadlock if stdin writes +block while stdout/stderr buffers fill — the classic pipe-buffer deadlock. +The fix is concurrent reads on stdout/stderr alongside stdin writes, which +is exactly what the bidirectional pump does (the POC's `drive_attach_raw` +runs the two directions as concurrent `tokio::spawn` tasks). The same +pattern works for `LocalTtyBackend`: spawn one task pumping stdin→process, +one task pumping process→stdout-chunks, one for stderr if piped. + +**Recommendation**: Phase 1 records this as a known constraint with a +known solution (concurrent pumping). No design decision needed — the POC +already proved the pattern. The spec notes that `LocalTtyBackend` must use +the concurrent-pump pattern, not sequential read-then-write. + +### DP-5: Exit code propagation — control chunk vs final data chunk + +*(Recommended: one-way door — control chunk)* + +The alknet-docker POC validated exit-code-on-final-`call.responded` for +the JSON carriage path (exec with exit code). The raw carriage path needs +a different mechanism because there's no `call.responded` after the raw +phase begins. Two options: + +- **(a) Control chunk**: `{"type":"exit","code":N}` as the last chunk + before stream close. Clean, explicit, carries the code as structured + data. +- **(b) Final data chunk with exit code**: a special stdout chunk with an + exit-code payload. Hacky — overloads the data channel for metadata. + +**Recommendation**: **(a) control chunk**. The exit code is control +metadata, not data. The control channel (stream_type 3) exists for exactly +this. The chunk is the last thing before stream close; the client reads it +and knows the process exited with code N. This is a one-way door because +clients will depend on the "exit chunk is last" invariant. + +### DP-6: Multiple sessions per connection + +*(Recommended: two-way door — one session per stream, multiple streams per connection)* + +A `Connection` (ADR-007) can open/accept multiple bidi streams. Should one +`alknet/tty` connection host multiple terminal sessions (one per stream), +or one session per connection? + +**Recommendation**: **one session per bidi stream, multiple streams per +connection**. This matches the call protocol's model (one operation per +stream, multiple operations per connection) and is the natural fit for +QUIC's stream multiplexing. A coordinator opens one connection to an +endpoint and launches multiple sessions (one stream each) for parallel +tasks. The `TtyAdapter::handle` accepts the connection and loops +`accept_bi`, dispatching each stream to a session — same pattern as +alknet-call's `Dispatcher::run_loop` (`protocol/dispatch.rs:369`). + +## Recommended Approach + +### Crate + +`alknet-tty`, depends on `alknet-core` (for `ProtocolHandler`, `Connection`). +Defines the `TtyBackend` trait, the wire format (chunk codec + control +messages), and the `TtyAdapter` (`ProtocolHandler` for `alknet/tty`). Does +not depend on bollard, russh, or portable_pty — those are in the backend +crates. + +### Build order + +**Step 1: Wire format + TtyAdapter + mock backend.** +- Extract `raw.rs` from the POC into alknet-tty's wire format module. +- Add `stream_type: 3` (control) and the control message types + (resize, signal, eof, exit). +- Implement `TtyAdapter` with a mock backend (in-memory pipes) to validate + the full protocol: negotiate → pump → control → exit → close. +- **Result**: a working `alknet/tty` handler with no real backends, but + the wire format and session lifecycle are proven. + +**Step 2: LocalTtyBackend (runner).** +- `alknet-tty-local` crate (or feature): `impl TtyBackend for LocalTtyBackend` + using `std::process::Command` with piped stdio. +- Validate the runner pattern: `cargo test` as the command, stream + stdout/stderr/exit over `alknet/tty`. +- Add `portable_pty` for the PTY case (terminal semantics, resize, signals). +- **Result**: a working runner/terminal endpoint with no docker or SSH + dependency. + +**Step 3: DockerTtyBackend.** +- In alknet-docker: `impl TtyBackend for DockerTtyBackend` wrapping + `bollard::attach_container` / `exec with tty:true`. +- The POC's `drive_attach_raw` becomes this backend; the `TtyAdapter` calls + it via the trait. +- **Result**: docker containers as terminal sessions via `alknet/tty`. + +**Step 4: SshTtyBackend.** +- In alknet-ssh: `impl TtyBackend for SshTtyBackend` wrapping russh's + `pty_request` + `shell_request`/`exec_request` on a session channel. +- `control.resize()` → `window_change` channel request; + `control.signal()` → `signal` channel request. +- **Result**: SSH PTYs as terminal sessions via `alknet/tty`. alknet-ssh's + DP-5 hedge dissolves — PTY is delegated to alknet-tty. + +### De-risk POC (extending the alknet-docker POC) + +The alknet-docker POC already validated targets 1 (attach round-trip), 2 +(logs completion), and 3 (exec exit code). Two extensions validate the +alknet-tty additions: + +1. **Control message during raw phase** — add `stream_type: 3` to the POC's + chunk format, send a `resize` control chunk mid-session, prove the + backend receives it. For docker this requires `tty: true` on the exec + and `bollard::exec::resize_exec`. Small POC, validates the control + channel mechanism. + +2. **PTY allocation via docker exec with TTY** — `CreateExecOptions { tty: + true }` allocates a real PTY. Validate that stdout/stderr merge + (stream_type always 1) and that resize works. Proves the docker-as-PTY- + backend path. + +Both are extensions to the existing POC, not new POCs. The wire format and +bidirectional pump are already proven; these just confirm the control +channel and PTY-specific paths. + +## Open Questions to Carry into Phase 1 + +- **OQ-TTY-01 (backend trait shape)**: the exact `TtyHandle` field set — + is `control` a separate trait object or are resize/signal methods on + `TtyHandle` directly? Does `exit_code` belong on the handle or is it a + separate `Future` the adapter awaits? Resolved by Phase 1 spec; the POC + extension informs the decision. +- **OQ-TTY-02 (terminal modes)**: SSH's `pty_request` carries TTY modes + (echo, raw, canonical, etc.) as a packed bitmask. Does alknet-tty + support these, or defer to the backend's defaults? Likely defer for v1 + (the common case is "default terminal modes"); the `modes` field in + `TerminalParams` is reserved for future use. +- **OQ-TTY-03 (flow control)**: the chunk format has no windowing (QUIC + provides flow control on the bidi stream). Is this sufficient for + high-throughput stdout (e.g., `cargo build` output)? QUIC's per-stream + flow control should handle it, but a POC with real high-volume output + would confirm. Low risk — the docker POC's logs subscription handled + multi-line output without issue. +- **OQ-TTY-04 (local backend crate placement)**: confirm `alknet-tty-local` + as a sibling crate vs a feature flag on alknet-tty. DP-1 recommends + sibling + feature re-export; Phase 1 confirms. +- **OQ-TTY-05 (runner API surface)**: the "runner" generalization + (local-process backend without PTY) is noted as "discuss afterwards" in + the conversation. Phase 1 should at minimum preserve the option + (`TtyParams.terminal = None` → pipe mode) even if the runner-specific + API surface (job management, log persistence, task graph integration) is + deferred to a later crate. + +## Next Steps (Phase 0 → Phase 1) + +1. **POC extension**: extend `/workspace/alknet-docker-poc` with + `stream_type: 3` (control) and `tty: true` exec to validate the control + channel and PTY allocation. Timeboxed; the wire format is already + proven, these are extensions. +2. **You decide** on the DP recommendations (or amend them). DP-1 (local + backend placement) and DP-5 (exit code on control chunk) are the + load-bearing choices. DP-2, DP-3, DP-4, DP-6 are defaults recommended + as-is. +3. **Phase 1 (Architect)**: produce `docs/architecture/crates/tty/README.md` + + component specs (`tty-wire.md` for the chunk format + control + messages, `tty-backend.md` for the `TtyBackend` trait + `TtyHandle`, + `tty-adapter.md` for the `ProtocolHandler` + session lifecycle, + `tty-local.md` for the local backend / runner), ADRs for the accepted + DPs (wire format + fixed channel set, backend trait as inversion point, + local backend placement, exit code on control chunk), and the OQs above + in `open-questions.md`. Update `docs/architecture/README.md` index and + ADR table. + +## References + +- `docs/research/alknet-docker/poc-summary.md` — the POC that seeded this + crate. Raw chunk format, two-carriage model, three validated targets. +- `/workspace/alknet-docker-poc/src/raw.rs` — the chunk codec + (`ChunkReader`, `ChunkWriter`, stream_type 0/1/2) that alknet-tty + extends with stream_type 3. +- `/workspace/alknet-docker-poc/src/ops.rs` — `drive_attach_raw` (the + bidirectional pump pattern, the session lifecycle) that the + `TtyAdapter` generalizes. +- `docs/research/alknet-ssh/phase-0-findings.md` — DP-5 (PTY hedge, dissolved + by this crate), the channel decomposition (Layers 1-7, PTY moves out of + Layer 4), the browser case (xterm.js over WebTransport to `/alknet/tty`). +- `docs/architecture/decisions/001-alpn-protocol-dispatch.md` — ALPN dispatch +- `docs/architecture/decisions/002-protocol-handler-trait.md` — ProtocolHandler +- `docs/architecture/decisions/007-bistream-type-definition.md` — Connection, + SendStream, RecvStream +- `docs/architecture/decisions/003-crate-decomposition.md` — no-handler-depends- + on-another-handler (alknet-tty depends on alknet-core; backends depend on + alknet-tty for the trait) +- `docs/architecture/decisions/040-webtransport-alpn-stream-proxy.md` — + WebTransport stream → `Connection` (the browser terminal path) +- `/workspace/bollard/src/read.rs` — `NewlineLogOutputDecoder` (the 8-byte + header format our chunk format mirrors) +- `/workspace/russh/` — `server::Handler` (`pty_request`, `window_change`, + `signal`) — the SSH operations a `SshTtyBackend` wraps +- `/workspace/@alkdev/dispatch/` — the reverse runner that currently requires + SSH; `LocalTtyBackend` removes that requirement +- `docs/research/alknet-runtime/summary.md` — the "operation host" pattern + (alknet-tty is the same pattern for process execution) \ No newline at end of file