tui

Documentation

Overview

Package tui draws Factor's interactive chat.

On a real terminal the console owns the bottom rows of the screen: an activity line showing what the agent is doing right now, and below it a prompt line that stays editable while a turn runs. Replies, background job results, and status repaints all land above the prompt, so nothing ever overwrites what you are half-way through typing — and a message you send never looks unanswered.

Without a terminal (pipes, `TERM=dumb`, no raw mode) every method falls back to plain lines, so scripts and tests see ordinary output.

Index

• Variables
• type Bar
• type Console
  • func NewChat(in, out *os.File) *Console
  • func NewStatus(out *os.File) *Console
  • func (c *Console) Close()
  • func (c *Console) Interactive() bool
  • func (c *Console) LogWriter() io.Writer
  • func (c *Console) Printf(format string, args ...any)
  • func (c *Console) PromptIdle()
  • func (c *Console) PromptSteering()
  • func (c *Console) ReadLine() (string, error)
  • func (c *Console) Reply(content, meta string)
  • func (c *Console) SetBar(bar Bar)
  • func (c *Console) SetStatus(status string)
  • func (c *Console) Start()
• type Spinner
  • func NewSpinner(con *Console) *Spinner
  • func (s *Spinner) Running() bool
  • func (s *Spinner) Set(phase, detail string)
  • func (s *Spinner) Start()
  • func (s *Spinner) Stop() Summary
• type Summary
  • func (s Summary) Note() string

Variables

var ErrInterrupted = errors.New("interrupted")

ErrInterrupted is returned by ReadLine when Ctrl-C is pressed on an empty line: the REPL's cue to quit.

Types

type Bar

type Bar struct {
	Session string
	Model   string
	Memory  string   // "" leaves memory out entirely
	Hints   []string // right-aligned, dropped first when the terminal is narrow
}

Bar is the persistent bottom line: which conversation you are in, what is answering it, and the keys that drive the prompt.

type Console

type Console struct {
	// contains filtered or unexported fields
}

Console renders the chat and reads the user's input.

func NewChat

func NewChat(in, out *os.File) *Console

NewChat builds the console for the interactive REPL. Painting and line editing switch on in Start, once the terminal is actually in raw mode.

func NewStatus

func NewStatus(out *os.File) *Console

NewStatus builds a console that only draws the activity line — one-shot mode, where there is no prompt and nothing to read.

func (*Console) Close

func (c *Console) Close()

Close erases the live region and gives the terminal back.

func (*Console) Interactive

func (c *Console) Interactive() bool

Interactive reports whether the console is drawing a live region.

func (*Console) LogWriter

func (c *Console) LogWriter() io.Writer

LogWriter returns a writer that prints log lines above the live region. Point the standard logger at it (`log.SetOutput`) so a background warning cannot land in the middle of the prompt and desync the layout.

func (*Console) Printf

func (c *Console) Printf(format string, args ...any)

Printf prints a line above the live region.

func (*Console) PromptIdle

func (c *Console) PromptIdle()

PromptIdle switches the prompt back to the resting one.

func (*Console) PromptSteering

func (c *Console) PromptSteering()

PromptSteering marks the prompt while a turn is in flight: whatever is typed now is steered into the running turn rather than starting a new one.

func (*Console) ReadLine

func (c *Console) ReadLine() (string, error)

ReadLine returns the next line the user submits. In raw mode the prompt stays live while it waits: activity updates and printed messages repaint around half-typed text instead of clobbering it.

func (*Console) Reply

func (c *Console) Reply(content, meta string)

Reply prints an agent message. meta is a dim trailing note (how long the turn took, which tools it used); an empty meta is left out.

func (*Console) SetBar

func (c *Console) SetBar(bar Bar)

SetBar replaces the status bar. A zero Bar removes it.

func (*Console) SetStatus

func (c *Console) SetStatus(status string)

SetStatus replaces the activity line; an empty status removes it.

func (*Console) Start

func (c *Console) Start()

Start hands the terminal to the console: raw mode, so it owns keystrokes and can repaint the bottom rows. Anything less than a real terminal leaves the console in its plain, line-at-a-time mode.

type Spinner

type Spinner struct {
	// contains filtered or unexported fields
}

Spinner drives the activity line: a pulse that travels while the agent works, what it is doing, and how long it has been at it.

func NewSpinner

func NewSpinner(con *Console) *Spinner

NewSpinner returns a spinner that paints on con.

func (*Spinner) Running

func (s *Spinner) Running() bool

Running reports whether a turn is in flight.

func (*Spinner) Set

func (s *Spinner) Set(phase, detail string)

Set moves the spinner to a new phase; detail carries the tool name.

func (*Spinner) Start

func (s *Spinner) Start()

Start begins a turn. Calling it on a running spinner does nothing, so a steering message folded into a live turn keeps the same elapsed clock.

func (*Spinner) Stop

func (s *Spinner) Stop() Summary

Stop ends the turn, clears the activity line, and reports what it took.

type Summary

type Summary struct {
	Elapsed time.Duration
	Steps   int
	Tools   []string
}

Summary describes a finished turn.

func (Summary) Note

func (s Summary) Note() string

Note renders the summary as the dim one-liner under a reply, or "" when a turn was quick and plain enough that saying anything would be noise.