Harnesses

Two clients are built from examples/. Both are examples of how to drive the library, and both are meant to be read as much as run.

Client What it is Where it stands
cliHarness The command line: options in, one prompt or a session out in place
tuiHarness The terminal UI: the conversation on screen, the answer arriving as it is written built

cliHarness

The command-line client. Every setting is an option, the npcs are created from the command line or from a command, and the turn is printed once it is over, in the order the reply contract defines it.

./build/examples/open_anima_cli --help                    # the manual
./build/examples/open_anima_cli --persona "a blacksmith" "who are you?"
./build/examples/open_anima_cli --persona "a blacksmith"  # a session over stdin

The settings are read by examples/common/apiSettings, shared with the terminal client under its own prefix, and the loader for .env is examples/common/dotenv. The client is the reference for the asynchronous turn: askTurnAsync() with poll(), cancel() wired to ctrl-c, and the whole document available when the turn is over. The dialogue is written once the turn is finished rather than while it arrives, so that the reasoning keeps its place above the words it leads to, and the answer is printed whole either way.

tuiHarness

The console application, and the client where the library is meant to be used rather than demonstrated: a conversation with an NPC, the answer arriving while the model writes it, and the keys alive the whole time. It is also where the room of several agents will live (v0.7.0), and the piece that has to look good enough to show the library off.

It is built, and it is provisional: a harness is where the shape of the library is tried out, so it moves every time the API moves, and what is written here describes today rather than a promise. What follows is the shape that was agreed before the code existed, and what the code now does.

The problem

What it looks like

The reference is the OpenCode TUI, which solved the same problem for a coding agent: a transcript with a scroll of its own, a prompt pinned to the bottom, and a hint line that says what is happening and what can be pressed.

  you     Do you have any iron daggers?

  npc 1   Three of them, and none of them cheap.
          The last one I sold went to a guard who
          never came back for it. Aye, that one
          cost him eleven silver.

  /create
  /enter
  /npcs

  +---------------------------------------------------------------+
  | > /c_                                                         |
  +---------------------------------------------------------------+
        mock   ask something   /help for keys

The commands are listed while one is being typed, up to six of them, with the selected one in the accent colour. When there are more than fit, the panel shows the ones around the selection, so a command reached with the arrows is never off the panel.

A blank row separates every turn from the one before it, so a conversation reads as a question and the answer it got. The answer itself is one block: the name of the NPC sits on its first line, over the thought that opens it, and the dialogue and the actions follow without repeating the name or opening a gap.

Keys

Key What it does
Enter Sends the draft
Ctrl+Enter, Ctrl+J, or a trailing \ Starts a new line instead of sending
Tab Completes the selected command
Up, Down Walks the command hints while they are showing, stopping at the ends, and the prompts of this scope otherwise
Ctrl+A, Ctrl+E, Ctrl+B, Ctrl+F, Left, Right Moves the cursor in the draft
Ctrl+Left, Ctrl+Right Moves a word at a time
Backspace, Delete Deletes the character before or after the cursor
Ctrl+Backspace, Ctrl+Delete Deletes a word at a time, and the gap around it
Ctrl+P, Ctrl+N Walks the prompts of this scope
Page up, Page down Scrolls the conversation
Wheel Scrolls whatever the pointer is over: the conversation, the hints, or the draft when it is taller than its box
Drag a scrollbar Scrolls to where the thumb is put, following the button
Hover a hint or a scrollbar Lights it up: the hint goes lilac, bold and underlined, the thumb of the bar goes lilac and bold
Click a hint Writes it into the draft, the same as tab with the selected one
Esc Cancels the turn in flight: the transcript keeps a short note and nothing of the answer
Drag over the conversation Picks out those cells, painted reversed as the pointer moves, and moves the conversation on when it is held against an edge of the viewport
Press and release on one cell Picks out that one character
Double click Picks out the word under the pointer
Triple click Picks out the whole row
Ctrl+C Copies what is picked out and drops the picking. It never leaves the client, which is what keeps a reach for the copy key from ending the session
Ctrl+V Types what was copied last
Ctrl+D Leaves

Control and backspace travel as the same byte as Ctrl+H on the terminals that do not report the chord itself, which is nearly all of them, so the client reads that byte as the word delete: it is what pressing the two keys produces there, and Ctrl+H has nothing else to do in a line being typed. The same goes for the other spellings the chords turn into: Ctrl+W, alt and backspace, and the modifier forms 27;5;3~ and 27;5;127~. Control and delete comes in as 3;5~ from a terminal, and as alt and d from an editor that takes the chord before the terminal sees it, which is what VS Code does. An editor that sends the key through the kitty keyboard protocol reports the code point instead, so code point 3 reaches the word delete too and code point 127 the word backspace.

A tab is never written into the draft. It counts as one column to the client and as up to eight to the terminal, and the two disagreeing is what tore the row apart.

