Split protocol and leaf surfaces into crates

Move the protocol runtime into unshell-protocol and remote shell leaf code into unshell-leaves so endpoint and TUI roles can compile independently without circular dependencies.

unshell-leaves/src/lib.rs

@@ -0,0 +1,79 @@
+//! Application-layer leaves and user-facing surfaces built on top of the UnShell
+//! protocol runtime.
+//!
+//! Each leaf module always exports its shared protocol-facing types. Role-specific
+//! implementations are selected with the crate-wide `endpoint` and `tui`
+//! features, and can optionally be re-exported behind one stable alias.
+
+use unshell::protocol::DataMessage;
+
+/// Re-exports one role-specific type behind a stable public alias.
+///
+/// This keeps consumers on a single name such as `RemoteShell` while still
+/// compiling only the role implementation needed by the current binary.
+#[macro_export]
+macro_rules! role_leaf {
+    (
+        $(#[$meta:meta])*
+        $vis:vis type $alias:ident {
+            endpoint => $endpoint:path,
+            tui => $tui:path $(,)?
+        }
+    ) => {
+        #[cfg(all(feature = "endpoint", feature = "tui"))]
+        compile_error!(concat!(
+            "`",
+            stringify!($alias),
+            "` can only alias one concrete role at a time; enable either `endpoint` or `tui`, not both"
+        ));
+
+        #[cfg(feature = "endpoint")]
+        $(#[$meta])*
+        $vis type $alias = $endpoint;
+
+        #[cfg(all(not(feature = "endpoint"), feature = "tui"))]
+        $(#[$meta])*
+        $vis type $alias = $tui;
+    };
+}
+
+/// Minimal leaf-specific TUI contract.
+///
+/// The initial implementation intentionally stays transport-agnostic. A CLI can
+/// feed validated protocol `DataMessage` values into a leaf TUI and ask it for a
+/// textual frame without depending on a specific rendering crate yet.
+pub trait LeafTui {
+    /// Returns the canonical protocol leaf name this UI understands.
+    fn leaf_name(&self) -> String;
+
+    /// Applies one inbound hook payload to the local UI state.
+    fn handle_data(&mut self, message: &DataMessage) -> Result<(), TuiError>;
+
+    /// Produces the current textual frame for the leaf.
+    fn render(&self) -> String;
+}
+
+/// Lightweight error used by the leaf TUI surface.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TuiError {
+    message: String,
+}
+
+impl TuiError {
+    /// Creates one UI-surface error from owned text.
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+impl core::fmt::Display for TuiError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl core::error::Error for TuiError {}
+
+pub mod remote_shell;

unshell-leaves/src/remote_shell/endpoint.rs

@@ -0,0 +1,96 @@
+//! PTY-backed endpoint implementation for the remote shell leaf.
+
+mod errors;
+mod session;
+mod transport;
+
+use std::collections::BTreeMap;
+
+use unshell::Leaf;
+use unshell::protocol::tree::{
+    Call, HookKey, Procedure, ProcedureEffect, ProcedureRuntime, ProcedureStore, ProtocolEndpoint,
+};
+
+pub use errors::ShellLeafError;
+pub use session::ProcedureOpen;
+pub use transport::{LISTEN_ADDR, send_forward, spawn_frame_reader, write_frames};
+
+use super::{OpenRequest, agent_path};
+
+/// Leaf state for the remote shell endpoint runtime.
+///
+/// The endpoint keeps each live shell session in an explicit map keyed by the
+/// caller-owned hook identity. That makes ownership and cleanup of hook-backed
+/// shell processes easy to inspect during debugging.
+#[derive(Default, Leaf)]
+#[leaf(leaf_name = "remote_shell")]
+pub struct RemoteShellEndpoint {
+    sessions: BTreeMap<HookKey, ProcedureOpen>,
+}
+
+impl ProcedureStore<ProcedureOpen> for RemoteShellEndpoint {
+    fn procedure_sessions(&mut self) -> &mut BTreeMap<HookKey, ProcedureOpen> {
+        &mut self.sessions
+    }
+}
+
+impl Procedure<RemoteShellEndpoint> for ProcedureOpen {
+    type Error = ShellLeafError;
+    type Input = OpenRequest;
+
+    fn open(_leaf: &mut RemoteShellEndpoint, call: Call<Self::Input>) -> Result<Self, Self::Error> {
+        let hook_key = call.response_hook.ok_or(ShellLeafError::MissingHook)?;
+        ProcedureOpen::spawn(hook_key.return_path, hook_key.hook_id, call.procedure_id)
+    }
+
+    fn on_data(
+        _leaf: &mut RemoteShellEndpoint,
+        session: &mut Self,
+        data: unshell::protocol::tree::IncomingData,
+    ) -> Result<ProcedureEffect, Self::Error> {
+        session.on_data(data)
+    }
+
+    fn on_fault(
+        _leaf: &mut RemoteShellEndpoint,
+        _session: &mut Self,
+        _fault: unshell::protocol::tree::IncomingFault,
+    ) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn poll(
+        _leaf: &mut RemoteShellEndpoint,
+        session: &mut Self,
+    ) -> Result<ProcedureEffect, Self::Error> {
+        session.poll()
+    }
+
+    fn close(_leaf: &mut RemoteShellEndpoint, mut session: Self) -> Result<(), Self::Error> {
+        session.terminate()
+    }
+}
+
+/// Builds the controller endpoint used by the receiver example.
+pub fn build_controller_endpoint() -> ProtocolEndpoint {
+    ProtocolEndpoint::new(
+        Vec::new(),
+        None,
+        vec![unshell::protocol::tree::ChildRoute::registered(agent_path())],
+        Vec::new(),
+    )
+}
+
+/// Builds the stateful shell runtime used by the endpoint example.
+pub fn build_agent_runtime() -> ProcedureRuntime<RemoteShellEndpoint, ProcedureOpen> {
+    let endpoint = ProtocolEndpoint::new(
+        agent_path(),
+        Some(Vec::new()),
+        Vec::new(),
+        vec![unshell::protocol::tree::LeafSpec {
+            name: RemoteShellEndpoint::protocol_leaf_name(),
+            procedures: vec![ProcedureOpen::protocol_procedure_id()],
+        }],
+    );
+    ProcedureRuntime::new(endpoint, RemoteShellEndpoint::default())
+}

unshell-leaves/src/remote_shell/endpoint/errors.rs

@@ -0,0 +1,28 @@
+use std::fmt;
+use std::io;
+
+/// Error produced by the remote shell endpoint implementation.
+#[derive(Debug)]
+pub enum ShellLeafError {
+    /// Underlying PTY or I/O failure.
+    Io(io::Error),
+    /// Shell open requires a response hook so the session can stream bytes back.
+    MissingHook,
+}
+
+impl fmt::Display for ShellLeafError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io(error) => write!(f, "{error}"),
+            Self::MissingHook => f.write_str("shell open requires a response hook"),
+        }
+    }
+}
+
+impl std::error::Error for ShellLeafError {}
+
+impl From<io::Error> for ShellLeafError {
+    fn from(value: io::Error) -> Self {
+        Self::Io(value)
+    }
+}

