SmartCLI — drive terminal TUIs

Check whether the session's child process is still running.

Terminate a session and its daemon. Always close sessions when done.

List active drive-tui sessions. Returns {"ok", "sessions"}: each entry carries "sid", "port", "pid", "cmd", "cols", "rows", "cwd" and "started".

Resize the session's terminal to cols x rows.

Send key tokens, e.g. ["Down", "Down", "Enter"], ["C-c"], ["M-x"]. Named tokens: Enter, Return, Tab, BackTab, Space, Backspace, Delete, Escape, Esc, Up, Down, Right, Left, Home, End, PageUp, PageDown, Insert, F1-F12. Combos: "C-<char>" or "^<char>" (Ctrl — letters plus @, Space, [, \, ]) and "M-<char>" (Meta/Alt, ESC prefix). Any other token is not an error — it is typed as literal text. Arrow keys adapt to the app's cursor-key mode (SS3 under DECCKM, CSI else), so menu navigation works in curses apps.

Type text followed by Enter — the common 'run this command' action.

Type literal text into the session (no Enter). Use for filling fields.

Read a semantic snapshot of the session's current screen. Returns {"ok", "alive", "alt_screen", "text", "hash", "visual_hash"}: `alt_screen` is true while a full-screen program (vim, less, htop, ...) owns the screen — keys are commands to that program, not input to a shell, and `text` is its frame rather than scrollback. `text` is the rendered screen; `json` (the structured cell/cursor model) is included only when as_json=true. `hash` covers text content only — use it as the wait_change baseline; `visual_hash` also covers styling, selection and cursor state — use it as the wait_visual_change baseline. Don't mix the two. This is the 'perceive' step — always snapshot after acting rather than assuming an action landed.

Spawn a program in a new detached, persistent session and return its id. The session survives across tool calls (a localhost-only daemon owns the live PtySession). `cmd` is the command line to spawn, e.g. "python3" or "lazygit". `cwd` and `env` configure only the controlled child process. Returns {"ok", "sid"} on success. Use the returned sid for every other tool. Server-side limits (violations return an error): at most 8 concurrent sessions by default (tunable via SMARTCLI_MAX_SESSIONS); `sid` must be 1-64 chars matching [A-Za-z0-9][A-Za-z0-9_.-]*; `env` keys must be valid identifiers and may not start with SMARTCLI_TUI_; `cwd` must be an existing directory; terminal size is capped at 1000 cols x 500 rows (100000 cells). Note: `env` values pass through the process command line briefly (visible in `ps`) — avoid secrets. `detect_child_exit` (default false) makes this session's waits END when the child dies instead of sitting out the remaining timeout: a program that crashes on your first input costs one poll cycle instead of the whole ceiling. Off is exactly the previous behaviour. On, every wait tool also reports `exited` (true only when the wait ended that way), and `wait_ready` reports `reason: "EXITED"` alongside the usual MARKER/STABLE/TIMEOUT.

Wait for ANY of `patterns` to appear on screen (pexpect expect([...]) style). Race several possible outcomes at once — e.g. patterns=[">>> ", "Error", "Password:"] — and learn WHICH happened. Patterns are scanned in list order each poll, so the earliest in the list wins a same-poll tie (put the most specific first). Screen lines are right-padded with spaces — end-anchored patterns never match; use unanchored markers. Returns {"ok", "index", "matched", "alive", "exited", "text", "json"} where `index` is the 0-based position of the matched pattern. Timeout is not an error: the call returns ok=true with index=-1 and matched=false plus the final screen snapshot. On a `detect_child_exit` session whose child died first, `index` is -1, `matched` is false and `exited` is true — the wait returned at once rather than running to `timeout_ms`.

Block until the screen content changes, then snapshot. The precise "did my action land?" primitive: call it right after send_line/ send_keys to wait for ANY change from the baseline (default: the screen at call time; or pass a prior `hash` to change away from). Returns {"ok", "changed", "hash", "alive", "exited", "text", "json"} — `hash` is the new screen hash, reusable as the next baseline. Timeout is not an error: the call returns ok=true with changed=false plus the final screen snapshot. `exited` is true only on a `detect_child_exit` session whose child died first. Can't false-positive on text that was already on screen, unlike wait_regex.

Wait for a regex `marker` OR for the screen to go quiet (stable), then snapshot. Use marker="" to wait purely for stability. Returns a snapshot plus `reason`: "MARKER" (the regex appeared), "STABLE" (the screen went quiet), "TIMEOUT", or — only on a session started with `detect_child_exit` — "EXITED" (the child died; the wait returned at once rather than running to `max_wait_ms`). `exited` reports the same fact as a boolean on every wait tool. Timeout is not an error: the call still returns ok=true with the final screen snapshot. Screen lines are right-padded with spaces — end-anchored markers never match; use unanchored markers.

Block until `pattern` (a regex) appears on screen, then snapshot. Returns {"ok", "matched", "alive", "exited", "text", "json"}. Timeout is not an error: the call returns ok=true with matched=false plus the final screen snapshot. `exited` is true only when the session was started with `detect_child_exit` AND the child died before the pattern appeared, in which case the wait returned at once instead of running to `timeout_ms`. Screen lines are right-padded with spaces — end-anchored patterns never match; use unanchored markers. This is the readiness sync — prefer it over a blind delay after send_line/send_keys.

Wait for text, selection styling, or cursor position to change. Prefer this after arrow/navigation keys in full-screen TUIs. Pass a prior `visual_hash`, or omit it to use the current rendered state as the baseline. Timeout is not an error: the call returns ok=true with changed=false plus the final screen snapshot, with `exited` true only on a `detect_child_exit` session whose child died first.