PUBLIC MODULE · lib/tui.js
TUI
lib/tui.js — the TUI: the human front end of ai.
The TUI uses lib/tui-app/ for semantic policy and Agent-turn lifecycle, and lib/gtui/ for geometry, rendering, selection, and editing. It does not own conversation state. The Agent owns context and the current turn; tui-app renders response events and live context, collects input, and sends messages and commands to the Agent.
lib/tui-app/ supplies an {init, update, view, bindings} application to lib/gtui/ through its run contract. The application supports two modes over the same rendering and control machinery: - inline the terminal keeps its native scrollback — finalized transcript rows print once and scroll; only the transient tail repaints in place; the footer rides the scroll; the mouse stays native except where something is actually clickable - alt owns the alternate screen (like vim): pins header/ footer, scrolls the transcript in-app, owns the mouse Mode selection: the engine option ("inline" | "alt"); createRepl defaults to "alt" when no engine is supplied. Inline preserves native terminal scrollback; alt owns the alternate screen.
The module exposes two front ends over the same app and command set: - createRepl the interactive terminal (raw-mode, ^O block viewer, ^X menu); - createLineRepl the piped, cooked-mode loop (one message per line).
TUI_ENGINES = TUI_MODES constant
The rendering modes accepted by createRepl.
createRepl({ agent, env, engine, input, write, output, resizeEmitter, log, onExit, cwd, signals, columns, rows }) function
The interactive REPL. options.engine picks the rendering mode: "inline" (native scrollback) or "alt" (default alternate screen). Both share one option contract.
optionsObjectoptions.agentobject[options.env]object[options.engine]"inline"|"alt"options.inputNodeJS.ReadableStream- stdin-like stream
[options.write](chunk: string) => void- THE terminal sink
[options.output]NodeJS.WritableStream- terminal output/resize source
[options.resizeEmitter]NodeJS.EventEmitter- explicit resize source
[options.log](line: string) => void- diagnostics mirror
[options.onExit]() => void- fires after terminal restoration
[options.cwd]string- working folder used for the title
[options.signals]NodeJS.EventEmitter- signal source
[options.columns](() => number)|number- viewport width override
[options.rows](() => number)|number- viewport height override
Returns {start: () => Promise<void>, close: () => void} — controller
close(runtime) function
Close TUI-owned agents, sessions, and background resources.
Returns {agent?: object, session?: {id: string, file?: string}|null} — Controllers returned by createRepl/createLineRepl also expose an
idempotent close().
run(state) function
Run the complete TUI application from normalized declarative state. Executables own argument parsing and process-exit policy; the runner creates the environment and Agent, selects the mode, and performs cleanup.
[state]object- normalized application state
Returns Promise<{code: number, agent: object, session: object|null}>
class TUI class
TUI module namespace. GTUI exposes the generic terminal runtime's view/effect/event/host/keybindings APIs for consumers building GTUI apps from the same import.
createLineRepl({ agent, input, writeOut, log, ansi = true, signals = true, onExit }) function
Create the piped, cooked-mode front end; one input message per line.
Defined in lib/tui-app/line-repl.js