omoya

PUBLIC MODULE · lib/app/tui/index.js

App.TUI

lib/app/tui/index.js — App.TUI: the terminal front end.

The TUI owns semantic policy and Agent-turn lifecycle, and uses App.GTUI (lib/app/gtui/) for geometry, rendering, selection, and editing. It does not own conversation state. The Agent owns context and the current turn; the TUI renders response events and live context, collects input, and sends messages and commands to the Agent.

This folder supplies an {init, update, view, bindings} application to 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 (overlays, completions, the ↓-focused status toolbar) — status chips ignore clicks while the input has focus (see GTUI README) - 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).

class TUI class

Empty namespace class for the TUI module, published as App.TUI by lib/app.js; static API members are assigned below.

Defined in lib/app/tui/index.js

createApp(agent, { env = agent?.env, cwd = "", sources, completionIO, log, open, columns, rows } = {…}) method

App lifecycle and presentation. Call dispose to detach UI bridges, then await closeWorkspace to release App-created agents and acquired project Envs; borrowed unrelated resources remain open.

agent object
the Agent this app starts on ("main")
[options] object
[options.env=agent.env] object
Env, for status/menu facts
[options.cwd] string
the process working folder
[options.sources] object
lib/tui-app/completion.js sources
[options.completionIO] object
completion filesystem hooks ({listDir}); defaults to real directory reads resolved under cwd
[options.open] (url: string) => void
browser opener handed to the OAuth flow; undefined uses the flow's system-browser default
[options.log] (line: string) => void
an external diagnostics mirror (piped `--input` runs: stdout IS the terminal byte stream, not human-parseable, so the caller may want every notice ALSO written somewhere plain — parity with the legacy engines' `log` option)

Returns {init: Function, update: Function, view: Function, bindings: Function, currentAgent: Function, closeWorkspace: Function, dispose: Function, abandonPending: Function, theme: object} — App lifecycle and presentation. Call dispose to detach UI bridges, then await closeWorkspace to release App-created agents and acquired project Envs; borrowed unrelated resources remain open.

TUI_ENGINES = TUI_MODES constant

The rendering modes accepted by {@link createRepl} (currently inline and alt).

Defined in lib/app/tui/index.js

close(runtime) function

Close TUI-owned agents, sessions, and background resources by delegating to the CLI cleanup routine. Controllers returned by createRepl and createLineRepl also expose an idempotent close() method.

Returns Promise<{agent?: object, session?: {id: string, file?: string}|null}> — Cleanup result returned by the CLI routine.

Effects — Delegates cleanup of the supplied runtime's TUI-owned resources.

Defined in lib/app/tui/index.js

createLineRepl({ agent, input, writeOut, log, ansi = true, signals = true, onExit }) function

Create the piped, cooked-mode front end, which reads one input message per line. Re-exported from ./line-repl.js; this module does not wrap it.

Returns object — The line-oriented REPL controller.

Defined in lib/app/tui/line-repl.js

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 modes use the same option contract. The function validates the mode and delegates controller creation to the interactive REPL implementation.

options Object
REPL configuration; required, with no default.
options.agent object
Agent that owns conversation state and turns.
[options.env] object
Environment supplied to the REPL; omitted by default.
[options.engine="alt"] "inline"|"alt"
Rendering mode; nullish or omitted selects `alt`.
options.input NodeJS.ReadableStream
Required stdin-like input stream.
[options.write] (chunk: string) => void
Terminal output sink; omitted by default.
[options.output] NodeJS.WritableStream
Terminal output/resize source; omitted by default.
[options.resizeEmitter] NodeJS.EventEmitter
Explicit resize source; omitted by default.
[options.log] (line: string) => void
Diagnostics mirror; omitted by default.
[options.onExit] () => void
Callback after terminal restoration; omitted by default.
[options.cwd] string
Working folder used for the title; omitted by default.
[options.signals] NodeJS.EventEmitter
Signal source; omitted by default.
[options.columns] (() => number)|number
Viewport width override; omitted by default.
[options.rows] (() => number)|number
Viewport height override; omitted by default.

Returns {start: () => Promise<void>, close: () => void} — Controller with asynchronous `start` and synchronous `close` methods.

Throws — {Error} If `engine` is neither `inline` nor `alt`; the error lists available engines.

Effects — Creates/delegates creation of an interactive terminal controller using the supplied streams and callbacks.

Defined in lib/app/tui/index.js

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; optional and forwarded unchanged, with no default applied here.

Returns Promise<{code: number, agent: object, session: object|null}> — Promise resolving to the application exit code, Agent, and session result.

Effects — Runs the application and its cleanup lifecycle through `runApplication`.

Defined in lib/app/tui/index.js