unshell-leaves/src/remote_shell/endpoint/session.rs

@@ -0,0 +1,289 @@
+//! Per-hook remote shell session lifecycle.
+//!
+//! A session opens one PTY-backed shell process and translates protocol hook
+//! traffic into stdin writes and stdout or stderr chunks. Close is intentionally
+//! two-sided: the peer signals input completion with `end_hook`, while the local
+//! side closes only after the child exits and the PTY reader drains.
+
+use std::io::{self, Read, Write};
+use std::process::Command;
+use std::sync::mpsc::{self, Receiver, SyncSender, TryRecvError};
+use std::thread;
+
+use portable_pty::{CommandBuilder, ExitStatus, PtySize, native_pty_system};
+use unshell::Procedure;
+use unshell::protocol::tree::{IncomingData, OutgoingData, ProcedureEffect};
+
+use super::RemoteShellEndpoint;
+use super::errors::ShellLeafError;
+
+/// Per-hook shell session created by the `open` procedure.
+///
+/// The procedure type is also the stored session type so the mapping between
+/// one opening procedure and one live hook remains direct and visible.
+#[derive(Procedure)]
+#[procedure(leaf = RemoteShellEndpoint, name = "open")]
+pub struct ProcedureOpen {
+    /// Spawned PTY child process.
+    pub(super) child: Box<dyn portable_pty::Child + Send>,
+    /// Process-group leader used for Unix hangup and kill signaling.
+    process_group_leader: Option<u32>,
+    /// Buffered stdin bridge into the shell process.
+    stdin_tx: Option<SyncSender<Vec<u8>>>,
+    /// Buffered output stream read from the PTY.
+    output_rx: Receiver<OutputEvent>,
+    /// Hook return path for packets emitted by this session.
+    return_path: Vec<String>,
+    /// Hook identifier allocated by the caller.
+    hook_id: u64,
+    /// Procedure id bound to this shell hook.
+    procedure_id: String,
+    /// Whether the PTY reader has closed and drained.
+    output_closed: bool,
+    /// Observed child exit status, once known.
+    pub(super) exit_status: Option<ExitStatus>,
+    /// Whether this session already emitted its terminal local packet.
+    pub(super) local_end_sent: bool,
+}
+
+/// One event forwarded from the PTY reader thread.
+enum OutputEvent {
+    Chunk(Vec<u8>),
+    ReaderClosed,
+}
+
+impl ProcedureOpen {
+    pub(super) fn spawn(
+        return_path: Vec<String>,
+        hook_id: u64,
+        procedure_id: String,
+    ) -> Result<Self, ShellLeafError> {
+        let command = build_shell_command();
+        let pty_system = native_pty_system();
+        let pair = pty_system
+            .openpty(PtySize {
+                rows: 24,
+                cols: 80,
+                pixel_width: 0,
+                pixel_height: 0,
+            })
+            .map_err(|error| io::Error::other(error.to_string()))?;
+
+        let child = pair
+            .slave
+            .spawn_command(command)
+            .map_err(|error| io::Error::other(error.to_string()))?;
+        let process_group_leader = child.process_id();
+        let stdin = pair
+            .master
+            .take_writer()
+            .map_err(|error| io::Error::other(error.to_string()))?;
+        let stdout = pair
+            .master
+            .try_clone_reader()
+            .map_err(|error| io::Error::other(error.to_string()))?;
+
+        let (stdin_tx, rx) = spawn_io_threads(stdin, stdout);
+
+        Ok(Self {
+            child,
+            process_group_leader,
+            stdin_tx: Some(stdin_tx),
+            output_rx: rx,
+            return_path,
+            hook_id,
+            procedure_id,
+            output_closed: false,
+            exit_status: None,
+            local_end_sent: false,
+        })
+    }
+
+    /// Builds one outgoing hook packet owned by this session.
+    pub(super) fn packet(&self, data: Vec<u8>, end_hook: bool) -> OutgoingData {
+        OutgoingData {
+            dst_path: self.return_path.clone(),
+            hook_id: self.hook_id,
+            procedure_id: self.procedure_id.clone(),
+            data,
+            end_hook,
+        }
+    }
+
+    /// Forces the underlying shell process to stop and records its exit status.
+    pub(super) fn terminate(&mut self) -> Result<(), ShellLeafError> {
+        self.stdin_tx.take();
+        match self.child.try_wait()? {
+            Some(status) => {
+                self.exit_status = Some(status);
+                Ok(())
+            }
+            None => {
+                self.signal_process_group("-KILL");
+                self.child
+                    .kill()
+                    .map_err(|error| io::Error::other(error.to_string()))?;
+                self.exit_status = Some(
+                    self.child
+                        .wait()
+                        .map_err(|error| io::Error::other(error.to_string()))?,
+                );
+                Ok(())
+            }
+        }
+    }
+
+    /// Drains any currently buffered PTY output into protocol packets.
+    pub(super) fn drain_output(&mut self, outgoing: &mut Vec<OutgoingData>) {
+        loop {
+            match self.output_rx.try_recv() {
+                Ok(OutputEvent::Chunk(bytes)) => outgoing.push(self.packet(bytes, false)),
+                Ok(OutputEvent::ReaderClosed) => self.output_closed = true,
+                Err(TryRecvError::Empty) => break,
+                Err(TryRecvError::Disconnected) => {
+                    self.output_closed = true;
+                    break;
+                }
+            }
+        }
+    }
+
+    /// Applies one inbound hook payload to the shell process.
+    pub(super) fn on_data(
+        &mut self,
+        data: IncomingData,
+    ) -> Result<ProcedureEffect, ShellLeafError> {
+        if !data.message.data.is_empty() {
+            let Some(stdin_tx) = self.stdin_tx.as_ref() else {
+                return Ok(ProcedureEffect::default());
+            };
+            stdin_tx.try_send(data.message.data).map_err(|_| {
+                io::Error::new(io::ErrorKind::WouldBlock, "shell stdin channel full")
+            })?;
+        }
+
+        if !data.message.end_hook {
+            return Ok(ProcedureEffect::default());
+        }
+
+        // Peer end means no more stdin from the caller. Keep the process alive so
+        // buffered PTY output can drain through the normal poll path.
+        self.stdin_tx.take();
+        self.signal_process_group("-HUP");
+        Ok(ProcedureEffect::default())
+    }
+
+    /// Polls the shell for locally-generated output.
+    pub(super) fn poll(&mut self) -> Result<ProcedureEffect, ShellLeafError> {
+        let mut outgoing = Vec::new();
+        self.drain_output(&mut outgoing);
+
+        if self.local_end_sent {
+            return Ok(ProcedureEffect::outgoing(outgoing));
+        }
+
+        if self.exit_status.is_none() {
+            self.exit_status = self
+                .child
+                .try_wait()
+                .map_err(|error| io::Error::other(error.to_string()))?;
+        }
+
+        if self.exit_status.is_some() && !self.output_closed {
+            self.signal_process_group("-KILL");
+        }
+
+        if self.exit_status.is_some() && self.output_closed {
+            outgoing.push(self.packet(Vec::new(), true));
+            self.local_end_sent = true;
+            return Ok(ProcedureEffect::close(outgoing));
+        }
+
+        Ok(ProcedureEffect::outgoing(outgoing))
+    }
+
+    fn signal_process_group(&self, signal: &str) {
+        #[cfg(unix)]
+        if let Some(process_group_leader) = self.process_group_leader {
+            let _ = Command::new("kill")
+                .arg(signal)
+                .arg(format!("-{}", process_group_leader))
+                .status();
+        }
+    }
+}
+
+impl Drop for ProcedureOpen {
+    fn drop(&mut self) {
+        let _ = self.terminate();
+    }
+}
+
+fn spawn_pipe_writer(mut stdin: Box<dyn Write + Send>, rx: Receiver<Vec<u8>>) {
+    thread::spawn(move || {
+        for bytes in rx {
+            if stdin.write_all(&bytes).is_err() {
+                break;
+            }
+            if stdin.flush().is_err() {
+                break;
+            }
+        }
+    });
+}
+
+fn build_shell_command() -> CommandBuilder {
+    if cfg!(windows) {
+        let mut command = CommandBuilder::new("cmd.exe");
+        command.arg("/Q");
+        command
+    } else {
+        let mut command = CommandBuilder::new("/bin/sh");
+        command.arg("-i");
+        command
+    }
+}
+
+fn spawn_io_threads(
+    stdin: Box<dyn Write + Send>,
+    stdout: Box<dyn Read + Send>,
+) -> (SyncSender<Vec<u8>>, Receiver<OutputEvent>) {
+    let (stdin_tx, stdin_rx) = mpsc::sync_channel(64);
+    let (tx, rx) = mpsc::sync_channel(64);
+    spawn_pipe_writer(stdin, stdin_rx);
+    spawn_pipe_reader(stdout, tx);
+    (stdin_tx, rx)
+}
+
+fn spawn_pipe_reader<R>(mut reader: R, tx: mpsc::SyncSender<OutputEvent>)
+where
+    R: Read + Send + 'static,
+{
+    thread::spawn(move || {
+        loop {
+            let mut buffer = [0u8; 1024];
+            match reader.read(&mut buffer) {
+                Ok(0) => {
+                    let _ = tx.send(OutputEvent::ReaderClosed);
+                    break;
+                }
+                Ok(read_len) => {
+                    if tx
+                        .send(OutputEvent::Chunk(buffer[..read_len].to_vec()))
+                        .is_err()
+                    {
+                        break;
+                    }
+                }
+                Err(error) if error.kind() == io::ErrorKind::Interrupted => {}
+                Err(error) => {
+                    let _ = tx.send(OutputEvent::Chunk(
+                        format!("shell pipe read error: {error}\n").into_bytes(),
+                    ));
+                    let _ = tx.send(OutputEvent::ReaderClosed);
+                    break;
+                }
+            }
+        }
+    });
+}

