Struct NativeEffectShell 

pub struct NativeEffectShell { /* private fields */ }

Executes native effects and returns exactly one completion observation for each accepted effect. Logical lifecycle state remains owned by the engine.

Implementations

impl NativeEffectShell

pub fn new(catalog: AgentRegistry) -> Self

pub fn new_with_runtime_adapters( catalog: AgentRegistry, legacy_adapters: AdapterRuntimeRegistry<CliTool>, ) -> Self

Builds a native shell with consumer-provided compatibility runtimes.

The runtime registry is deliberately separate from the declarative catalog: both the adapter family and revision must resolve before a process is spawned.

pub fn take_efficiency_facts(&mut self) -> ShellEfficiencyFacts

Hand the caller everything collect_terminal_frames and reclassify_foreground recorded since the last call, and reset the facts back to empty. Called once per worker-loop iteration by gate4agent-runtime-native::publish_shell_observations, the only place with somewhere to fold these into a distribution.

pub fn active_session_count(&self) -> usize

pub fn spawn_operation_id(&self, key: NativeSessionKey) -> Option<OperationId>

pub fn terminal_snapshot( &self, key: NativeSessionKey, ) -> Result<PtyTerminalSnapshot, String>

pub async fn execute(&mut self, envelope: EffectEnvelope) -> ObservationEnvelope

pub async fn execute_with_pty_env( &mut self, envelope: EffectEnvelope, pty_env: Vec<EnvMutation>, ) -> ObservationEnvelope

Backward-compatible name for PTY-only callers. OneShot launches now receive the same shell-owned mutations.

pub async fn execute_with_environment( &mut self, envelope: EffectEnvelope, environment: Vec<EnvMutation>, ) -> ObservationEnvelope

Execute an effect with shell-owned environment injected only into a newly spawned provider process. The canonical start request cannot set these authority variables itself.

pub async fn execute_with_launch_overlay( &mut self, envelope: EffectEnvelope, environment: Vec<EnvMutation>, extra_args: Vec<OsString>, ) -> ObservationEnvelope

Execute an effect with host-only environment and optional PTY argv applied only to a newly spawned provider process.

pub async fn execute_with_launch_overlay_and_persistence( &mut self, envelope: EffectEnvelope, environment: Vec<EnvMutation>, extra_args: Vec<OsString>, one_shot_session_persistence: OneShotSessionPersistence, ) -> ObservationEnvelope

Execute an effect with host-only launch mutations and an explicit OneShotText session persistence policy.

pub async fn execute_with_launch_context( &mut self, envelope: EffectEnvelope, environment: Vec<EnvMutation>, extra_args: Vec<OsString>, one_shot_session_persistence: OneShotSessionPersistence, mcp_server: Option<McpServerSpec>, ) -> ObservationEnvelope

pub async fn collect_exits(&mut self) -> Vec<ObservationEnvelope>

Convert naturally exited PTY children into generation-bound lifecycle observations. Runtime ticks call this before accepting new commands.

pub fn collect_provider_events(&mut self) -> Vec<ObservationEnvelope>

Drain normalized provider events without mixing them with replaceable terminal frames. Broadcast lag is converted into an explicit stale gap.

pub fn collect_terminal_frames(&mut self) -> Vec<ObservationEnvelope>

Capture only changed terminal frames. Snapshot failures become an explicit stale observation once, until a later successful frame heals it.

The sequence is checked BEFORE the capture, not after. This runs on the per-session worker tick (20ms, so ~50 times a second per live PTY session), and terminal_state is not a cheap read: it renders the visible screen twice and clones the whole vt100::Screen to walk its scrollback row by row. Asking it first and comparing sequences afterwards meant every idle session rebuilt its entire screen fifty times a second purely to discover nothing had changed, and then dropped the result – with a couple of dozen sessions open that is the machine’s time, all of it wasted. terminal_sequence answers the same question by reading one integer.

pub async fn reclassify_foreground(&mut self) -> Vec<ObservationEnvelope>

Refresh the foreground half of PtyScreenState for whichever sessions are due, per next_foreground_probe.

Deliberately not folded into collect_terminal_frames: that method is synchronous and only pays for a real capture when the terminal sequence says the screen changed, but PtySession::observe_foreground_timed is async and walks the live OS process tree (CreateToolhelp32Snapshot on Windows) unconditionally every time it is called. Running that walk once per changed frame would scale a syscall with output rate – exactly the cost collect_terminal_frames’s own sequence gate exists to avoid. The cost here is bounded by the count of sessions NOT currently Ready, never by output rate and never by total session count: a session that reaches Ready disarms itself (see foreground_probe_schedule) and is never probed again until its text disagrees.