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().

OUTPUT_IDX_HEADER_LEN 🔒

Magic header size for output.idx: the first 8 bytes are the output byte-size the index was built for. The index is valid iff this equals output’s current size; otherwise it is stale and must be rebuilt.

PTY_READ_BUF_SIZE 🔒

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

SHELL_INPUT_CH_SIZE 🔒

Cap on the out-of-order input reorder buffer (input_seq_buf).

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

Port of Go’s HandleAppendBlockFile.

handle_truncate_block_file

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

mirror_append_to_global 🔒

Append data to the global transcript zone’s output file, creating it lazily on first write. Mirrors the per-channel write-through in handle_append_block_file; all errors are logged and swallowed so the hot stdout path is never blocked by the global store.

persist_to_blockfile_silent

and write-through to FileStore (if provided). Persist data to the block’s output file and the global transcript zone without publishing a WPS event. Used by the persistent controller to record user-message lines for future history loads (so that parseHistoryLines can reconstruct user_message nodes on reopen) without triggering a live-stream append that would produce a duplicate node alongside the agent-message-accepted UUID node. Same lazy-create semantics as handle_append_block_file.

rebuild_output_idx 🔒

Rebuild output.idx from output in a single streaming scan and atomically replace it. The index is the byte offset of every non-blank line, matching the reader’s line addressing (String::lines().filter(!trim().is_empty())).

resolve_global_output_zone 🔒

Resolve a block’s GLOBAL transcript zone (agent:<defId>:current) from its agentId meta, looking the block up in wstore. Returns None for non-agent blocks, when there’s no store, or when the block can’t be loaded — the caller then passes None and no global mirror happens. Shared by the subprocess / persistent / acp agent controllers.

Type Aliases

ConnFactory

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