Crate alktty 

alktty: Terminal session protocol for the alk/tty ALPN.

Producer/consumer protocol crate on top of alkcall channels. Two halves (per alkcall’s protocol-crate pattern):

• Producer half — adapter::TtyAdapter (direct alk/tty ALPN via ProtocolHandler) + channels (registers the channels/tty/sub open op via ChannelCore::register_openable for the alk/channels multiplexed path).
• Consumer half — session::TtySession (typed client wrapper around the wire protocol, with connect_direct and open_via_channels constructors).

Two-carriage wire format (ADR-052): a JSON negotiation frame, then raw chunks ([stream_type: u8][length: u32 be][payload]). Backend-agnostic via the backend::TtyBackend trait (ADR-053). Depends on alkcall (ADR-057 — the negotiation framing is self-contained; alkcall’s EventEnvelope framing is not reused).

WASM target

The default crate (no features) compiles to wasm32-unknown-unknown. The local module is feature-gated and non-wasm by design (portable-pty + tokio::process need a real OS). Downstream TS/Python adapters compile the protocol layer in a sandbox; the local-process backend runs on a real OS.

Local backend

The local backend (local::LocalTtyBackend) is gated behind the local feature. It implements backend::TtyBackend via portable_pty (PTY mode, terminal semantics) and tokio::process::Command (pipe mode, the runner case). The blocking→async bridge for PTY mode uses three dedicated std threads feeding tokio mpsc/oneshot channels (REQ-TTY-01).

Assembly pattern

let mut backends = std::collections::HashMap::new();
backends.insert(
    "local".into(),
    std::sync::Arc::new(alktty::LocalTtyBackend::new())
        as std::sync::Arc<dyn alktty::TtyBackend>,
);
let tty_adapter = alktty::TtyAdapter::new(backends);

Crate-root surface

The primary types are re-exported at the crate root — TtyAdapter/drive_session (producer), TtySession (consumer), TtyBackend/TtyHandle/TtyParams (backend authors), plus the wire codec (Chunk, ChunkReader, ChunkWriter), the wire constants (STREAM_STDOUT, MAX_CHUNK_LEN, …), ControlMessage, the negotiation types NegotiateRequest, …), the channels registration helpers (register_openable), and local::LocalTtyBackend under the local feature. The module paths below remain the full public surface — the root re-exports are the ergonomic short paths for the common imports.

Re-exports

pub use adapter::drive_session;

pub use adapter::drive_session_pre_negotiated;

pub use adapter::TtyAdapter;

pub use adapter::TTY_OPEN_SCOPE;

pub use backend::BoxFuture;

pub use backend::TerminalParams;

pub use backend::TtyBackend;

pub use backend::TtyControl;

pub use backend::TtyControlHandle;

pub use backend::TtyError;

pub use backend::TtyHandle;

pub use backend::TtyParams;

pub use channels::register_openable;

pub use channels::tty_open_spec;

pub use channels::OP_TTY_OPEN;

pub use channels::TTY_ALPN;

pub use control::signal_from_name;

pub use control::ControlMessage;

pub use negotiation::error_response_bytes;

pub use negotiation::NegotiateRequest;

pub use negotiation::NegotiationError;

pub use negotiation::NegotiationReader;

pub use negotiation::NegotiationWriter;

pub use negotiation::TerminalParamsWire;

pub use session::TtySession;

pub use session::TtySessionError;

pub use wire::Chunk;

pub use wire::ChunkReader;

pub use wire::ChunkWriter;

pub use wire::RawError;

pub use wire::CHUNK_HEADER_LEN;

pub use wire::MAX_CHUNK_LEN;

pub use wire::STREAM_CTRL_IN;

pub use wire::STREAM_CTRL_OUT;

pub use wire::STREAM_STDERR;

pub use wire::STREAM_STDIN;

pub use wire::STREAM_STDOUT;

Modules

adapter

TtyAdapter (ProtocolHandler on alk/tty) and the drive_session three-pump bidirectional driver.

backend

Backend trait and handle shapes: TtyBackend, TtyHandle, TtyControl, TtyControlHandle, TtyParams, TerminalParams, and TtyError.

channels

Producer half of the channels integration — the register_openable helper and the TtyOpenHandler factory (ADR-047 §3, amended by alkcall ADR-049 / alktty ADR-010 with an establishment phase).

control

Control messages carried in stream_type 3 (ctrl_in) and stream_type 4 (ctrl_out) chunks (ADR-052, amended Phase 7).

negotiation

Negotiation carriage: NegotiateRequest, TerminalParamsWire, length-prefixed framing reader/writer, and the error response shape.

session

Consumer half — TtySession, the typed client wrapper around the alk/tty wire protocol (per alkcall’s protocol-crate pattern).

wire

Raw chunk codec for the alk/tty bidi stream (ADR-052, Phase 2 “raw carriage”).