unshell-leaves/src/remote_shell/endpoint/transport.rs

@@ -0,0 +1,93 @@
+use std::io::{self, ErrorKind, Read, Write};
+use std::net::TcpStream;
+use std::sync::mpsc::{self, Receiver};
+use std::thread;
+
+use unshell::protocol::FrameBytes;
+use unshell::protocol::tree::EndpointOutcome;
+
+/// TCP listen address used by the remote shell examples.
+pub const LISTEN_ADDR: &str = "127.0.0.1:4444";
+const MAX_FRAME_BYTES: usize = 1024 * 1024;
+
+/// Writes the forwarded frame produced by one endpoint outcome.
+pub fn send_forward(stream: &mut TcpStream, outcome: EndpointOutcome) -> io::Result<()> {
+    match outcome {
+        EndpointOutcome::Forward { frame, .. } => write_frames(stream, &[frame]),
+        EndpointOutcome::Local(_) | EndpointOutcome::Dropped => write_frames(stream, &[]),
+    }
+}
+
+/// Writes one or more framed packets onto the example TCP stream.
+pub fn write_frames(stream: &mut TcpStream, frames: &[FrameBytes]) -> io::Result<()> {
+    for frame in frames {
+        let frame_len = u32::try_from(frame.len()).map_err(|_| {
+            io::Error::new(ErrorKind::InvalidData, "frame exceeds u32 transport size")
+        })?;
+        stream.write_all(&frame_len.to_be_bytes())?;
+        stream.write_all(frame)?;
+    }
+    stream.flush()?;
+    Ok(())
+}
+
+/// Spawns the example frame reader that lifts prefixed frames off the TCP stream.
+pub fn spawn_frame_reader(mut stream: TcpStream) -> Receiver<io::Result<FrameBytes>> {
+    let (tx, rx) = mpsc::sync_channel(64);
+
+    thread::spawn(move || {
+        loop {
+            match read_frame(&mut stream) {
+                Ok(Some(frame)) => {
+                    if tx.send(Ok(frame)).is_err() {
+                        break;
+                    }
+                }
+                Ok(None) => break,
+                Err(error) => {
+                    let _ = tx.send(Err(error));
+                    break;
+                }
+            }
+        }
+    });
+
+    rx
+}
+
+fn read_frame(stream: &mut TcpStream) -> io::Result<Option<FrameBytes>> {
+    let Some(len_bytes) = read_prefix(stream)? else {
+        return Ok(None);
+    };
+
+    let frame_len = u32::from_be_bytes(len_bytes) as usize;
+    if frame_len > MAX_FRAME_BYTES {
+        return Err(io::Error::new(
+            ErrorKind::InvalidData,
+            "frame exceeds remote shell example transport limit",
+        ));
+    }
+    let mut bytes = vec![0u8; frame_len];
+    stream.read_exact(&mut bytes)?;
+
+    let mut frame = FrameBytes::with_capacity(bytes.len());
+    frame.extend_from_slice(&bytes);
+    Ok(Some(frame))
+}
+
+fn read_prefix(stream: &mut TcpStream) -> io::Result<Option<[u8; 4]>> {
+    let mut len_bytes = [0u8; 4];
+    let mut filled = 0usize;
+
+    while filled < len_bytes.len() {
+        match stream.read(&mut len_bytes[filled..]) {
+            Ok(0) if filled == 0 => return Ok(None),
+            Ok(0) => return Err(io::Error::from(ErrorKind::UnexpectedEof)),
+            Ok(read_len) => filled += read_len,
+            Err(error) if error.kind() == ErrorKind::Interrupted => {}
+            Err(error) => return Err(error),
+        }
+    }
+
+    Ok(Some(len_bytes))
+}

