Module substrate 

Execution substrate — the single environment an agent acts within.

See docs/execution-substrate.md. A coherent agent acts within one environment: every side-effecting tool (files, processes) resolves against the same machine, while pure tools (calculate) are environment-free and run in-process anywhere.

The Substrate trait is deliberately minimal: exec + file I/O (+ optional PTY). Convenience tools (list_dir/find_files/grep_files/edit_file) are composed on top — they are not trait methods. The GUI is a sibling surface on the same environment, not folded in here.

Variants

• LocalSubstrate — host fs/process. This is the lifted, byte-for-byte equivalent of the historic agent_basics host behavior (absolute paths pass through; relative paths join the host process current_dir()). It is the default for every existing consumer, so binding a substrate is backward compatible by construction.
• McpSubstrate — wraps an McpSession (e.g. the vm bridge). The bridge becomes one implementation of the environment, not a parallel tool surface. Routes substrate methods onto same-named bridge tools.

Structs

CommandOutput

Result of a one-shot command execution on a substrate.

LocalSubstrate

Host filesystem / process substrate.

McpSubstrate

Enums

PathState

Whether an execution substrate can establish a path’s existence without treating an unreadable file as absent. Guarded file writes may create only a confirmed-missing path; an unknown state must fail closed.

Constants

SUBSTRATE_TRANSPORT_ERR_PREFIX

Substrate backed by an MCP session (e.g. the vm bridge). Maps substrate methods onto same-named bridge tools (run_command, read_text, write_text, read_bytes, write_bytes, pty_*).

Traits

Substrate

The environment an agent acts within. Bound once to a Runtime; the agent never chooses per-tool where execution lands.