render

Documentation

Overview

Package render provides emoji-driven terminal rendering for the odek agent loop.

It produces structured output for each phase of the ReAct cycle: thinking, tool calls, tool results, and the final answer. When a Renderer is nil or disabled, no output is produced — this keeps the programmatic API silent and the CLI colorful.

Design

• Zero dependencies. Uses ANSI escape codes directly.
• Emoji icons as visual anchors (🧠 🔧 ✅ ❌).
• Color detection: respects NO_COLOR env var and tty detection.
• Truncation: tool output is collapsed to one line to keep the terminal scannable during multi-step tool chains.
• Maintainable: each rendering method is self-contained; adding a new event type requires one constant + one method.

Index

• func ColorEnabled() bool
• func FirstSentence(text string) string
• func ToolEmoji(name string) string
• func ToolPreview(name, args string) string
• type Event
  • func (e Event) String() string
• type Renderer
  • func New(w io.Writer, color bool) *Renderer
  • func (r *Renderer) ContextTrimmed(mode string, count int)
  • func (r *Renderer) Error(err error)
  • func (r *Renderer) FinalAnswer(text string)
  • func (r *Renderer) Iteration(n, maxN int, latency time.Duration, inTokens, outTokens int, turn int)
  • func (r *Renderer) MemoryConsolidated(target string, before, after int)
  • func (r *Renderer) MemoryEpisode(action, detail string)
  • func (r *Renderer) MemoryFact(action, target, content string)
  • func (r *Renderer) NarratorMessage(msg string)
  • func (r *Renderer) SkillAutoLoaded(names []string)
  • func (r *Renderer) SkillDeleted(name string)
  • func (r *Renderer) SkillLoaded(names []string)
  • func (r *Renderer) SkillSaved(name string)
  • func (r *Renderer) SkillSuggested(name, heuristic string)
  • func (r *Renderer) Start(task string)
  • func (r *Renderer) Summary(inTokens, outTokens, cacheCreate, cacheRead, cached int)
  • func (r *Renderer) Thinking(text string)
  • func (r *Renderer) ToolCall(name, args string)
  • func (r *Renderer) ToolRecovery(tool, detail string)
  • func (r *Renderer) ToolResult(output string)
  • func (r *Renderer) WithMemoryVerbose(verbose bool) *Renderer
  • func (r *Renderer) WithModel(name string) *Renderer
  • func (r *Renderer) WithSkillVerbose(verbose bool) *Renderer

Functions

func ColorEnabled

func ColorEnabled() bool

ColorEnabled returns true when the terminal supports ANSI colors and the user hasn't set NO_COLOR.

func FirstSentence

func FirstSentence(text string) string

FirstSentence extracts the first sentence from reasoning/thinking text. Returns a user-facing preview under 20 words. Falls back to truncation if no sentence boundary is found. Returns empty string for empty input. Handles standard punctuation (. ! ?) followed by space or newline, and also handles ellipsis (...) and end-of-input as boundaries.

func ToolEmoji

func ToolEmoji(name string) string

toolEmoji returns an emoji that visually signals the tool category. Each tool gets an icon matching its domain so users can scan tool traces at a glance without reading every label. ToolEmoji returns an emoji for the given tool name based on its category. Exported so non-renderer consumers (e.g., Telegram bot) can use the same mapping.

func ToolPreview

func ToolPreview(name, args string) string

ToolPreview extracts a meaningful short preview from a tool call's JSON args. Returns a human-readable snippet like "main.go" for read_file, or "go test ./..." for shell. Falls back to a truncated command description.

Types

type Event

type Event int

Event identifies a point in the agent loop lifecycle. Programmatic consumers can type-switch on Event values.

const (
	// IterStart marks the beginning of an iteration cycle.
	IterStart Event = iota
	// Thinking is the model's reasoning text before tool calls.
	Thinking
	// ToolCall is a tool invocation requested by the model.
	ToolCall
	// ToolResult is the output from a completed tool call.
	ToolResult
	// FinalAnswer is the model's final response (no tool calls).
	FinalAnswer
	// Error is a non-fatal error during the loop.
	Error
)

func (Event) String

func (e Event) String() string

type Renderer

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

Renderer writes formatted agent loop output to an io.Writer. The zero value is usable but won't produce any output — call New() to create a properly initialized Renderer.

func New

func New(w io.Writer, color bool) *Renderer

New creates a Renderer that writes to w. If color is false, ANSI escape codes are stripped from the output.

func (*Renderer) ContextTrimmed

func (r *Renderer) ContextTrimmed(mode string, count int)