unshell-leaves/src/remote_shell/mod.rs

@@ -0,0 +1,92 @@
+//! Remote shell leaf and its user-facing surfaces.
+//!
+//! The module always exports the protocol contract for the leaf. Role-specific
+//! implementations live behind crate-wide features:
+//! - `endpoint` builds the PTY-backed runtime leaf
+//! - `tui` builds a placeholder client-side TUI surface
+
+use rkyv::{Archive, Deserialize, Serialize};
+
+#[cfg(feature = "endpoint")]
+mod endpoint;
+#[cfg(feature = "tui")]
+mod tui;
+
+#[cfg(feature = "endpoint")]
+pub use endpoint::{
+    LISTEN_ADDR, RemoteShellEndpoint, ShellLeafError, build_agent_runtime,
+    build_controller_endpoint, send_forward, spawn_frame_reader, write_frames,
+};
+#[cfg(feature = "tui")]
+pub use tui::RemoteShellTui;
+
+use unshell::protocol::tree::encode_call_reply;
+
+/// Open-request payload for the remote shell leaf.
+///
+/// The shell currently needs no structured arguments, but a named payload type is
+/// easier for downstream code to discover than a bare `()`.
+#[derive(Archive, Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
+pub struct OpenRequest;
+
+crate::role_leaf! {
+    /// Feature-selected remote shell surface.
+    pub type RemoteShell {
+        endpoint => endpoint::RemoteShellEndpoint,
+        tui => tui::RemoteShellTui,
+    }
+}
+
+/// Returns the example endpoint path used by the remote shell samples.
+pub fn agent_path() -> Vec<String> {
+    path(&["agent"])
+}
+
+/// Returns the canonical leaf id used by endpoint and TUI code.
+#[cfg(feature = "endpoint")]
+pub fn shell_leaf_name() -> String {
+    RemoteShellEndpoint::protocol_leaf_name()
+}
+
+/// Returns the canonical opening `procedure_id` for the shell leaf.
+#[cfg(feature = "endpoint")]
+pub fn shell_open_procedure() -> String {
+    endpoint::ProcedureOpen::protocol_procedure_id()
+}
+
+/// Encodes the empty open-request payload used by the shell example.
+#[cfg(all(not(feature = "endpoint"), feature = "tui"))]
+pub fn shell_leaf_name() -> String {
+    RemoteShellTui::protocol_leaf_name()
+}
+
+/// Returns the canonical opening `procedure_id` for the shell leaf.
+#[cfg(all(not(feature = "endpoint"), feature = "tui"))]
+pub fn shell_open_procedure() -> String {
+    let mut procedure_id = shell_leaf_name();
+    procedure_id.push_str(".open");
+    procedure_id
+}
+
+/// Encodes the empty open-request payload used by the shell example.
+#[cfg(not(any(feature = "endpoint", feature = "tui")))]
+pub fn shell_leaf_name() -> String {
+    String::from("remote_shell")
+}
+
+/// Returns the canonical opening `procedure_id` for the shell leaf.
+#[cfg(not(any(feature = "endpoint", feature = "tui")))]
+pub fn shell_open_procedure() -> String {
+    let mut procedure_id = shell_leaf_name();
+    procedure_id.push_str(".open");
+    procedure_id
+}
+
+/// Encodes the empty open-request payload used by the shell example.
+pub fn shell_open_payload() -> Vec<u8> {
+    encode_call_reply(&OpenRequest).expect("remote shell open payload should encode")
+}
+
+fn path(parts: &[&str]) -> Vec<String> {
+    parts.iter().map(|part| (*part).to_owned()).collect()
+}

