Skip to main content

Crate rig_tui

Crate rig_tui 

Source
Expand description

The terminal view: the front (FRONT) of a run where someone sits at the terminal (Invoked::interactive). It reads agent components, keeps its own state in resources and components, and sends the same requests any other view would. It never owns the app’s loop: a thread reads the terminal and wakes the loop, PreUpdate handles input one key at a time (TuiKeys), and PostUpdate lays out and draws a frame only when something drawn changed (TuiSystems).

TuiPlugin is TuiViewPlugin plus DefaultScreenPlugin. Where a plugin hooks in:

The view shows every plugin’s pickers and every agent’s questions, one at a time (PickerInput). All of this exists in every run, also under another front such as --print, which never draws a frame. ratatui and crossterm are re-exported so a plugin uses the same versions.

Re-exports§

pub use keys::AppKeyBindingsExt;
pub use keys::InputAction;
pub use keys::KeyBinding;
pub use keys::KeyFocus;
pub use keys::KeyPress;
pub use keys::KeyPressed;
pub use keys::KeyScope;
pub use keys::Keys;
pub use keys::run_command;
pub use pane::MainPane;
pub use pane::MainTranscript;
pub use pane::PaneKeys;
pub use pane::TranscriptPane;
pub use pane::TranscriptSource;
pub use panel::PanelCanvas;
pub use panel::Placement;
pub use panel::RedrawArea;
pub use panel::RequestRedraw;
pub use panel::TerminalSize;
pub use panel::TuiPanel;
pub use panel::TuiSystems;
pub use status::AppStatus;
pub use status::Side;
pub use status::StatusItem;
pub use status::StatusItems;
pub use status::StatusLine;
pub use status::StatusSystems;
pub use status::Tone;
pub use crossterm;
pub use ratatui;

Modules§

diff
A unified diff a tool returned, drawn in the transcript: each line with its numbers in the old and the new file, in the colors of the file’s language (highlight), removed lines on red and added ones on green (Theme), and the words a changed line changed on a stronger shade of each.
highlight
Code in the terminal’s own colors: bat’s grammars (two-face) and its ansi theme, which names colors of the terminal’s palette rather than colors of its own, so highlighted code follows the terminal’s theme. The grammars load once, on a thread of their own when the terminal opens, or when code is first drawn.
keys
Key bindings: every key the view acts on, its own editing keys included, is a KeyBinding entity named key:<keys>, so a plugin binds a key or a sequence (ctrl+x ctrl+e) as the view does, and listings read them as data.
markdown
Markdown in the model’s answers drawn as styled lines: headings, emphasis, inline code, fenced code, lists, quotes and alerts, links, rules and tables. Parsing is pulldown-cmark’s, with strikethrough, tables, task lists and GitHub’s alerts on. Code sits on the theme’s code tint, with a fenced block’s language over it, and an alert (> [!NOTE]) on the tint of what it is, under its name in bold.
pane
Transcript panes: a TranscriptPane draws a conversation in its panel with the transcript’s own layout, looks and state, live for an agent (the reply streaming in, running calls, the inbox, notices) or as a value (a saved session). Each pane has its own TranscriptView (what is selected and lit, where it is scrolled), its own scroll and, once a plugin adds one, its own DrawnTranscript. A look spawned as a child of a pane applies in it only. The default screen’s transcript is one, marked MainPane.
panel
What a plugin draws in the terminal view: a TuiPanel entity takes a side of the transcript or a box over the screen, and an ordinary system of the plugin draws it into the entity’s PanelCanvas in TuiSystems::Draw, with whatever queries and resources it needs. The transcript is laid out in what the panels leave.
status
The status line: what the view shows under the transcript of the agent it shows. Each agent, and its running turn, has its StatusItems, and the app its AppStatus; a plugin shows its items there by name in StatusSystems::Show, and replaces or hides another plugin’s in StatusSystems::Edit, as plain text in a Tone or in runs of their own styles (StatusItem::styled). A plugin that also builds without the terminal view does it behind a default tui cargo feature. The plugin guide has an example and the default plugins’ names and places. A StatusLine draws one in a panel, for the shown agent or another, and line() fits any items to a width.
wrap
Word wrapping of styled lines to a width, as the transcript wraps its rows: at word boundaries, a list item’s continuation rows under its text. A plugin drawing its own lines wraps them with wrap_all to look the same.