ContextTrimmed reports that the engine dropped message groups to stay within the model's context window. mode is "proactive" (pre-call budget trim) or "survival" (post-error nuclear trim).

func (*Renderer) Error

func (r *Renderer) Error(err error)

Error prints a non-fatal loop error with a cross emoji.

func (*Renderer) FinalAnswer

func (r *Renderer) FinalAnswer(text string)

FinalAnswer prints the model's concluding response with a checkmark emoji.

func (*Renderer) Iteration

func (r *Renderer) Iteration(n, maxN int, latency time.Duration, inTokens, outTokens int, turn int)

Iteration prints the cycle header with optional turn statistics and turn number. When turn > 0, shows "Turn N" in the header. When latency > 0 or tokens are reported, a compact stats suffix appears on the same line: [1,247 in · 342 out · 4.1s]

func (*Renderer) MemoryConsolidated

func (r *Renderer) MemoryConsolidated(target string, before, after int)

MemoryConsolidated prints a fact-consolidation notification (before → after).

func (*Renderer) MemoryEpisode

func (r *Renderer) MemoryEpisode(action, detail string)

MemoryEpisode prints an episode-tier lifecycle notification. action is one of "stored", "deduped", "evicted", "promoted", "pending_review".

func (*Renderer) MemoryFact

func (r *Renderer) MemoryFact(action, target, content string)

MemoryFact prints a fact-tier lifecycle notification. action is one of "added", "merged", "replaced", "removed".

func (*Renderer) NarratorMessage

func (r *Renderer) NarratorMessage(msg string)

NarratorMessage prints an engaging, human-friendly narration line. Used in "engaging" interaction mode instead of raw tool call output.

func (*Renderer) SkillAutoLoaded

func (r *Renderer) SkillAutoLoaded(names []string)

SkillAutoLoaded prints a notification about auto-loaded skills at startup.

func (*Renderer) SkillDeleted

func (r *Renderer) SkillDeleted(name string)

SkillDeleted prints confirmation of a deleted skill.

func (*Renderer) SkillLoaded

func (r *Renderer) SkillLoaded(names []string)

SkillLoaded prints a notification about lazy-loaded skills.

func (*Renderer) SkillSaved

func (r *Renderer) SkillSaved(name string)

SkillSaved prints confirmation of a saved skill.

func (*Renderer) SkillSuggested

func (r *Renderer) SkillSuggested(name, heuristic string)

SkillSuggested prints a skill suggestion from the learning system.

func (*Renderer) Start

func (r *Renderer) Start(task string)

Start is a no-op — session context is now shown via iteration headers and session banners (REPL). Kept for API compatibility.

func (*Renderer) Summary

func (r *Renderer) Summary(inTokens, outTokens, cacheCreate, cacheRead, cached int)

Summary prints a run summary line with total token and cache statistics. Emitted after the final answer when at least one stat is non-zero. Shows: total input/output tokens, cache creation/read/cached tokens. Uses plain text labels (no symbols) for cross-terminal compatibility.

func (*Renderer) Thinking

func (r *Renderer) Thinking(text string)

Thinking prints the model's reasoning text with a brain emoji.

func (*Renderer) ToolCall

func (r *Renderer) ToolCall(name, args string)

ToolCall prints a tool invocation with a category emoji, name, and compact args.

func (*Renderer) ToolRecovery

func (r *Renderer) ToolRecovery(tool, detail string)

ToolRecovery reports that a repeatedly-failing tool triggered an automatic corrective hint so the model changes approach.

func (*Renderer) ToolResult

func (r *Renderer) ToolResult(output string)

ToolResult prints a one-line summary of the tool output in gray. Long output is collapsed to the first line + ellipsis to keep the terminal readable during multi-step tool chains.

func (*Renderer) WithMemoryVerbose

func (r *Renderer) WithMemoryVerbose(verbose bool) *Renderer

WithMemoryVerbose controls whether memory lifecycle notifications (fact add/merge/consolidate, episode store/dedup/evict/promote) and internal agent signals (context trim, tool-failure recovery) are shown. Disabled by default to keep the terminal scannable; enabled by verbose interaction mode.

func (*Renderer) WithModel

func (r *Renderer) WithModel(name string) *Renderer

WithModel sets the model name displayed in iteration headers.

func (*Renderer) WithSkillVerbose

func (r *Renderer) WithSkillVerbose(verbose bool) *Renderer

WithSkillVerbose controls whether skill lifecycle notifications (auto-load, save, suggest, delete) are shown. Disabled by default.