terminal

The terminal namespace: 7 functions.

terminal/create

terminal.create(title)

Allocate a terminal (an empty vt100 grid, no process yet) and return its id. Render it with Z.terminal(id); start a coding agent in it with trusted.call("agents.spawn", { termId, harness }).

Parameters

• title string — Display title

Returns number — Terminal id

terminal/destroy

terminal.destroy(id)

Kill the child (if any) and remove the terminal from the registry. Raises when no terminal carries id.

Parameters

• id number — Terminal id

terminal/kill

terminal.kill(id)

Terminate the terminal's child process, if running. Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id

terminal/list

terminal.list()

List live terminals as { {id: number, title: string, running: boolean} }.

Returns { {id: number, title: string, running: boolean} } — Live terminals

terminal/poll

terminal.poll()

Drain one-shot lifecycle events as { {id: number, event: string, note: string, ok: boolean} }. event is "exited" when a child ends, note is the reason shown in the pane's ended bar, and ok is whether that child reported success — the difference between someone quitting the program in the pane and the program falling over. Each event is returned once.

Returns { {id: number, event: string, note: string, ok: boolean} } — Lifecycle events

terminal/resize

terminal.resize(id, rows, cols)

Request a PTY resize (rows x cols). The widget resizes automatically; this is for programmatic sizing. Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id
• rows number — Rows
• cols number — Columns

terminal/write

terminal.write(id, bytes)

Queue keystroke bytes to the terminal's PTY (programmatic input; routine typing flows through the focused Z.terminal widget). Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id
• bytes string — Bytes to send