Add stateful call leaf runtime

examples/protocol/bench/support/bench_common.rs

@@ -195,7 +195,9 @@ pub fn run_hook_data_receive(iterations: usize) -> usize {
             .receive(&Ingress::Child(path(&["worker"])), frame)
             .expect("hook data should work");
         match outcome.event {
-            Some(LocalEvent::Data { header, message }) => {
+            Some(LocalEvent::Data {
+                header, message, ..
+            }) => {
                 checksum = checksum
                     .wrapping_add(header.hook_id.unwrap_or_default() as usize)
                     .wrapping_add(message.data.len())

examples/protocol/leaf_derive.rs

@@ -1,46 +1,101 @@
 use std::error::Error;
+use std::{convert::Infallible, string::String};
 
-use unshell::Leaf;
-use unshell::protocol::tree::{Endpoint, Ingress, LocalEvent, ProtocolEndpoint};
+use rkyv::{Archive, Deserialize, Serialize};
+use unshell::protocol::tree::{Call, CallLeaf, Ingress, LeafRuntime, ProtocolEndpoint};
+use unshell::protocol::tree::{ChildRoute, ConnectionState};
+use unshell::protocol::{PacketType, decode_frame};
+use unshell::{Leaf, procedures};
 
 #[derive(Leaf)]
 #[leaf(org = "org", product = "example", version = "v1", leaf_name = "echo")]
-#[leaf(procedures(call, stream))]
-struct EchoLeaf;
+struct EchoLeaf {
+    prefix: String,
+}
+
+#[derive(Archive, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+struct EchoRequest {
+    text: String,
+}
+
+#[derive(Archive, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+struct EchoResponse {
+    text: String,
+}
+
+#[procedures(error = Infallible)]
+impl EchoLeaf {
+    #[call]
+    fn echo(&mut self, request: Call<EchoRequest>) -> EchoResponse {
+        EchoResponse {
+            text: format!("{}{}", self.prefix, request.input.text),
+        }
+    }
+}
+
+impl CallLeaf for EchoLeaf {
+    type Error = Infallible;
+}
 
 fn path(parts: &[&str]) -> Vec<String> {
     parts.iter().map(|part| (*part).to_owned()).collect()
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
-    let mut endpoint = ProtocolEndpoint::new(
+    let endpoint = ProtocolEndpoint::new(
         path(&["agent"]),
         Some(Vec::new()),
         Vec::new(),
         vec![EchoLeaf::protocol_leaf_spec()],
     );
+    let mut runtime = LeafRuntime::new(
+        endpoint,
+        EchoLeaf {
+            prefix: String::from("echo: "),
+        },
+    );
 
-    let hook_id = endpoint.allocate_hook_id();
-    let frame = endpoint.make_call(
+    let mut controller = ProtocolEndpoint::new(
+        Vec::new(),
+        None,
+        vec![ChildRoute {
+            path: path(&["agent"]),
+            state: ConnectionState::Registered,
+        }],
+        Vec::new(),
+    );
+    let hook_id = controller.allocate_hook_id();
+    let controller_outcome = controller.send_call(
         path(&["agent"]),
         Some(EchoLeaf::protocol_leaf_name()),
-        EchoLeaf::protocol_procedure_id("call").expect("known procedure suffix"),
+        EchoLeaf::protocol_procedure_id("echo").expect("known procedure suffix"),
         Some(hook_id),
-        b"hello leaf".to_vec(),
+        unshell::protocol::tree::encode_call_reply(&EchoRequest {
+            text: String::from("hello leaf"),
+        })?,
     )?;
-
-    let outcome = endpoint.receive(&Ingress::Parent, frame)?;
-    let Some(LocalEvent::Call { header, message }) = outcome.event else {
-        return Err("expected local leaf call".into());
+    let Some((_, frame)) = controller_outcome.forward else {
+        return Err("expected controller to forward call".into());
     };
 
-    assert_eq!(header.dst_leaf.as_deref(), Some("org.example.v1.echo"));
-    assert_eq!(message.procedure_id, "org.example.v1.echo.call");
+    let outcome = runtime.receive(&Ingress::Parent, frame)?;
+    let [response_frame] = outcome.frames.as_slice() else {
+        return Err("expected one response frame".into());
+    };
+    let parsed = decode_frame(response_frame.as_slice())?;
+    assert_eq!(parsed.packet_type(), PacketType::Data);
+    let response = unshell::protocol::tree::decode_call_input::<EchoResponse>(
+        parsed.deserialize_data()?.data.as_slice(),
+    )?;
+
+    assert_eq!(EchoLeaf::protocol_leaf_name(), "org.example.v1.echo");
+    assert_eq!(response.text, "echo: hello leaf");
 
     println!(
-        "leaf={} procedure={}",
+        "leaf={} procedure={} response={}",
         EchoLeaf::protocol_leaf_name(),
-        message.procedure_id
+        EchoLeaf::protocol_procedure_id("echo").expect("known procedure suffix"),
+        response.text,
     );
     Ok(())
 }

examples/protocol/remote_shell_endpoint.rs

@@ -2,36 +2,16 @@
 mod common;
 
 use std::error::Error;
-use std::io::{self, Read, Write};
 use std::net::TcpStream;
-use std::process::{Child, ChildStdin, Command, ExitStatus, Stdio};
-use std::sync::mpsc::{self, Receiver, RecvTimeoutError, Sender};
-use std::thread;
+use std::sync::mpsc::RecvTimeoutError;
 use std::time::Duration;
 
-use unshell::protocol::tree::{Endpoint, Ingress, LocalEvent};
-
-struct ShellSession {
-    child: Child,
-    stdin: Option<ChildStdin>,
-    return_path: Vec<String>,
-    hook_id: u64,
-    procedure_id: String,
-    readers_closed: usize,
-    exit_status: Option<ExitStatus>,
-}
-
-enum OutputEvent {
-    Chunk(Vec<u8>),
-    ReaderClosed,
-}
+use unshell::protocol::tree::Ingress;
 
 fn main() -> Result<(), Box<dyn Error>> {
     let mut stream = TcpStream::connect(common::LISTEN_ADDR)?;
     let frame_rx = common::spawn_frame_reader(stream.try_clone()?);
-    let mut endpoint = common::build_agent_endpoint();
-    let mut session: Option<ShellSession> = None;
-    let mut output_rx: Option<Receiver<OutputEvent>> = None;
+    let mut runtime = common::build_agent_runtime();
 
     println!("connected to controller at {}", common::LISTEN_ADDR);
 
@@ -39,241 +19,16 @@ fn main() -> Result<(), Box<dyn Error>> {
         match frame_rx.recv_timeout(Duration::from_millis(25)) {
             Ok(result) => {
                 let frame = result?;
-                let outcome = endpoint.receive(&Ingress::Parent, frame)?;
-                if let Some(event) = common::pump_outcome(&mut stream, outcome)? {
-                    handle_local_event(
-                        &mut endpoint,
-                        &mut stream,
-                        &mut session,
-                        &mut output_rx,
-                        event,
-                    )?;
-                }
+                let outcome = runtime.receive(&Ingress::Parent, frame)?;
+                common::write_frames(&mut stream, &outcome.frames)?;
             }
             Err(RecvTimeoutError::Timeout) => {}
             Err(RecvTimeoutError::Disconnected) => break,
         }
 
-        if let Some(rx) = output_rx.as_ref() {
-            while let Ok(event) = rx.try_recv() {
-                handle_shell_output(&mut endpoint, &mut stream, &mut session, event)?;
-            }
-        }
-
-        if finalize_exited_shell(&mut endpoint, &mut stream, &mut session)? {
-            output_rx = None;
-        }
+        let outcome = runtime.poll()?;
+        common::write_frames(&mut stream, &outcome.frames)?;
     }
 
     Ok(())
 }
-
-fn handle_local_event(
-    endpoint: &mut unshell::protocol::tree::ProtocolEndpoint,
-    stream: &mut TcpStream,
-    session: &mut Option<ShellSession>,
-    output_rx: &mut Option<Receiver<OutputEvent>>,
-    event: LocalEvent,
-) -> Result<(), Box<dyn Error>> {
-    match event {
-        LocalEvent::Call { header, message } => {
-            let shell_leaf_name = common::shell_leaf_name();
-            let start_procedure = common::shell_start_procedure();
-            if header.dst_leaf.as_deref() != Some(shell_leaf_name.as_str())
-                || message.procedure_id != start_procedure
-            {
-                return Ok(());
-            }
-
-            let Some(hook) = message.response_hook else {
-                return Ok(());
-            };
-
-            let (new_session, rx) =
-                start_shell(&hook.return_path, hook.hook_id, &message.procedure_id)?;
-            *session = Some(new_session);
-            *output_rx = Some(rx);
-
-            let outcome = endpoint.send_data(
-                hook.return_path,
-                hook.hook_id,
-                message.procedure_id,
-                b"shell ready\n".to_vec(),
-                false,
-            )?;
-            let _ = common::pump_outcome(stream, outcome)?;
-        }
-        LocalEvent::Data { message, .. } => {
-            let Some(active_session) = session.as_mut() else {
-                return Ok(());
-            };
-
-            if !message.data.is_empty() {
-                let Some(stdin) = active_session.stdin.as_mut() else {
-                    return Ok(());
-                };
-                stdin.write_all(&message.data)?;
-                stdin.flush()?;
-            }
-
-            if message.end_hook {
-                active_session.stdin.take();
-            }
-        }
-        LocalEvent::Fault { message, .. } => {
-            eprintln!(
-                "controller reported protocol fault: 0x{:02X}",
-                message.fault.0
-            );
-        }
-    }
-
-    Ok(())
-}
-
-fn handle_shell_output(
-    endpoint: &mut unshell::protocol::tree::ProtocolEndpoint,
-    stream: &mut TcpStream,
-    session: &mut Option<ShellSession>,
-    event: OutputEvent,
-) -> Result<(), Box<dyn Error>> {
-    let Some(active_session) = session.as_mut() else {
-        return Ok(());
-    };
-
-    match event {
-        OutputEvent::Chunk(bytes) => {
-            let outcome = endpoint.send_data(
-                active_session.return_path.clone(),
-                active_session.hook_id,
-                active_session.procedure_id.clone(),
-                bytes,
-                false,
-            )?;
-            let _ = common::pump_outcome(stream, outcome)?;
-        }
-        OutputEvent::ReaderClosed => {
-            active_session.readers_closed += 1;
-        }
-    }
-
-    Ok(())
-}
-
-fn finalize_exited_shell(
-    endpoint: &mut unshell::protocol::tree::ProtocolEndpoint,
-    stream: &mut TcpStream,
-    session: &mut Option<ShellSession>,
-) -> Result<bool, Box<dyn Error>> {
-    let Some(active_session) = session.as_mut() else {
-        return Ok(false);
-    };
-
-    if active_session.exit_status.is_none() {
-        active_session.exit_status = active_session.child.try_wait()?;
-    }
-
-    let Some(exit_status) = active_session.exit_status else {
-        return Ok(false);
-    };
-    if active_session.readers_closed < 2 {
-        return Ok(false);
-    }
-
-    let summary = format!("shell exited with {exit_status}\n");
-    let outcome = endpoint.send_data(
-        active_session.return_path.clone(),
-        active_session.hook_id,
-        active_session.procedure_id.clone(),
-        summary.into_bytes(),
-        true,
-    )?;
-    let _ = common::pump_outcome(stream, outcome)?;
-    *session = None;
-    Ok(true)
-}
-
-fn start_shell(
-    return_path: &[String],
-    hook_id: u64,
-    procedure_id: &str,
-) -> io::Result<(ShellSession, Receiver<OutputEvent>)> {
-    let mut command = if cfg!(windows) {
-        let mut command = Command::new("cmd.exe");
-        command.arg("/Q");
-        command
-    } else {
-        let mut command = Command::new("/bin/sh");
-        command.arg("-i");
-        command
-    };
-
-    let mut child = command
-        .stdin(Stdio::piped())
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .spawn()?;
-
-    let stdin = child
-        .stdin
-        .take()
-        .ok_or_else(|| io::Error::other("failed to capture shell stdin"))?;
-    let stdout = child
-        .stdout
-        .take()
-        .ok_or_else(|| io::Error::other("failed to capture shell stdout"))?;
-    let stderr = child
-        .stderr
-        .take()
-        .ok_or_else(|| io::Error::other("failed to capture shell stderr"))?;
-
-    let (tx, rx) = mpsc::channel();
-    spawn_pipe_reader(stdout, tx.clone());
-    spawn_pipe_reader(stderr, tx);
-
-    Ok((
-        ShellSession {
-            child,
-            stdin: Some(stdin),
-            return_path: return_path.to_vec(),
-            hook_id,
-            procedure_id: procedure_id.to_owned(),
-            readers_closed: 0,
-            exit_status: None,
-        },
-        rx,
-    ))
-}
-
-fn spawn_pipe_reader<R>(mut reader: R, tx: Sender<OutputEvent>)
-where
-    R: Read + Send + 'static,
-{
-    thread::spawn(move || {
-        let mut buffer = [0u8; 1024];
-        loop {
-            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;
-                }
-            }
-        }
-    });
-}

examples/protocol/remote_shell_receive.rs

@@ -17,25 +17,46 @@ fn main() -> Result<(), Box<dyn Error>> {
     let mut endpoint = common::build_controller_endpoint();
     let hook_id = endpoint.allocate_hook_id();
     let shell_leaf_name = common::shell_leaf_name();
-    let start_procedure = common::shell_start_procedure();
+    let open_procedure = common::shell_open_procedure();
 
     let outcome = endpoint.send_call(
         common::agent_path(),
         Some(shell_leaf_name),
-        start_procedure.clone(),
+        open_procedure.clone(),
         Some(hook_id),
-        Vec::new(),
+        common::shell_open_payload(),
+    )?;
+    common::write_frames(
+        &mut stream,
+        &outcome
+            .forward
+            .into_iter()
+            .map(|(_, frame)| frame)
+            .collect::<Vec<_>>(),
     )?;
-    let _ = common::pump_outcome(&mut stream, outcome)?;
 
-    let mut commands_sent = false;
+    for (index, command) in ["pwd\n", "whoami\n", "exit\n"].iter().enumerate() {
+        let outcome = endpoint.send_data(
+            common::agent_path(),
+            hook_id,
+            open_procedure.clone(),
+            command.as_bytes().to_vec(),
+            index == 2,
+        )?;
+        common::write_frames(
+            &mut stream,
+            &outcome
+                .forward
+                .into_iter()
+                .map(|(_, frame)| frame)
+                .collect::<Vec<_>>(),
+        )?;
+    }
 
     for result in frame_rx {
         let frame = result?;
         let outcome = endpoint.receive(&Ingress::Child(common::agent_path()), frame)?;
-        let event = common::pump_outcome(&mut stream, outcome)?;
-
-        let Some(event) = event else {
+        let Some(event) = outcome.event else {
             continue;
         };
 
@@ -43,20 +64,6 @@ fn main() -> Result<(), Box<dyn Error>> {
             LocalEvent::Data { message, .. } => {
                 print!("{}", String::from_utf8_lossy(&message.data));
 
-                if !commands_sent {
-                    commands_sent = true;
-                    for (index, command) in ["pwd\n", "whoami\n", "exit\n"].iter().enumerate() {
-                        let outcome = endpoint.send_data(
-                            common::agent_path(),
-                            hook_id,
-                            start_procedure.clone(),
-                            command.as_bytes().to_vec(),
-                            index == 2,
-                        )?;
-                        let _ = common::pump_outcome(&mut stream, outcome)?;
-                    }
-                }
-
                 if message.end_hook {
                     break;
                 }

examples/protocol/support/remote_shell_common.rs

@@ -1,17 +1,124 @@
+use std::collections::BTreeMap;
+use std::fmt;
 use std::io::{self, ErrorKind, Read, Write};
 use std::net::TcpStream;
-use std::sync::mpsc::{self, Receiver};
+use std::process::{Child, ChildStdin, Command, ExitStatus, Stdio};
+use std::sync::mpsc::{self, Receiver, TryRecvError};
 use std::thread;
 
-use unshell::Leaf;
 use unshell::protocol::FrameBytes;
-use unshell::protocol::tree::{ChildRoute, EndpointOutcome, LocalEvent, ProtocolEndpoint};
+use unshell::protocol::tree::{
+    Call, CallLeaf, ChildRoute, HookKey, IncomingData, IncomingFault, LeafRuntime, OutgoingData,
+    ProtocolEndpoint,
+};
+use unshell::{Leaf, procedures};
 
 pub const LISTEN_ADDR: &str = "127.0.0.1:4444";
 
-#[derive(Leaf)]
-#[leaf(procedures(start))]
-pub struct RemoteShellLeaf;
+#[derive(Default, Leaf)]
+pub struct RemoteShellLeaf {
+    sessions: BTreeMap<HookKey, ShellSession>,
+}
+
+#[procedures(error = ShellLeafError)]
+impl RemoteShellLeaf {
+    #[call]
+    fn open(&mut self, call: Call<()>) -> Result<(), ShellLeafError> {
+        let hook_key = call.response_hook.ok_or(ShellLeafError::MissingHook)?;
+        let session = ShellSession::spawn(
+            hook_key.return_path.clone(),
+            hook_key.hook_id,
+            call.procedure_id,
+        )?;
+
+        if let Some(mut previous) = self.sessions.insert(hook_key, session) {
+            previous.terminate()?;
+        }
+        Ok(())
+    }
+}
+
+impl CallLeaf for RemoteShellLeaf {
+    type Error = ShellLeafError;
+
+    fn on_data(&mut self, data: IncomingData) -> Result<Vec<OutgoingData>, Self::Error> {
+        let Some(session) = self.sessions.get_mut(&data.hook_key) else {
+            return Ok(Vec::new());
+        };
+
+        if !data.message.data.is_empty() {
+            let Some(stdin) = session.stdin.as_mut() else {
+                return Ok(Vec::new());
+            };
+            stdin.write_all(&data.message.data)?;
+            stdin.flush()?;
+        }
+
+        if !data.message.end_hook {
+            return Ok(Vec::new());
+        }
+
+        let session = self
+            .sessions
+            .remove(&data.hook_key)
+            .ok_or(ShellLeafError::MissingSession)?;
+        close_session(session)
+    }
+
+    fn on_fault(&mut self, fault: IncomingFault) -> Result<(), Self::Error> {
+        if let Some(mut session) = self.sessions.remove(&fault.hook_key) {
+            session.terminate()?;
+        }
+        Ok(())
+    }
+
+    fn poll(&mut self) -> Result<Vec<OutgoingData>, Self::Error> {
+        let mut outgoing = Vec::new();
+        let mut closed = Vec::new();
+
+        for key in self.sessions.keys().cloned().collect::<Vec<_>>() {
+            let Some(session) = self.sessions.get_mut(&key) else {
+                continue;
+            };
+
+            loop {
+                match session.output_rx.try_recv() {
+                    Ok(OutputEvent::Chunk(bytes)) => {
+                        outgoing.push(session.packet(bytes, false));
+                    }
+                    Ok(OutputEvent::ReaderClosed) => {
+                        session.readers_closed += 1;
+                    }
+                    Err(TryRecvError::Empty) => break,
+                    Err(TryRecvError::Disconnected) => {
+                        session.readers_closed = 2;
+                        break;
+                    }
+                }
+            }
+
+            if session.local_end_sent {
+                continue;
+            }
+
+            if session.exit_status.is_none() {
+                session.exit_status = session.child.try_wait()?;
+            }
+
+            if session.exit_status.is_some() && session.readers_closed >= 2 {
+                outgoing.push(session.packet(Vec::new(), true));
+                session.local_end_sent = true;
+                closed.push(key);
+            }
+        }
+
+        for key in closed {
+            self.sessions.remove(&key);
+        }
+
+        Ok(outgoing)
+    }
+}
 
 pub fn agent_path() -> Vec<String> {
     path(&["agent"])
@@ -32,22 +139,30 @@ pub fn build_controller_endpoint() -> ProtocolEndpoint {
 }
 
 #[allow(dead_code)]
-pub fn build_agent_endpoint() -> ProtocolEndpoint {
-    ProtocolEndpoint::new(
+pub fn build_agent_runtime() -> LeafRuntime<RemoteShellLeaf> {
+    let endpoint = ProtocolEndpoint::new(
         agent_path(),
         Some(Vec::new()),
         Vec::new(),
         vec![RemoteShellLeaf::protocol_leaf_spec()],
-    )
+    );
+    LeafRuntime::new(endpoint, RemoteShellLeaf::default())
 }
 
+#[allow(dead_code)]
 pub fn shell_leaf_name() -> String {
     RemoteShellLeaf::protocol_leaf_name()
 }
 
-pub fn shell_start_procedure() -> String {
-    RemoteShellLeaf::protocol_procedure_id("start")
-        .expect("remote shell leaf declares a start procedure")
+#[allow(dead_code)]
+pub fn shell_open_procedure() -> String {
+    RemoteShellLeaf::protocol_procedure_id("open")
+        .expect("remote shell leaf declares an open procedure")
+}
+
+#[allow(dead_code)]
+pub fn shell_open_payload() -> Vec<u8> {
+    unshell::protocol::tree::encode_call_reply(&()).expect("unit shell open payload should encode")
 }
 
 pub fn write_frame(stream: &mut TcpStream, frame: &[u8]) -> io::Result<()> {
@@ -59,17 +174,11 @@ pub fn write_frame(stream: &mut TcpStream, frame: &[u8]) -> io::Result<()> {
     Ok(())
 }
 
-pub fn pump_outcome(
-    stream: &mut TcpStream,
-    outcome: EndpointOutcome,
-) -> io::Result<Option<LocalEvent>> {
-    if let Some((_route, frame)) = outcome.forward {
-        // These examples model one direct parent-child link over one TCP stream, so
-        // any forwarded protocol frame is emitted on the same socket.
-        write_frame(stream, &frame)?;
+pub fn write_frames(stream: &mut TcpStream, frames: &[FrameBytes]) -> io::Result<()> {
+    for frame in frames {
+        write_frame(stream, frame)?;
     }
-
-    Ok(outcome.event)
+    Ok(())
 }
 
 pub fn spawn_frame_reader(mut stream: TcpStream) -> Receiver<io::Result<FrameBytes>> {
@@ -95,6 +204,16 @@ pub fn spawn_frame_reader(mut stream: TcpStream) -> Receiver<io::Result<FrameByt
     rx
 }
 
+fn close_session(mut session: ShellSession) -> Result<Vec<OutgoingData>, ShellLeafError> {
+    session.terminate()?;
+    if session.local_end_sent {
+        return Ok(Vec::new());
+    }
+
+    session.local_end_sent = true;
+    Ok(vec![session.packet(Vec::new(), true)])
+}
+
 fn read_frame(stream: &mut TcpStream) -> io::Result<Option<FrameBytes>> {
     let mut len_bytes = [0u8; 4];
     match stream.read_exact(&mut len_bytes) {
@@ -115,3 +234,156 @@ fn read_frame(stream: &mut TcpStream) -> io::Result<Option<FrameBytes>> {
     frame.extend_from_slice(&bytes);
     Ok(Some(frame))
 }
+
+struct ShellSession {
+    child: Child,
+    stdin: Option<ChildStdin>,
+    output_rx: Receiver<OutputEvent>,
+    return_path: Vec<String>,
+    hook_id: u64,
+    procedure_id: String,
+    readers_closed: usize,
+    exit_status: Option<ExitStatus>,
+    local_end_sent: bool,
+}
+
+enum OutputEvent {
+    Chunk(Vec<u8>),
+    ReaderClosed,
+}
+
+impl ShellSession {
+    fn spawn(
+        return_path: Vec<String>,
+        hook_id: u64,
+        procedure_id: String,
+    ) -> Result<Self, ShellLeafError> {
+        let mut command = if cfg!(windows) {
+            let mut command = Command::new("cmd.exe");
+            command.arg("/Q");
+            command
+        } else {
+            let mut command = Command::new("/bin/sh");
+            command.arg("-i");
+            command
+        };
+
+        let mut child = command
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()?;
+
+        let stdin = child
+            .stdin
+            .take()
+            .ok_or_else(|| io::Error::other("failed to capture shell stdin"))?;
+        let stdout = child
+            .stdout
+            .take()
+            .ok_or_else(|| io::Error::other("failed to capture shell stdout"))?;
+        let stderr = child
+            .stderr
+            .take()
+            .ok_or_else(|| io::Error::other("failed to capture shell stderr"))?;
+
+        let (tx, rx) = mpsc::channel();
+        spawn_pipe_reader(stdout, tx.clone());
+        spawn_pipe_reader(stderr, tx);
+
+        Ok(Self {
+            child,
+            stdin: Some(stdin),
+            output_rx: rx,
+            return_path,
+            hook_id,
+            procedure_id,
+            readers_closed: 0,
+            exit_status: None,
+            local_end_sent: false,
+        })
+    }
+
+    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,
+        }
+    }
+
+    fn terminate(&mut self) -> Result<(), ShellLeafError> {
+        self.stdin.take();
+        match self.child.try_wait()? {
+            Some(status) => {
+                self.exit_status = Some(status);
+                Ok(())
+            }
+            None => {
+                self.child.kill()?;
+                self.exit_status = Some(self.child.wait()?);
+                Ok(())
+            }
+        }
+    }
+}
+
+fn spawn_pipe_reader<R>(mut reader: R, tx: mpsc::Sender<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;
+                }
+            }
+        }
+    });
+}
+
+#[derive(Debug)]
+pub enum ShellLeafError {
+    Io(io::Error),
+    MissingHook,
+    MissingSession,
+}
+
+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"),
+            Self::MissingSession => f.write_str("shell session missing for active hook"),
+        }
+    }
+}
+
+impl std::error::Error for ShellLeafError {}
+
+impl From<io::Error> for ShellLeafError {
+    fn from(value: io::Error) -> Self {
+        Self::Io(value)
+    }
+}