Struct CliChannel 

pub struct CliChannel { /* private fields */ }

CLI channel that reads from stdin and writes to stdout.

Input is read in a background task (spawned lazily on the first Channel::recv call), which makes recv() cancel-safe: dropping the future (e.g. inside a tokio::select! branch) never discards buffered input — messages stay in the internal mpsc channel and are returned on the next recv() call.

The channel automatically detects whether stdin is a TTY:

• TTY mode — uses line_editor::read_line with crossterm raw-mode for readline-style editing (cursor movement, history navigation, Ctrl-C/Ctrl-D).
• Piped mode — spawns a dedicated OS thread that reads lines from a BufReader and shuttles them through a tokio channel, avoiding repeated stdin locks.

Examples

use zeph_channels::CliChannel;
use zeph_core::channel::Channel;

let mut ch = CliChannel::new();
// Send a formatted reply to stdout.
ch.send("Hello from Zeph!").await.unwrap();

Implementations

impl CliChannel

pub fn new() -> Self

Create a new CLI channel without persistent history.

This is safe to call outside of a Tokio runtime; the background stdin reader task is not spawned until the first Channel::recv call.

pub fn with_history( entries: Vec<String>, persist_fn: impl Fn(&str) + Send + 'static, ) -> Self

Create a CLI channel with persistent input history.

entries is a pre-loaded history list (e.g. loaded from SQLite on startup). persist_fn is called for each newly submitted entry so the caller can persist it (e.g. via SqliteStore::save_input_entry).

Duplicate consecutive entries are silently ignored; empty lines are never added to the history.

Examples

use zeph_channels::CliChannel;

let previous: Vec<String> = vec!["ls -la".into(), "cargo build".into()];
let ch = CliChannel::with_history(previous, |entry| {
    // Persist `entry` to your storage layer.
    eprintln!("saving: {entry}");
});

Trait Implementations

impl Channel for CliChannel

async fn recv(&mut self) -> Result<Option<ChannelMessage>, ChannelError>

Receive the next user message.

This method is cancel-safe: dropping the future does not discard any buffered input. The background stdin reader task buffers messages in an mpsc channel; they remain available on the next recv() call.

async fn send(&mut self, text: &str) -> Result<(), ChannelError>

Write a complete agent reply to stdout.

The message is prefixed with "Zeph: " and followed by a newline. Use send_chunk / flush_chunks for streaming output instead.

Errors

Always returns Ok(()) — stdout writes do not produce recoverable errors in this adapter.

async fn send_chunk(&mut self, chunk: &str) -> Result<(), ChannelError>

Write a streaming chunk to stdout and accumulate it internally.

Chunks are printed without a trailing newline so that the response streams character-by-character. Call flush_chunks when the stream is complete to emit the final newline and clear the internal buffer.

Errors

Returns Err if the stdout flush fails.

async fn flush_chunks(&mut self) -> Result<(), ChannelError>

Finalise a streamed response by printing a trailing newline.

Clears the internal accumulation buffer so the channel is ready for the next response.

Errors

Always returns Ok(()).

async fn confirm(&mut self, prompt: &str) -> Result<bool, ChannelError>

Prompt the user for a yes/no confirmation on stdin.

In non-interactive (piped) mode the method auto-declines and returns Ok(false) without blocking. In TTY mode it reads one line and returns true only when the user types y or Y.

Errors

Returns Err if spawning the blocking task fails or if the underlying readline call returns an I/O error.

async fn elicit( &mut self, request: ElicitationRequest, ) -> Result<ElicitationResponse, ChannelError>

Collect structured input from the user on behalf of an MCP server.

Prompts the user for each field in request.fields sequentially. In non-interactive (piped) mode the method logs a warning and auto-declines without blocking.

Field values are coerced to the declared ElicitationFieldType. If a value cannot be coerced the method returns ElicitationResponse::Declined immediately. Ctrl-C or Ctrl-D returns ElicitationResponse::Cancelled.

Errors

Returns Err if spawning the blocking task fails or if the underlying readline call returns an I/O error.

fn try_recv(&mut self) -> Option<ChannelMessage>

Non-blocking receive. Returns None if no message is immediately available.

fn supports_exit(&self) -> bool

Whether /exit and /quit commands should terminate the agent loop.

fn send_typing( &mut self, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send a typing indicator. No-op by default.

fn send_status( &mut self, _text: &str, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send a status label (shown as spinner text in TUI). No-op by default.

fn send_thinking_chunk( &mut self, _chunk: &str, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send a thinking/reasoning token chunk. No-op by default.

fn send_queue_count( &mut self, _count: usize, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Notify channel of queued message count. No-op by default.

fn send_usage( &mut self, _input_tokens: u64, _output_tokens: u64, _context_window: u64, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send token usage after an LLM call. No-op by default.

fn send_diff( &mut self, _diff: DiffData, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send diff data for a tool result. No-op by default (TUI overrides).

fn send_tool_start( &mut self, _event: ToolStartEvent, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Announce that a tool call is starting.

fn send_tool_output( &mut self, event: ToolOutputEvent, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Send a complete tool output with optional diff and filter stats atomically.

fn send_stop_hint( &mut self, _hint: StopHint, ) -> impl Future<Output = Result<(), ChannelError>> + Send

Signal the non-default stop reason to the consumer before flushing.

impl Debug for CliChannel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CliChannel

fn default() -> Self

Returns the “default value” for a type.