Documentation
¶
Overview ¶
Package activity renders display-only activity blocks, Markdown, and journal result layouts. It owns no thread lifecycle, journal receipts, or execution.
Index ¶
- Constants
- func AddTimeouts(text string, timeouts []string) string
- func AgentDisplayName(name string) string
- func AttachCopy(row string, spans []CopySpan) string
- func Backdrop(row string) string
- func BlankRow(row string) bool
- func Card(title, right string, rows []string, width int, glow bool) []string
- func ChangeTotals(rows []ChangeRow) (added, removed int)
- func Color(name string) string
- func CopyDecoration(row string) string
- func CopyText(parts []CopyFragment) string
- func DimColor(name string) string
- func EditPath(block Block) string
- func EditStat(label string) (path string, added, removed int, tail string, ok bool)
- func EditStatus(b Block) string
- func EditVerb(b Block) string
- func ErrorHasDetails(block Block) bool
- func ErrorPreview(body string) string
- func ErrorRows(block Block, width int) []string
- func EventHeading(glyph, name, detail string, observed time.Time, width int) string
- func FaintFallback(frame string) string
- func FenceDelimiter(line string) (string, bool)
- func Gutter(name string, theme livediff.Theme) string
- func Hang(lead, label string, width int) []string
- func MarkdownSource(text string) string
- func Paragraphs(text string) []string
- func Path(path string) string
- func ReasoningShimmer(text string, elapsed time.Duration, colors Colors) string
- func ReasoningSummaryBody(text string) string
- func ReasoningSummaryHeader(text string) string
- func ResultCount(count *int) string
- func RowVerb(b Block) string
- func RunElapsed(block Block, now time.Time) string
- func StatusPulse(text string, now time.Time, colors Colors) string
- func SummaryVerb(verb string) string
- func TailOutput(output string) ([]string, int)
- func TailRows(rows []string, limit int) ([]string, int)
- func TextSelection(text string, theme livediff.Theme) string
- func Tree(parts [][]string) []string
- func TruncatePath(path string, width int) string
- func Underline(text string) string
- func UnderlineEdit(text string) string
- func Verb(verb string) string
- func VerbColor(verb string) string
- func Wrap(text string, width int, hard bool) []string
- type Answer
- type AnswerGroup
- type Block
- func AlignVerbs(blocks []Block) []Block
- func CollapseBatch(blocks []Block) (Block, bool)
- func FoldStages(blocks []Block) []Block
- func GroupOperations(blocks []Block) []Block
- func MergeLiveActivityReads(blocks []Block) []Block
- func ParseOperation(paragraph string) Block
- func ReasoningSections(text string) []Block
- type ChangeRow
- type Colors
- type CopyFragment
- type CopySpan
- type DialogFrame
- type DialogLine
- type DialogPage
- type Elision
- type ElisionForm
- type Journal
- type Output
- type OutputTail
- type OutputView
- type Painter
- func (p *Painter) Agent(name string) string
- func (p *Painter) Block(block Block, width int) []string
- func (p *Painter) CopyWrapped(rows []string, source CopyFragment, gutter int) []string
- func (p *Painter) Dialog(f DialogFrame, width, height int) []string
- func (p *Painter) DialogPage(block Block, width int) DialogPage
- func (p *Painter) DialogPageTitle(block Block, now time.Time, width int) string
- func (p *Painter) Event(block Block, width int) []string
- func (p *Painter) Flash(block Block, rows []string) []string
- func (p *Painter) Highlight(lang, source string) []string
- func (p *Painter) Inline(line string) string
- func (p *Painter) Journal(journal *Journal, width int, heading bool) []string
- func (p *Painter) Label(verb, label string) string
- func (p *Painter) Markdown(text string, width int) []string
- func (p *Painter) QuestionState(state string) string
- func (p *Painter) Quote(text string, width int) []string
- func (p *Painter) ReasoningElided(block Block, width int) bool
- func (p Painter) Route(block Block) string
- func (p *Painter) Summary(blocks []Block, width int) string
- type Question
- type Read
- type Retention
- type Stat
- type TextPoint
- type TextSpan
- type TokenKind
- type WaitTarget
Constants ¶
const ( OutputBytes = 1 << 20 OutputLineBytes = 16 << 10 OutputRetainedBytes = 16 << 20 )
Host aggregates stop at 1 MiB; a live stream keeps as much of its latest output. A session keeps OutputRetainedBytes across commands.
const ( Dim = livediff.Subtle Undim = livediff.SubtleReset Reset = "\x1b[0m" Green = "\x1b[38;5;114m" Red = "\x1b[38;5;203m" Amber = "\x1b[38;5;214m" )
const ( OutputTailLines = 5 OutputTailBytes = 512 // Per line, before sanitizing. // A burst rolls through at most this many of its latest lines. OutputPendingLines = 64 )
Bounded tails show the latest rows of something still growing and count what they leave out. Live thinking tails its painted rows; command output tails its lines as they stream, in memory bounded by the tail.
const ChangeRowsShown = 12
ChangeRowsShown bounds the change rows open output shows.
const DialogChrome = 4
DialogChrome is the rows a dialog frame takes beyond its body: the top edge, the detail row, its rule and the bottom edge.
const DialogClose = "[×]"
const DialogCloseWidth = 3
const Hash = "\x1b[38;5;179m"
Hash is the gold VCS output uses for commit hashes and branches.
const OutputDebounce = 750 * time.Millisecond
Successful output stays open until its agent's next standalone event, then collapses once events pause for OutputDebounce. Eligible outputs share the latest deadline across agents and late completions, so a quick run of commands collapses together rather than one row at a time. Restored history starts settled.
const ThinkingTailRows = 3
ThinkingTailRows is how much reasoning stays visible while it streams, following grok-build's truncated thinking blocks.
Variables ¶
This section is empty.
Functions ¶
func AddTimeouts ¶ added in v0.2.0
AddTimeouts carries presentation metadata outside command and operand spans.
func AgentDisplayName ¶
agentDisplayName is the one user-facing form of a canonical agent path: main for the root, the path below it otherwise (worker, or a/worker when nested). Model-visible text keeps canonical paths, since agents address each other by them.
func AttachCopy ¶
AttachCopy is used only while the router composes native panes. Public view rendering stays clean ANSI; the visible annotations remain a separate value.
func Backdrop ¶
Backdrop fades a screen row the dialog is drawn over: its colors and attributes give way to faint text, and cursor moves stay in place.
func Card ¶
Card frames a finished answer: a rounded green edge with its title on the top border and optional dim right text, such as a time.
func ChangeTotals ¶
ChangeTotals sums a row set's known line counts. A footer that states totals, as a commit's does, is authoritative over the rows it summarizes.
func CopyDecoration ¶
CopyDecoration marks a generated heading as selectable geometry, not source.
func CopyText ¶
func CopyText(parts []CopyFragment) string
CopyText serializes only the visible, selected fragments. Table identity and logical cell coordinates reconcile wrapped grids and repeated record labels.
func EditStatus ¶
EditStatus is the outcome a group's first row names after its source.
func EditVerb ¶
EditVerb is a grouped row's verb: past tense once confirmed, and otherwise the requested action, whose status the group's first row names.
func ErrorHasDetails ¶
ErrorHasDetails reports content omitted by the inline first-line preview.
func ErrorPreview ¶
ErrorPreview bounds inline diagnostics independently of the full dialog body. A single first line also keeps multiline host errors out of the transcript.
func EventHeading ¶
Source: internal/router/live_activity_conversation.go:549:560@1426318d conversationHeading. EventHeading is shared by transcript and Activity events. Unknown times stay absent; a known time is right-aligned only when it fits.
func FaintFallback ¶
FaintFallback lowers faint styling in a complete terminal frame to fixed 256-color foregrounds. Only unsupported output uses it; cached rows retain their semantic styles. Cursor controls, hyperlinks and text pass unchanged.
func FenceDelimiter ¶
func MarkdownSource ¶
MarkdownSource removes terminal controls without normalizing code tabs. The shared renderer expands them for display and retains their source identity.
func Paragraphs ¶
Paragraphs splits operations at blank lines outside fences.
func ReasoningShimmer ¶
Source: codex-rs/tui/src/summary_shimmer.rs:23:61@86be5320b068ef67b56348b02aa8c33706955da6 summary_shimmer. Preserve Codex's two-second, whole-grapheme, left-to-right cosine sweep: the band takes the terminal foreground and the rest blends halfway into the background. Unknown palettes use a neutral continuous ramp.
func ReasoningSummaryBody ¶
ReasoningSummaryBody removes a detected section title only when paragraphs follow it. Heading-only summaries remain public content, not empty bodies.
func ReasoningSummaryHeader ¶
Source: codex-rs/tui/src/chatwidget/streaming.rs:9:24@86be5320 latest_summary_line.
func ResultCount ¶
func RunElapsed ¶
RunElapsed shares the compact duration grammar used by native status timers.
func StatusPulse ¶
statusPulse brightens the entire pending label together over a two-second cycle.
func SummaryVerb ¶
func TailOutput ¶
TailOutput is the display tail of complete output.
func TailRows ¶
TailRows keeps the last limit rows with text and counts the text rows before them. Paragraph gaps take no place, so the tail always shows text.
func TextSelection ¶ added in v0.2.0
TextSelection replaces backgrounds while retaining syntax colors. Clear reverse-video carets and restore the fill after resets and code/diff fills.
func Tree ¶
Tree joins operation rows into one tree: ├ before each but the last, └ before the last, and a rail beside continuation rows.
func TruncatePath ¶
TruncatePath uses the feed's path elision in single-line controls, including widths where feed rows would wrap instead. It keeps nearby directories and the filename, or the filename's start and extension when it cannot fit.
func UnderlineEdit ¶
UnderlineEdit marks text, not the tree gutter, alignment gaps, or stat bar.
Types ¶
type AnswerGroup ¶
type Block ¶
type Block struct {
Ended time.Time // Observed command end; zero when unavailable.
Started time.Time // Observed live command start, presentation only.
Duration time.Duration // Host or measured segment duration; zero means unavailable.
NotificationTiming bool // Timestamps are UI notification observations, not host execution boundaries; Duration is host elapsed.
Questions []Question
Source uint64 // Activity entry identity for exact cross-pane navigation.
Section int // Reasoning section ordinal within that entry, retained by dialogs.
Kind string // op, reads, message, start, error, text
Verb string // Operation verb, or a message headline.
Label string // Markdown remainder of the operation label.
Path string // Literal operation target, rendered with shared path styling.
SyntaxPath string // File identity when Path is a compressed display label.
Workdir string // Display path of a command directory other than the workspace; set on every row it applies to.
ShowWorkdir bool // The invocation's first row labels Workdir.
Timeouts []string // Explicit execution bounds, as displayed.
Code string // Inline code or fenced program under the label.
Lang string
Fenced bool
From, To string
Owner string
Body string
Reads []Read
Journal *Journal // A final answer in journal-result form.
WaitTargets []WaitTarget // Canonical identity and observed status, not parsed display text.
Results *int
ExitCode int // Nonzero command exit; zero means no failure label.
Approval string // Approval outcome, distinct from execution status and exit.
BatchExit bool // This row owns an invocation-wide exit, not an individual operation's.
EditSource string // Editing source shared by this invocation's file rows.
EditOutcome string // Live segment outcome, distinct from captured file evidence.
EditHeader bool // First row of a contiguous source group.
GroupHeader string // Presentation-only edit outcome shared by a group's rows.
GroupStart bool
GroupCount int // Edit invocations in this group.
VerbAlign int // Widest row verb in this row's group.
VerbColumn int // Verb column shared with adjacent operations; 0 uses the default.
PathAlign int // Widest aligned edit path in this row's group.
StatAlign int // Widest line-count text in this row's group.
StatScale int // Largest changed-line total in a multi-row group; 0 omits bars.
Running bool // A live command the host has not completed.
Requested bool // Source intent without observed per-command execution.
Segment bool // Ends one tracked segment of a command list; shows that segment's exit.
Skipped bool // A tracked segment the command list never reached.
Tail []string
TailOmitted int // Output lines before Tail.
TailRows int // Tail lines open output shows; 0 shows all of Tail.
Changes []ChangeRow // Change history rows open output shows instead of Tail.
Output *Output // The invocation's retained output, which the output dialog reads.
// Members are the invocations a merged read row stands for, each with its
// own output, which the output dialog pages through.
Members []Block
SourceRows int // Rows a command or program preview may use; 0 shows it whole.
Flash bool // Presentation-only: another pane just opened this entry.
Live bool // Reasoning still streaming.
Elapsed string // Formatted reasoning time, when observed from its first delta.
// Collapsed shows a settled block as one row that opens it; Hovered
// underlines that row under the pointer. Both are presentation-only.
Collapsed, Hovered bool
// Rows paints styled presentation rows at a width; the dialog shows them
// in place of Body's Markdown, and Body stays the copied text.
Rows func(width int) []string
Detail string // Styled facts for the dialog's detail row when it has none of its own.
}
The agents pane parses the router's own commentary grammar back into parts so it can lay them out natively. Unrecognized text stays a plain text block; nothing is interpreted, expanded, or executed.
func AlignVerbs ¶
AlignVerbs gives each run of adjacent operations one verb column, as wide as the widest verb in that run, so rows pad only to the verbs beside them.
func CollapseBatch ¶ added in v0.2.0
CollapseBatch folds a settled run of operations into one "batch" row whose Members are the operations the output dialog pages through. Running or skipped work and questions keep their rows, as does a lone operation.
func FoldStages ¶
FoldStages drops staging rows that lead straight into a commit of the same invocation: the commit's rows name the files it recorded. A failed or skipped stage, or one before a skipped commit, stays visible.
func GroupOperations ¶
GroupOperations groups adjacent edits from one source and outcome, across invocations, so their rows share one verb cell. Invocation identities stay on their rows. Other operations stand alone.
func MergeLiveActivityReads ¶
MergeLiveActivityReads collapses adjacent targets of the same action, joining ranges of the same path. Reads whose content is collapsed join too, each target counting the lines read from it; a read still streaming, failed or left open stays its own row until it settles. Merged blocks own their slices; parsed entries are shared.
func ParseOperation ¶
func ReasoningSections ¶
ReasoningSections keeps titled summaries independently readable and reopenable, retaining each section's original Markdown for the dialog.
func (Block) Collapsible ¶
Collapsible reports a settled block that can show as one row: finished thinking as its header, or a successful command's output as its line count.
func (Block) DirectoryDeletion ¶ added in v0.2.0
DirectoryDeletion reports a captured directory removal summary.
func (Block) Instant ¶
Instant reports an operation that prints what it reads at once: a read, search, listing or inspection, not a program whose output is worth watching roll by.
func (Block) ProgressText ¶
ProgressText is the plain-text form used by activity summaries.
func (Block) ReadOutput ¶
ReadOutput reports a file or skill read, whose output is what the agent read rather than a result to watch, so it starts collapsed.
type ChangeRow ¶
type ChangeRow struct {
Verb string // Edited, Created, Deleted, Moved, Conflict or ?; empty for a change ID.
Code string // Short file status, or staged/unstaged VCS status, shown in the verb column.
From string // A moved file's earlier path.
Label string // File path or change ID range; a footer's lead, such as a commit hash.
Added, Removed int // Known line counts; zero counts are omitted.
Note string // Muted detail after the counts, such as a status.
// totals, after any elided rows: Label leads, then Note and counts.
Footer bool
}
ChangeRow is one row of a change history read, such as `mchanges --list` or `--summary`, or of a version-control read or commit, laid out like confirmed edit rows.
type Colors ¶
Colors are the default text and background colors the terminal reported through OSC 10 and OSC 11.
type CopyFragment ¶
type CopySpan ¶
type CopySpan struct {
Column int
CopyFragment
}
CopySpan is positioned in terminal cells, while its source uses UTF-8 bytes.
func ExtractCopy ¶
ExtractCopy resolves the final composed row, including absolute cursor moves. No private annotation reaches the terminal emulator or external terminal.
type DialogFrame ¶
type DialogFrame struct {
Tabs string // Styled command selector, empty for a single result.
Page DialogPage
Position string // Page position among a merged row's invocations, such as "2 / 4".
Paused bool // Live output the reader scrolled away from.
Rows []string // Visible body rows.
GutterStyles []string // Optional styles for visible rows' left padding.
Top int // Index of the first visible body row, for the scroll thumb.
Total int // Body rows in all.
}
DialogFrame is one frame of the output dialog, before layout.
type DialogLine ¶
type DialogLine struct {
Wrap bool // Keep an unnumbered logical line intact for search; wrap only for display.
Number int // Zero leaves the number column blank.
Gutter string // "│" before source, "┆" before output, empty for other rows.
GutterStyle string // Optional number style, including wrapped rows and their left padding.
Text string // Styled.
}
DialogLine is one numbered source/output line, a logical unnumbered error line, or a pre-laid-out row such as a note or rendered Markdown.
type DialogPage ¶
type DialogPage struct {
Title string // Styled verb and target.
Live bool // Output is still streaming.
Detail string // Styled facts: line spans, line count, exit.
Lines []DialogLine
Text string // Plain output, or source without output, for copying.
// contains filtered or unexported fields
}
DialogPage is one invocation's source and output as the output dialog shows them. Lines stay unwrapped, so a long live stream costs a layout only for the rows in view.
func (DialogPage) Indent ¶
func (d DialogPage) Indent(i int) int
Indent is the cells line i's rows spend on its number and gutter.
func (DialogPage) MatchRow ¶
func (d DialogPage) MatchRow(i, width int, query string) (int, bool)
MatchRow finds a case-insensitive substring in a logical line and locates its first display row. Search must not lose text at visual wrap boundaries.
func (DialogPage) RowCount ¶
func (d DialogPage) RowCount(i, width int) int
RowCount is how many rows line i takes at width.
func (DialogPage) Rows ¶
func (d DialogPage) Rows(i, width int) []string
Rows lays out line i at width: numbered lines wrap under their gutter, and continuation rows leave the number blank.
type Elision ¶
type Elision struct {
Hidden int
Unit string // Counted noun used as written; empty counts lines.
Form ElisionForm
Hovered bool
}
Elision counts content a row leaves out of view. Every hint renders through it, so counts read alike wherever content is clipped, and each underlines alike under the pointer that opens its content.
type ElisionForm ¶
type ElisionForm uint8
const ( // ElisionMore ends clipped rows: "… +N lines". ElisionMore ElisionForm = iota // ElisionSuffix follows text on its row: "+N lines". ElisionSuffix // ElisionEarlier precedes the rows shown: "… N earlier lines". ElisionEarlier // ElisionLead counts earlier lines in a verb column: "+N". ElisionLead // ElisionContent counts collapsed content in full: "(N lines)". ElisionContent )
type Journal ¶
type Journal struct {
Groups []AnswerGroup
Changes string // Change ranges.
Stats []Stat
// contains filtered or unexported fields
}
Journal is a child's journal result laid out by the router's journal delivery grammar: answer groups, then this agent's recorded changes.
func ParseJournal ¶
ParseJournal reads the child result grammar written by journal delivery: the answer, then the change report that always closes a child result. Results retained from before the heading was dropped still lead with "Journal result". Any other shape stays authored Markdown.
type Output ¶
type Output struct {
// contains filtered or unexported fields
}
Output keeps a command's host output for reading in full, apart from the display tail rows show: its latest OutputBytes, sanitized line by line, and a count of the lines before them. A Retention bounds what a session keeps across commands. Outputs belong to the UI goroutine.
func (*Output) Finish ¶
Finish replaces streamed output with the host's aggregate, when it reports one, and records the command's exit, when known. Later output is ignored.
func (*Output) Release ¶
func (o *Output) Release()
Release ends output retention when segment attribution becomes unavailable. It belongs to the UI goroutine, like Write and Finish.
func (*Output) View ¶
func (o *Output) View() OutputView
type OutputTail ¶
type OutputTail struct {
// contains filtered or unexported fields
}
OutputTail keeps the display tail of command output as it arrives, in memory bounded by the tail regardless of output size. A carriage return starts its line over, as a terminal redraws a progress line. Complete lines wait until revealed, so a burst can scroll through rather than jump.
func (*OutputTail) Flush ¶
func (t *OutputTail) Flush() bool
Flush reveals every pending line at once, for output with nothing to watch roll by.
func (*OutputTail) Lines ¶
func (t *OutputTail) Lines() ([]string, int)
Lines is the last revealed non-blank lines, then an unfinished one once nothing is pending, and the count of lines before the first of them.
func (*OutputTail) Pending ¶
func (t *OutputTail) Pending() int
Pending counts complete lines awaiting a reveal.
func (*OutputTail) Reveal ¶
func (t *OutputTail) Reveal(n int) bool
Reveal shows up to n pending lines, oldest first, and reports whether it showed any.
func (*OutputTail) Roll ¶
func (t *OutputTail) Roll() bool
Roll reveals one frame's share of pending lines: a quarter of the backlog, at least one. A burst scrolls through in a few hundred milliseconds at the frame rate, while steady output stays within a few lines of live.
func (*OutputTail) VisibleThrough ¶
func (t *OutputTail) VisibleThrough() int
VisibleThrough is the source-line boundary revealed so far. Once the backlog is empty it includes the unfinished line, just as Lines does.
func (*OutputTail) Write ¶
func (t *OutputTail) Write(output string)
type OutputView ¶
type OutputView struct {
Lines []string // Retained lines, then an unfinished one.
Dropped int // Lines before Lines no longer retained.
Truncated bool // A retained line lost bytes to the per-line limit.
Released bool // The session released this output for newer output.
Done bool
Exited bool // Exit is the host's reported status.
Exit int
}
OutputView is what an Output retains at one moment.
type Painter ¶
type Painter struct {
Theme livediff.Theme
Colors Colors
Clock func() time.Time // Optional presentation clock, shared with replay.
// LayoutOnly skips syntax decoration while retaining exact text geometry.
// The feed uses it for cold off-screen runs, never visible rows or dialogs.
LayoutOnly bool
// CopySource carries semantic annotations to the native viewport.
CopySource bool
CopyScope uint64 // Stable native entry/block scope for cached source identities.
// contains filtered or unexported fields
}
Painter lays out parsed blocks as terminal rows. Syntax colors come from the same renderer and theme as the live diff pane.
func (*Painter) CopyWrapped ¶ added in v0.2.0
func (p *Painter) CopyWrapped(rows []string, source CopyFragment, gutter int) []string
CopyWrapped projects the already-rendered fragments onto one logical source. The renderer's known content gutter is excluded; wrapping gaps stay attached to the continuation but are copied only when both fragments are selected.
func (*Painter) Dialog ¶
func (p *Painter) Dialog(f DialogFrame, width, height int) []string
Dialog boxes a frame width by height: the title and page position on the top edge, the detail row and a rule, the body with a scroll thumb on its right edge, and controls on the bottom edge.
func (*Painter) DialogPage ¶
func (p *Painter) DialogPage(block Block, width int) DialogPage
DialogPage lays out a block's whole source and retained output. Source keeps the code gutter and output the dashed one, as in the feed; a read's content is source, numbered from the first line it read. Markdown bodies wrap to width; numbered lines wrap as they are shown.
func (*Painter) DialogPageTitle ¶
func (*Painter) Event ¶
event renders a block for the native Activity log: a short label row, then the body flush with the gutter so narrow panes keep their full width. Operations keep their ordinary one-row-per-operation layout.
func (*Painter) Flash ¶
Flash highlights the text of a flashed block's rows, leaving padding and frames plain.
func (*Painter) Journal ¶
journal lays out a final journal result: a heading with its answer and change totals, each question with its answers, then recorded changes. The agent heading already names the author. The shared feed keeps questions to one row so clipping reaches the answers.
func (*Painter) Markdown ¶
markdown renders authored text: fenced programs are highlighted on a fill, list items hang, and tables lay out within the available width.
func (*Painter) QuestionState ¶
func (*Painter) Quote ¶
quote keeps a visible bar on every wrapped row and renders the quoted Markdown normally, including lists, nested quotes, and fenced code. The bar is heavier than feed gutters so a quote reads as quoted, not as a thread.
func (*Painter) ReasoningElided ¶
ReasoningElided uses the same wrapped body and short-summary rule as the renderer. A settled one-line summary is not a collapsed detail view.
type Question ¶
type Question struct {
Text, Answer, Options, State string
}
Question is a presentation snapshot, never an editable or transport record.
type Retention ¶
type Retention struct {
// contains filtered or unexported fields
}
Retention bounds the output a session keeps, releasing the oldest settled output first. Output still running is never released.
type TokenKind ¶
type TokenKind uint8
TextSpan identifies a bound, atomic token, not text resembling a placeholder. Offsets are UTF-8 byte boundaries; spans must not overlap.
type WaitTarget ¶
type WaitTarget struct{ Name, Status string }
WaitTarget retains canonical identity for both live and restored wait notices.