Start an interactive terminal session and return its id plus the initial screen.

Args: shell: "powershell" (Windows PowerShell 5.1), "pwsh" (PowerShell 7), "cmd", or an absolute path to any executable. cwd: Working directory. Defaults to the server's current directory. env: Extra environment variables merged into the inherited environment. cols: Terminal width in columns (default 120). rows: Terminal height in rows (default 30). name: Session id. Auto-generated (t1, t2, ...) when omitted. replace: Kill an existing session with the same name and start a fresh one. args: Extra arguments passed to the shell or executable.

Returns: session_id, shell, cwd, pid, size, ready reason and the rendered screen.

Send text and/or named keys to a session.

Args: session_id: Session returned by terminal_start. text: Literal text to type (not followed by Enter unless enter=true). keys: Named keys, e.g. ["ctrl-c"], ["up"], ["tab"], ["f5"], ["text:abc"]. Supported: enter, tab, backtab, esc, space, backspace, up, down, left, right, home, end, pageup, pagedown, insert, delete, f1..f12, ctrl-a..ctrl-z, ctrl-space, ctrl-break. enter: Append a carriage return after text/keys. repeat: Repeat the whole sequence 1..100 times.

Returns: session_id, sent_chars and running state.

Read incremental raw output from a session, without duplicates.

Each call returns only what arrived after the previous read. Use the returned cursor with since to resume from an explicit position.

Args: session_id: Session returned by terminal_start. since: Absolute character offset to read from. Defaults to the last read position. max_chars: Maximum characters returned (head+tail with an explicit omission marker). grep: Keep only lines matching this regular expression. tail: Keep only the last N lines (applied after grep). strip_ansi: Remove ANSI escape sequences.

Returns: text, cursor (pass as since), dropped, truncated, running, exit_code.

Note: PowerShell (PSReadLine) repaints the current line with cursor movements, so raw output contains fragments. Use terminal_screen for an authoritative view.

Block until output matches a regex, becomes quiet, the session exits, or timeout.

Args: session_id: Session returned by terminal_start. until: Case-insensitive regular expression to wait for, e.g. "PS C:\|>>>|Done". quiet_ms: Return when no output arrived for this long (0 disables quiet detection). Provide at least one of until or quiet_ms. timeout_ms: Give up after this long. ignore_echo: Ignore the echo of the last command line when matching until (prevents matching the command text itself).

Returns: reason: "matched" | "quiet" | "exited" | "timeout", matched, running, exit_code, and the rendered screen.

Return the rendered terminal screen (VT emulation) with cursor position.

This is the clean view: cursor moves, erases and color codes are applied, so it shows exactly what a human would see, including the current prompt or TUI.

Args: session_id: Session returned by terminal_start. max_chars: Maximum characters returned (head+tail with an omission marker).

Returns: text, cursor {x,y}, cols, rows, running, exit_code.

Stop the command running in a session, keeping the shell alive.

Sends Ctrl+C first. Native Windows programs often ignore the control character inside a pseudo-console, so any child process still running after a short grace period is terminated together with its own children. The shell itself is preserved.

Args: session_id: Session returned by terminal_start. force: Skip the grace period and terminate child processes immediately.

Returns: session_id, sent, running and the list of terminated pids.

Resize the pseudo-terminal (affects wrapping and full-screen programs).

Args: session_id: Session returned by terminal_start. cols: New width, 2..1000. rows: New height, 2..500.

List active sessions with their state, pid, cwd, size, idle time and buffer size.

Close a session and free its process.

Args: session_id: Session returned by terminal_start. force: Kill the whole process tree instead of requesting a graceful stop.

Run a one-shot command to completion and return its output and exit code.

Use this for non-interactive commands. Use terminal_start + terminal_send for programs that need input, a TUI, or a persistent shell.

Args: command: Command line to execute. shell: "powershell", "pwsh" or "cmd". cwd: Working directory. Defaults to the server's current directory. env: Extra environment variables. timeout_ms: Kill the command after this long. max_chars: Maximum output characters returned.

Returns: output, exit_code, timed_out, duration_ms, truncated.