Structs§

AsideRenderer
The look of the asides of a kind, on an entity of its own.
AsideView
An aside of a conversation, as an aside renderer sees it.
CallDecorator
Lines drawn under every tool call, after its look, on an entity of its own.
Candidate
One candidate of a completion.
ChildCall
A tool or model call that a tool call started, or one of those started, as a renderer sees it (ToolCallView::children).
ChoiceKeys
On a Picker or an Ask: keys of its own in the view’s choice list, found before the view’s own. A plain character’s binding works while a choice row is selected and nothing is typed; once the user types, or selects the typed-answer row, characters type.
Completion
The open completion list of the input, as InputContext::completion gives it.
CompletionSource
Candidates a plugin adds to completion, on an entity of its own: for a word starting with a marker anywhere in the input, such as # for issues (CompletionSource::marker), or for an argument of a slash command, such as /model’s models (CompletionSource::arg). The view itself completes / at the start to a command name and @ to a path of the ProjectRoot (walked off the main thread, honouring .gitignore, until a FileWatch of the root sees a change).
ContentRenderer
The look of the content blocks of a kind, on an entity of its own.
ContentView
A content block of a message, as a content renderer sees it: an image, audio, a video or a document, the user’s or the model’s. Its rows are the transcript item TranscriptItem::Content, which a plugin finds in the DrawnTranscript, such as to draw an image over the rows its renderer left blank.
CopyToClipboard
Puts the text on the system clipboard through the terminal (OSC 52), which works over SSH too, where the terminal allows it, and on this machine’s clipboard through rig_tools::clipboard, for a terminal that ignores OSC 52.
DecoratedMessage
A message the user or the model wrote, as a message decorator sees it.
DefaultScreenPlugin
Spawns the default screen’s widgets, as ordinary entities, first, so the panels other plugins add go above the input or beside the transcript. The TuiPlugin adds it.
DrawnLine
A line of a DrawnTranscript as it was before the view wrapped it.
DrawnRow
A row of the DrawnTranscript.
DrawnTranscript
The transcript as the view drew it at its last frame: every row laid out, on screen or not, as drawn (wrapped, as its renderer drew it), with the items they belong to and the matches the view lit in each. A plugin counts and scrolls over this, not over the source text. TranscriptLayout lays one out without drawing it, for any agent; a plugin’s test, with no terminal to draw, inserts such a one as this resource.
Editor
A text being typed: multiline, with a cursor and emacs-style editing keys. The keys type into the MainEditor, or into the editor of the panel with the KeyFocus; Enter sends the main one’s text to the shown agent. A plugin reads and edits a draft as the keys do (a template, a dictated message, the text an editor wrote), the main one through MainInput; is_changed on it says the draft was edited. Up and Down move between lines and, from the first or last line, through the PromptHistory, keeping the draft, which Down past the newest prompt brings back. In a panel placed at the top, the bottom or below the input, it is as tall as its text, up to ten lines.
EntryRenderer
The look of the notes and delivered texts of the plugin plugin, on an entity of its own.
EntryView
A note or a delivered text, as an entry renderer sees it: a plugin’s Note, or a text of an entry of the conversation another author wrote, such as a compaction summary.
Highlight
Text to light in the transcript: wherever its text is drawn, or only its spans. Where matches of two highlights overlap, the one placed first in TranscriptView::highlights lights them and the other’s match there is not lit, so a highlight placed first, in a style of its own, sets its text apart from the rest’s.
InlineStrip
The strip that shows the question asked beside the work, if any (Ask::inline), with the keys that answer it: one row while one shows, none otherwise, in a panel at the top or the bottom. The default screen’s is above the input.
InputContext
What the view does with the keys, as the keys before the one being done left it, in TuiKeys, and as the frame’s keys left it, after them: for a filter that acts only in some states, such as not while a completion is open. The view writes it; it is read-only to plugins.
LineSpan
A match a plugin found in a line of the transcript, as DrawnTranscript::lines gives them, to light with a Highlight.
MainEditor
Marks the editor the keys type into while no panel has the KeyFocus, whose text Enter sends to the shown agent, and which a recalled message or a reload’s draft comes back to: the default screen’s. An app that builds its own screen marks its own.
MessageDecorator
Lines drawn under every message the user or the model wrote, after its own, on an entity of its own.
MessageView
A text of a message, as a message renderer sees it.
Notices
The notices the view shows, oldest first, those an earlier build of the session showed included: each drawn in the transcript of the agent it is about (ShownNotice::slot), and one about every agent where it was written. TranscriptItem::Notice names one by its number: its index here plus the older ones dropped.
PastEffects
Effects that settled before this run, such as a resumed session’s, for ToolCallView::children and each call’s facts: read as the kernel’s EffectRecorded records are. rig_basics::telemetry sends the session’s effect log once it was restored. PastEffects::new does all the work per record, so make it where the records are read, off the main thread for a long log: the view only takes it over. A later one replaces it.
PendingInput
The frame’s input, in order: what the terminal reported and the actions plugins pushed. The view does one item at a time, running TuiKeys for each: InputSystems::Filter systems may change, drop or replace it (with the main Editor and InputContext as the keys before it left them), and InputSystems::Dispatch does it. The picker or question shown takes it first, then a KeyBinding, then the input. Items left by a run are done next; a push outside TuiKeys waits for the next frame.
PickerInput
What the user did in the Picker or Ask the view shows, on its entity while shown: the filter or answer typed, the row selected and what is ticked. The view shows every agent’s and plugin’s, one at a time, in the order they came. A new Picker on the entity refills the list and keeps all three (the selected row found again by its command, else its label). A question superseded by another (SupersededBy) hands them to its successor, by choice id. The item highlighted is Highlighted on the entity, and a PickPreview there is drawn beside the list.
PromptHistory
The prompts Up and Down browse, oldest first, kept across sessions in the user’s PluginData as tui/history.jsonl (file: None saves nothing). Prompts are kept as typed, slash commands included.
RowWrap
How a DrawnRow continues the row before it, the view having wrapped one line into both: the line is the row before, then gap, then this row’s text past its indent.
RunInTerminal
Runs a program with the terminal, such as $EDITOR on a draft: the view leaves the screen, stops reading keys and lets the program have the terminal, its output included, until it exits; then it takes the terminal back, draws again, and inserts TerminalExit on the entity, which the plugin despawns once it read it. The agent’s loop waits while the program runs. Only the terminal view runs it, in the frame it is spawned.
ScrollTo
Scrolls the transcript pane pane so that row of item is shown; item: None follows the newest output again. An item not drawn leaves the pane where it is. Its TranscriptView::top reads where it is. To show another agent in the main pane, trigger ShowAgent first.
Sent
A prompt sent, which HistorySystems::Record adds to the PromptHistory unless it repeats the last one: the input writes one for each prompt it sends, and a plugin writes one for a prompt it sent for the user, such as from a panel of its own.
ShowAgent
Ask the view to show the agent and send what is typed to it, such as a subagent picked with /agents.
ShownNotice
A notice placed in a transcript.
TerminalExit
How a RunInTerminal program ended: its exit status, or why it did not start.
TerminalFocus
Whether the terminal has the user’s focus, as the terminal reports it where it can: None until its first report, and in a run without the terminal view.
TerminalWrite
Bytes for the terminal itself, such as an escape code that shows a desktop notification (OSC 9 or 777): the view writes them after its frame, through its own writer, so they never land inside a frame. Bytes sent in Bevy’s OnAppExitSystems are written before the terminal is given back. Nothing writes them in a run without the terminal view.
TextMark
A short label the transcript draws inside a reply’s text, before byte at of it, markdown kept on both sides: a mark past the end goes at the end, one inside a character goes before it.
Theme
The view’s colors, a resource. Plugins’ looks and panels may use them too, such as added behind a line a tool added, or panel for a panel’s surface.
ToolCallView
A tool call and its result, if it has one yet, as a renderer sees them.
ToolRenderer
The look of the tool named tool, on an entity of its own.
TranscriptLayout
Lays out an agent’s transcript as the terminal view draws it, without drawing it: for any agent, shown or not, in a run with the terminal or without, by the view’s own layout (its order, its renderers, wrapping and the matches it lights), so an export, a copy, a search or a screen reader reads what the view shows. Each layout renders and wraps the whole transcript, so lay one out when asked, not every frame. It is there in any run with the TuiPlugin, and takes the TranscriptView to lay out with, such as a pane’s, so a system that changes the view lays out with it too.
TranscriptView
A transcript pane’s view, as plugins read and steer it: on each TranscriptPane (the default screen’s is the MainTranscript). A change to it draws the pane again.
TuiFrame
Where the last frame drew each part of the screen: for a plugin that writes to the terminal itself after the frame (TerminalWrite), such as an image over the rows its content renderer left blank, which finds those rows in a pane’s DrawnTranscript (see TuiFrame::screen_row) and leaves out what an overlay covers. The view writes it after each frame it draws, in TuiSystems::Render; read it after that. All empty in a run without the terminal.
TuiKeys
The schedule the view runs once for each item of the frame’s PendingInput, in order, in PreUpdate, with that one item in them: filters see one key (and what earlier filters made of it) with the input and the InputContext as the keys before it left them. Its sets, in this order, are InputSystems; the commands of a run are applied before the next, so a panel a key opens takes the next.
TuiPlugin
The terminal view with its default screen (TuiViewPlugin plus DefaultScreenPlugin). It owns the terminal when it is the run’s front: on an interactive terminal, unless another front’s option was given.
TuiTestScreen
A screen in memory that the view draws to, for a test of what a plugin shows: inserted in a run with the view’s systems but no terminal (the plugin, then add_view), each frame due is drawn to it as it would be to the terminal, and the bytes sent for the terminal (TerminalWrite, CopyToClipboard) are kept. A test reads what is shown, never a whole screen to compare.
TuiViewPlugin
The terminal view without a screen: the terminal, the keys, the frame and the widgets’ systems, which draw whatever widgets are spawned. The TuiPlugin adds it with the DefaultScreenPlugin; an app that builds its own screen adds it alone.

