Tools

Why: use it for any command whose result matters. Read exitCode and timedOut: receiving a result is not proof that a command succeeded, and a timeout ends the wait without necessarily stopping the command, so do not repeat work that changes things. The inline output is a head and tail; for a temporary foreground run, retrieve the retained capture with terminal_read in run_output mode and the returned runId. For a named terminal, read its retained scrollback instead. A background run does not create a run-output record, so read its terminal instead.

A run in a named terminal can keep that shell's directory and variables. With stdin, do not rely on that command's environment changes carrying to the next call; verify any state needed later. One supported execution mode keeps at most 8 MiB of one run before previewing; installed modes can differ, and the inline preview is 2 KiB of head plus 2 KiB of tail unless maxOutputBytes says otherwise: a larger value widens the preview but cannot bring back bytes that were never kept. A run also shares its terminal with raw input and any browser participant, so agree who supplies input.

Why: open one terminal per task or per program, give it a name, and close it when done. Save the returned session id. Closing and an empty list are not proof that every descendant process has stopped, so check when a job must really be gone. terminal_open with a command waits up to 300 milliseconds for first output and does not wait for the program to be ready. Only one of session, group or all should be given to terminal_close; if several are given, all wins over group, and group over session.

The terminal_open options in practice:

Attaching returns once ownership has changed and does not apply the other fields: look at the state, then ask for a separate change. A tag search can pick any eligible match, so do not use it where several terminals could fit. The attachUrl is a secret link; confirm with the service owner that the bridge is running. terminal_list shows the default of 15 execution records with detail; use completed history and the current screen when checking command progress, and an exit status of -1 means none was collected. A group close ends only active terminals; list them afterwards, because any that failed to close stay listed.

Why: a successful send reports that input was accepted, not that the program handled it. Confirm the effect on the screen and do not resend a side-effecting line on a doubt. An inline wait has a ten-second ceiling and prompt is a quiet-screen check, not a recognised prompt. Use scrollback or incremental for output that has scrolled away, and screen to judge a prompt or a full-screen program. Text goes in before named keys. ctrl works with a single ASCII letter, alt applies to named keys rather than ordinary text, and shift is unsupported; bytesSent is an accounting figure and not a transcript. The output of a send shows the viewport lines that changed, so it can leave out what scrolled away.

The ways terminal_read can read, chosen with mode:

Output comes as text, ansi or lines. The default budget is 48 KiB. History keeps a configured number of lines and approximates carriage returns and redraws. An empty lines read can come back with no content fields, so ask for text when you need an explicit empty answer. Incremental reads consume their returned position even when filtering or response limits omit content. Filters are a reading aid; review shared output separately for confidentiality.

Why: these are diagnostic signals, not limits: neither ends a job that runs too hot. Frame reads keep up to 120 frames of changed screen text and are not a recording.

Only one output mode is active per watch: frame wins over idle, and otherwise the watch samples new output. A frame watch uses frameIntervalMs, 100 by default and held between 20 and 60,000. Output sampling sends at 4,096 bytes or 10 lines, so it can skip smaller writes and is not a transcript. idle means periodic statistics, and the complete, pattern and exit labels do not give separate detection. off: true ends both the output mode and any resource watcher. Adding resource starts a separate sampler, and a later watch without it does not stop that one. The resource options:

When several thresholds are exceeded, CPU is reported first, then memory bytes, then memory percent, and they share one sustained timer. Stats are cached, and the first sample for a process has no earlier CPU interval; resident memory sums can count shared memory more than once. A detailed stats result includes command lines, which can contain credentials or private paths.

Defaults: an attached terminal idle for an hour is detached (persistent) or ended (not persistent), and a detached persistent terminal is ended after a day. The service owner can change both limits. A terminal is exempt from idle cleanup while the service tracks a command running in it.

A browser attach link is a secret. Output, command lines and links can hold confidential information, so ask for only what the task needs. The service owner's options are on Settings, and the fixes for common failures are on Problems and fixes.