Module shell 

ShellController: manages lifecycle of shell and command blocks. Port of Go’s pkg/blockcontroller/shellcontroller.go.

State machine: INIT ─(start)─> RUNNING ─(exit/stop)─> DONE DONE ─(resync+force)─> RUNNING

I/O model (3 async tasks when running):

1. PTY read loop: process stdout → FileStore + WPS event
2. Input loop: input channel → process stdin
3. Wait loop: monitor process exit, update status

Structs

ShellController

ShellController manages one shell or command block.

ShellControllerInner 🔒

Constants

AGENT_LINE_BUFFER_CAP 🔒

Append data to a block’s terminal output file, publish a WPS event, Maximum size of the per-block line buffer used by the agent-event translation path. Past this, the buffer is reset (a producer that never emits a newline can’t grow it unboundedly). 1 MiB is far beyond any plausible stream-json frame size.

KILL_GRACE_SECS 🔒

Inner state protected by mutex. Grace period (seconds) between SIGTERM and SIGKILL during stop().

PTY_READ_BUF_SIZE 🔒

PTY read buffer size (matches Go’s 4096).

SHELL_INPUT_CH_SIZE 🔒

Channel buffer size for shell input (matches Go’s 32).

Functions

accumulate_and_translate 🔒

Publish the events extract_agent_events produced on the WPS scope agent_event:<block_id>. Phase 1.5 PR 1 hook for agent panes. Called only when is_agent is true at spawn time (see read-task closure in start()).

detect_local_shell_path_windows 🔒

Detect the best available interactive shell on Windows.

extract_agent_events 🔒

Append chunk to line_buf, drain complete lines, JSON-parse each, and run successful parses through translator. Returns the events the translator emitted. Caller is responsible for publishing them.

handle_append_block_file

and write-through to FileStore (if provided).

handle_truncate_block_file

Truncate a block’s terminal output file and publish a WPS event. Port of Go’s HandleTruncateBlockFile.

Type Aliases

ConnFactory

Factory function type for creating ConnInterface instances. This allows dependency injection for testing.