unshell-leaves/src/remote_shell/tui.rs

@@ -0,0 +1,43 @@
+//! Placeholder client-side TUI surface for the remote shell leaf.
+//!
+//! The first application-layer consumer will be a CLI and later a full GUI. This
+//! stub keeps the leaf-specific interpretation point in place without forcing a
+//! rendering-library decision yet.
+
+use std::string::String;
+use std::vec::Vec;
+
+use unshell::Leaf;
+use unshell::protocol::DataMessage;
+
+use crate::{LeafTui, TuiError};
+
+/// Stub TUI surface for the remote shell leaf.
+#[derive(Default, Leaf)]
+#[leaf(leaf_name = "remote_shell")]
+pub struct RemoteShellTui {
+    transcript: Vec<u8>,
+}
+
+impl RemoteShellTui {
+    /// Returns a short explanation of the current stub status.
+    pub fn status_line(&self) -> &'static str {
+        "remote shell TUI stub: rendering is placeholder-only for now"
+    }
+}
+
+impl LeafTui for RemoteShellTui {
+    fn leaf_name(&self) -> String {
+        Self::protocol_leaf_name()
+    }
+
+    fn handle_data(&mut self, message: &DataMessage) -> Result<(), TuiError> {
+        self.transcript.extend_from_slice(&message.data);
+        Ok(())
+    }
+
+    fn render(&self) -> String {
+        let body = String::from_utf8_lossy(&self.transcript);
+        format!("{}\n\n{}", self.status_line(), body)
+    }
+}