Enums§

CallState
Where a tool call stands. A call of an earlier turn, or one whose effect is gone, is Done when it has a result and Running when not.
ChoiceAction
What a key of ChoiceKeys does.
CompletionKind
What a Completion completes.
CompletionTrigger
What a CompletionSource completes.
ContentBlock
A content block of a message that is not text, a tool call or a result.
ContentKind
A kind of content block a ContentRenderer draws.
HistorySystems
Where the terminal view records the prompts sent and saves them, in Update, in this order.
InputSystems
Where the terminal view handles each item of the PendingInput, in TuiKeys, in this order.
ItemRow
A row of a TranscriptItem to scroll to, counted in the rows the view draws, which the view works out, wrapping included.
KeyInput
An item of the PendingInput.
MarkIn
Whose text a TextMark is in.
Role
Whose text a MessageView is.
TranscriptItem
An item of a transcript, as plugins name it.
TranscriptSlot
Where a notice or a note is drawn in an agent’s transcript, by the index of a message in its Conversation. Slots order as they are drawn: the top, then each message with the slots inside it by item, then the slot after it. Those in the same slot are drawn in the order they came.

Constants§

FRONT
The terminal view’s name as a front.
OUTPUT_INDENT
The indent of a tool’s output and of the text under an entry’s title, for a look that draws its own rows.

Traits§

AppToolRenderersExt
Registers transcript looks: how tool calls, notes, content blocks, asides and message text are drawn, and lines under every call or message.

Functions§

add_view
Adds the view without a terminal: its input, keys, pickers, questions and the transcript it lays out, driven by the keys put in PendingInput and drawn only to a TuiTestScreen. The TuiViewPlugin adds it in finish when the run’s front is the terminal view, then opens the terminal; a test adds it once, after the plugin, and inserts a TuiTestScreen instead of a terminal.
text_rows
The lines of text in style, each indented by OUTPUT_INDENT.

Type Aliases§

DecorateMessage
Draws lines under a message.
MainInput
The main editor’s text, to read or edit. A system with it is skipped when there is no such editor, as in an app without the default screen.
RenderAside
Draws an aside as transcript lines, not yet wrapped.
RenderContent
Draws a content block as transcript lines, not yet wrapped.
RenderEntry
Draws a note or a delivered text as transcript lines, not yet wrapped.
RenderToolCall
Draws a tool call as transcript lines, not yet wrapped.