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.

List active drive-tui sessions.

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

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.

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

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

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

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-" or "^" (Ctrl — letters plus @, Space, [, , ]) and "M-" (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.

Block until pattern (a regex) appears on screen, then snapshot.

Returns {"ok", "matched", "alive", "text", "json"}. Timeout is not an error: the call returns ok=true with matched=false plus the final screen snapshot. 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.

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", "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. Can't false-positive on text that was already on screen, unlike wait_regex.

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.

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", "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.

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), or "TIMEOUT". 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.

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

Resize the session's terminal to cols x rows.