The picking out follows the button for as long as it is held: the cells are painted as the pointer passes over them, the paint grows and shrinks with it, and the last one stays painted when the button comes back up. A double click takes the word under the pointer and a triple click takes the whole row, the way a terminal does it; a cell that is not part of a word is a word of its own. Picking is only over what was said: the box of the prompt, its padding, the marker beside it and the scrollbar on the right are the client's own drawing, so a drag across them paints the text and leaves them as they were, and a copy of that same selection holds the words without the box and comes out flush with the left edge. The bar inside the box is the client's drawing too, and the padding column it takes is not part of the draft. Any other key drops the picking, so a selection never sits over text that has been typed over. The wheel and the page keys are the exception: they move the conversation, and a picking made in it goes with the words it covers, so it stays over what was picked out while it scrolls, and it is there again when the words come back. A drag that reaches an edge of the viewport and waits there moves the conversation a row at a time, so a span can be taken past what is on screen without letting go. The end tied to the text goes with it and the end under the pointer waits on the edge, which means the span grows for as long as the button is held there. A picking belongs to the part of the screen it was made on: one of the conversation is read and painted inside the viewport and never reaches the prompt, and one of the prompt stays where it is while the conversation moves under it. A drag that starts on the prompt and comes up over the conversation therefore takes the draft and leaves what was said above it alone. While the client runs the mouse is the client's, which is the price of the wheel scrolling the conversation; holding shift asks the terminal for its own selection back in most of them. The right button is left to the terminal: the client never uses it, so the menu of the editor or of the emulator opens with the copy and paste it offers.

The pointer also lights up what it is over. A command hint under it turns lilac, bold and underlined, and a click on it writes it into the draft, which is what tab does with the one that was selected. A hint that is not under the pointer is quiet unless it is the selected one, which keeps the accent colour. The wheel and the page keys are the wheel of whatever is under the pointer: over the panel they walk the hints, stopping at the ends, and anywhere else they scroll the conversation. A scrollbar under it gives the pointer the thumb it would drag: the thumb turns lilac and bold, and the button drags it, which scrolls the conversation to the row it is left on, or walks the hints when it is the bar of the panel. A press beside a thumb brings the thumb under the pointer first, and a drag that goes past either end stops there.

Anything a keyboard can send reaches the draft as bytes, so an enye, an accented vowel or a combining mark typed after a letter lands in the same cell as the letter it belongs to. Copying goes out as the terminal's own clipboard sequence and lives in the client too, so a paste works in a terminal that keeps the clipboard to itself.

The world

The client starts with no NPC at all, and the conversation is with whoever it was told to talk to:

Command What it does
/create <description> Makes an NPC from the description and talks to it
/enter <id> Talks to another NPC, with the conversation where it was left
/npcs Lists the NPCs, and which one is being talked to
/leave Leaves the conversation, keeping it
/clear Drops the active conversation, keeping the persona
`/raw [on off]`
/help Lists the keys and the commands
/quit Leaves

An NPC has no name yet, only the number it was given when it was made, so it is shown as npc 1, npc 2. The persona is the description it was created from. Any number of NPCs can be made and each one keeps its conversation, reachable by id. NPCs cannot talk to each other: that needs the library to carry a conversation between several of them, which is not there yet.

Each scope has its own prompt history: inside an NPC the arrows walk what was typed to that NPC, and in the lobby what was typed outside. A command that would leave a turn behind waits for the answer, and says so.

How it is built

Packets

Where What is in it
domain/ The model, the commands and the keys: what a key does, and what to ask the shell for
presentation/ The canvas, the cells, the colours, the text measurement, the picking and the frame writer
application/ The session, the pointer and the brains: the loop, and what a click or a wheel notch means
terminal/ Raw mode, key decoding, the size of the window and writing without waiting
main.cpp The composition root: configuration, terminal, session

How it is checked

The plan

  1. Two prototypes, one over FTXUI and one written by hand, in a branch of their own, with the minimum needed to compare them: the prompt, the answer growing, and the key that cancels. They are thrown away once one of them wins. The hand-written one won: FTXUI was dropped because its inline renderer emits cursor moves with a negative parameter (\x1b[-1B), which both the terminal in the editor and a strict emulator misrender.
  2. The skeleton of the real client around the winner, with the terminal layer abstracted and both of its implementations.
  3. The loop, the world of NPCs, the scroll of the transcript and the command palette.
  4. The tests above, and these pages brought up to date.

Steps 1 to 3 are done, and the piece tests of step 4 are in the suite. The enhanced keyboard is in, the wheel is in, and so is picking text out of the conversation with the mouse and handing it to the clipboard. What is left of step 4 is the in-suite client test over a pseudo-terminal, so the client itself is exercised by the same command that runs the rest.

What comes next, in the order it will be felt:

  1. A measured layout: today the rows of the screen are placed by arithmetic on the height and the width, which is what makes a narrow window and a resize the places where the client can still be surprised. The screen is going to describe itself as a tree of boxes with sizes to honour, measure it and then paint it, so that what is asked for and what is shown cannot drift apart.