Struct ShellController 

pub struct ShellController {
    controller_type: String,
    tab_id: String,
    block_id: String,
    run_lock: Arc<AtomicBool>,
    inner: Arc<Mutex<ShellControllerInner>>,
    conn_factory: Mutex<Option<Box<dyn Fn(&str, &HashMap<String, Value>) -> Result<Box<dyn ConnInterface>, String> + Send + Sync>>>,
    broker: Option<Arc<Broker>>,
    event_bus: Option<Arc<EventBus>>,
    wstore: Option<Arc<Store>>,
}

ShellController manages one shell or command block.

Fields

controller_type: String

Controller type: “shell” or “cmd”.

tab_id: String

block_id: String

run_lock: Arc<AtomicBool>

Prevents concurrent run() calls.

inner: Arc<Mutex<ShellControllerInner>>

Protected inner state.

conn_factory: Mutex<Option<Box<dyn Fn(&str, &HashMap<String, Value>) -> Result<Box<dyn ConnInterface>, String> + Send + Sync>>>

Optional factory for creating ConnInterface (for testing).

broker: Option<Arc<Broker>>

WPS broker for publishing events (blockfile, controllerstatus).

event_bus: Option<Arc<EventBus>>

Event bus (unused for now, reserved for future event routing).

wstore: Option<Arc<Store>>

Wave object store — used to seed cmd:cwd on shell spawn.

Implementations

impl ShellController

pub fn new( controller_type: String, tab_id: String, block_id: String, broker: Option<Arc<Broker>>, event_bus: Option<Arc<EventBus>>, wstore: Option<Arc<Store>>, ) -> Self

Create a new ShellController.

pub fn set_conn_factory( &self, factory: Box<dyn Fn(&str, &HashMap<String, Value>) -> Result<Box<dyn ConnInterface>, String> + Send + Sync>, )

Set a custom ConnInterface factory (for testing).

fn try_lock_run(&self) -> bool

Try to acquire the run lock. Returns false if already running.

fn unlock_run(&self)

Release the run lock.

fn set_status(inner: &mut ShellControllerInner, status: &str)

Update process status and increment version (must hold inner lock).

fn get_status_snapshot(&self) -> BlockControllerRuntimeStatus

Get the runtime status (snapshot).

pub fn last_output_secs_ago(&self) -> Option<u64>

Seconds since last PTY output, or None if no output yet.

pub fn is_agent_pane(&self) -> bool

True if this pane is running an agent CLI.

fn should_run_on_start(meta: &HashMap<String, Value>) -> bool

Check block meta for whether to run on start.

fn should_run_once(meta: &HashMap<String, Value>) -> bool

Check block meta for run-once mode (used in full lifecycle integration).

fn should_clear_on_start(meta: &HashMap<String, Value>) -> bool

Check block meta for clear-on-start (used in full lifecycle integration).

fn should_close_on_exit(meta: &HashMap<String, Value>) -> bool

Check block meta for close-on-exit (used in full lifecycle integration).

fn should_close_on_exit_force(meta: &HashMap<String, Value>) -> bool

Check block meta for force close-on-exit (used in full lifecycle integration).

fn close_on_exit_delay_ms(meta: &HashMap<String, Value>) -> u64

Get the close-on-exit delay in ms (defaults to 2000, used in full lifecycle integration).

fn get_conn_name(meta: &HashMap<String, Value>) -> String

Get the connection name from block meta.

fn get_cmd_str(meta: &HashMap<String, Value>) -> String

Get the command string from block meta.

fn get_cmd_args(meta: &HashMap<String, Value>) -> Vec<String>

Get cmd:args array from block meta.

fn is_interactive(meta: &HashMap<String, Value>) -> bool

Check if cmd:interactive is set in block meta.

fn publish_status(&self)

Publish current controller status via the WPS broker.

fn pty_size_from_rt_opts(rt_opts: &Option<Value>) -> PtySize

Resolve the initial PTY geometry from the resync rt_opts payload.

The agent pane is a custom UI (not xterm.js), so the PTY never receives a fitAddon resize and must be born at the right width — otherwise the first batch of agent/tool output wraps at the fallback width until a post-spawn resize RPC lands, and that RPC races controller startup (it can fail outright). The frontend computes cols from the pane and passes them as rtopts.termsize on the controllerresync command (see usePtyWidth.ts / launch-flow.ts).

Falls back to the historical 25x200 default when rt_opts is absent, unparseable, or carries the serde-default termsize (rows==0 && cols==0, per obj::is_default_term_size). Per-field guards let a cols-only payload keep the default row count. Each axis is clamped to [1, 1000] so the i64 → u16 cast is lossless and a bogus value cannot open a zero-size or wrapped-size PTY. See docs/analysis/AGENT_PANE_PTY_RESIZE_RACE_2026_06_16.md.

Trait Implementations

impl Controller for ShellController

fn start( &self, block_meta: HashMap<String, Value>, rt_opts: Option<Value>, force: bool, ) -> Result<(), String>

Start the controller. May spawn background tasks. force restarts even if already running.

fn stop(&self, _graceful: bool, new_status: &str) -> Result<(), String>

Stop the controller. graceful waits for process to exit; new_status is the target state.

fn get_runtime_status(&self) -> BlockControllerRuntimeStatus

Get the current runtime status.

fn send_input( &self, input: BlockInputUnion, seq: Option<u64>, ) -> Result<(), String>

Send input (terminal data, signal, or resize) to the controller. seq is the per-TermViewModel monotonic counter; None means fire-and-forget (no ordering).

fn controller_type(&self) -> &str

Get the controller type (e.g., “shell”, “cmd”).

fn block_id(&self) -> &str

Get the block ID.

fn as_any(&self) -> &dyn Any

Downcast support for concrete controller types.