Terminal browser

Terminal browser is BMO’s terminal-native automation surface. Agents drive terminal programs, REPLs, full-screen TUIs, and BMO itself with browser-like verbs against a virtual terminal screen model layered on top of the existing PTY manager.

When to enable

Terminal browser is on by default on Linux and macOS. It is disabled on Windows: terminal_browser_open returns a documented error and the read-only posture surfaces report enabled=false, os_supported=false. Use the web agent-browser tool family for webapps and the existing pty_* tools when you only need raw line-buffered terminal I/O — terminal browser adds the screen reconstruction, scrollback, key/mouse synthesis, and wait/assert verbs needed for full-screen TUIs.

Operator surfaces

Surface	Purpose
`bmo config show-terminal-browser`	Posture summary: enabled flag, OS support, ring capacity/saturation, action x outcome histogram, recent invocations
`/terminal-browser` (TUI slash)	Same posture in the chat transcript, sharing the CLI formatter
`terminal_browser_status`	Read-only agent tool returning the posture as JSON
`terminalbrowser.CurrentPostureSnapshot`	Library accessor used by the surfaces above

Agent tools

Descriptor-backed tools (Linux/macOS):

terminal_browser_open — spawn a command or attach to an existing PTY session and return a terminal-browser session ID. Returns a documented error on Windows.
terminal_browser_snapshot — read the reconstructed live terminal screen, cursor, dimensions, scrollback count, optional cells, optional styled ANSI, and optional BMO landmarks.
terminal_browser_input — send text, common keys, or cell-addressed SGR mouse input (click, press/release, drag, move, wheel, modifier events).
terminal_browser_wait — block until a Contains substring appears, an Absent substring stays absent, the process exits, or a clamped timeout fires (non-positive timeouts clamp to 1ms).
terminal_browser_assert — same predicates as wait, but fails fast on non-match and records outcome=error, error_category=assert_unmatched.
terminal_browser_capture — persist a snapshot to a workspace-bounded artifact path.
terminal_browser_close — release the session.
terminal_browser_status — read-only posture summary; safe on Windows.

External-host compatibility boundary

BMO’s native Terminal Browser includes richer semantics than generic shell emulation. For Codex-style host harnesses (bash async + read_bash + write_bash + stop_bash), treat support as a portable subset: open, snapshot, input, wait, close.

Native-only features that are not portable without runtime support:

assert
capture
explicit PTY ownership/attach semantics
explicit terminal geometry controls
rich mouse semantics
first-class Terminal Browser session abstraction

Canonical maintainer guidance (including a dogfood flow using ./bmo) lives in docs/topics/tui/terminal-browser.md.

Structured logs

Each invocation emits paired records:

terminal_browser.fired — one per tool entry, before the action runs
terminal_browser.action — bounded action x outcome enum after the action completes

Filter examples:

terminal_browser.fired
terminal_browser.action
terminal_browser.action action=wait outcome=timeout
terminal_browser.action error_category=assert_unmatched

Field discipline (KTD-5): records carry only hashed session/parent prefixes, bounded scalar metadata (action, outcome, error_category, latency_ms, level), and timestamps. Raw IDs, argv, env, and PTY content never reach the log layer or the posture surfaces.

When to use vs `agent-browser` / `pty_*`

Scenario	Recommended surface
Web app interaction, DOM, screenshots	`agent-browser` tool family
Line-buffered terminal I/O without screen reconstruction	`pty_*` tools
Full-screen TUI (vim, htop, BMO itself)	Terminal browser
Wait for substring, assert posture, capture terminal artifact	Terminal browser

Windows posture

runtime.GOOS == "windows" is a hard gate on session creation: terminal_browser_open short-circuits with a documented error response, and all read-only surfaces (terminal_browser_status, bmo config show-terminal-browser, /terminal-browser) report os_supported=false so operators can see the disabled state at a glance. A static-analysis meta-test (internal/agent/tools/terminal_browser_windows_guard_test.go) pins this behavior so a new tool cannot ship without an explicit Windows clause.

Capture artifacts

terminal_browser_capture writes inside the workspace artifact root only — absolute paths and traversals outside the root are rejected. The capture returns the resolved path on the artifact response so the agent can attach it to a session record.

Maintainer topic: bmo/docs/topics/tui/terminal-browser.md (internals, controller lifecycle, screen model)
Tools reference