Documentation
¶
Overview ¶
Package html provides HTML session viewer generation. It converts stored sessions into self-contained HTML files for viewing agent conversation history in a browser.
Index ¶
- func ComputeFallbackDuration(messages []MessageView) (duration time.Duration, first, last time.Time)
- func CountDiffLines(output string) (added, removed int)
- func ExtractFilePathFromInput(input string) string
- func FormatDuration(d time.Duration) string
- func FormatToolInputCompact(tool *ToolCallView) template.HTML
- func FormatToolSummary(tool *ToolCallView) string
- func FormatWorkBlockSummary(wb *WorkBlockView) string
- func IsDiffOutput(output string) bool
- func RenderDiffHTML(output string) template.HTML
- func RenderMarkdown(text string) template.HTML
- func StripANSI(s string) string
- func TemplateFuncMap() template.FuncMap
- func ToolCategory(name string) string
- type AhaMomentView
- type BrandColors
- type ChapterItem
- type ChapterView
- type FileChangeView
- type Generator
- func (g *Generator) Generate(t *session.StoredSession) ([]byte, error)
- func (g *Generator) GenerateToFile(t *session.StoredSession, outputPath string) error
- func (g *Generator) GenerateToFileWithSummary(t *session.StoredSession, summary *session.SummarizeResponse, ...) error
- func (g *Generator) GenerateWithSummary(t *session.StoredSession, summary *session.SummarizeResponse) ([]byte, error)
- type MessageView
- type MetadataView
- type SageoxInsightView
- type StatsView
- type SummaryView
- type TemplateData
- type ToolCallView
- type WorkBlockView
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeFallbackDuration ¶
func ComputeFallbackDuration(messages []MessageView) (duration time.Duration, first, last time.Time)
ComputeFallbackDuration derives duration from message timestamps when metadata times are missing. Returns zero values if no valid timestamps found.
func CountDiffLines ¶
CountDiffLines counts added and removed lines in a unified diff output. Lines starting with "+" (not "+++") are counted as added. Lines starting with "-" (not "---") are counted as removed.
func ExtractFilePathFromInput ¶
ExtractFilePathFromInput parses tool input (JSON or raw) to find a file_path field.
func FormatDuration ¶
FormatDuration creates a human-readable duration string.
func FormatToolInputCompact ¶ added in v0.3.0
func FormatToolInputCompact(tool *ToolCallView) template.HTML
FormatToolInputCompact renders a tool call as a compact terminal-style command. e.g., ">_ Bash git status", ">_ Read cmd/ox/main.go"
func FormatToolSummary ¶
func FormatToolSummary(tool *ToolCallView) string
FormatToolSummary creates a compact summary for tool calls. Examples: "Edit(file.go) -- +5 / -3 lines", "Read(config.yaml)", "Bash"
func FormatWorkBlockSummary ¶ added in v0.3.0
func FormatWorkBlockSummary(wb *WorkBlockView) string
FormatWorkBlockSummary creates a human-readable summary like "12 tool calls (Read 5, Grep 4, Bash 3)".
func IsDiffOutput ¶
IsDiffOutput detects whether the output string looks like a unified diff. Checks for common diff markers: lines starting with @@, +++, or ---.
func RenderDiffHTML ¶
RenderDiffHTML wraps diff lines in colored spans for HTML display. Lines are HTML-escaped first, then wrapped:
- Lines starting with "+" (not "+++") get class="diff-add"
- Lines starting with "-" (not "---") get class="diff-remove"
- Lines starting with "@@" get class="diff-header"
Returns raw HTML safe for template rendering.
func RenderMarkdown ¶
RenderMarkdown converts markdown text to template.HTML via goldmark. Goldmark's default behavior strips raw HTML tags for XSS safety, so <script> and similar tags are silently removed from output. HardWraps mode converts single newlines to <br> for plain-text readability. Returns empty HTML for empty input.
func TemplateFuncMap ¶ added in v0.3.0
TemplateFuncMap returns the template function map used by the HTML template. Exported so callers can reuse the same helpers if needed.
func ToolCategory ¶ added in v0.3.0
ToolCategory maps a tool name to a semantic category for timeline dot coloring. Categories: read (investigation), edit (changes), exec (execution), search (research).
Types ¶
type AhaMomentView ¶
type AhaMomentView struct {
Seq int // message sequence number for navigation
Role string // user, assistant, system
Type string // question, insight, decision, breakthrough, synthesis
Highlight string // the key text/quote
Why string // why this moment was important
}
AhaMomentView represents a pivotal conversation moment for display. Documents collaborative intelligence between human and AI.
type BrandColors ¶
type BrandColors struct {
Primary string // sage green
Secondary string // copper gold
Accent string // forest green
Text string
TextDim string
BgDark string
BgCard string
Border string
Error string
Info string
}
BrandColors defines the SageOx brand color palette for CSS variable injection.
func DefaultBrandColors ¶
func DefaultBrandColors() BrandColors
DefaultBrandColors returns the SageOx brand color palette from the theme.
type ChapterItem ¶ added in v0.3.0
type ChapterItem struct {
IsWorkBlock bool
Message *MessageView // non-nil for conversation messages
WorkBlock *WorkBlockView // non-nil for grouped tool/system blocks
}
ChapterItem is either a conversation message or a work block. Exactly one of Message or WorkBlock is non-nil.
type ChapterView ¶ added in v0.3.0
type ChapterView struct {
ID int // 1-based chapter number
Title string // chapter title (LLM-generated or heuristic)
Items []ChapterItem // interleaved conversation messages and work blocks
}
ChapterView is a narrative section of the session, grouping conversation turns and their associated work blocks into a coherent unit.
func GroupIntoChapters ¶ added in v0.3.0
func GroupIntoChapters(messages []MessageView, chapterTitles []string) []ChapterView
GroupIntoChapters converts a flat message list into a structured chapter view. Each chapter groups a conversation turn (user message + assistant responses) with tool/system calls collapsed into work blocks between conversation messages.
chapterTitles are optional LLM-generated titles; when provided, they override heuristic titles. Titles are matched by position (first title → first chapter).
type FileChangeView ¶ added in v0.3.0
type FileChangeView struct {
Path string // shortened file path (home dir stripped)
Added int // lines added
Removed int // lines removed
}
FileChangeView represents a file modified during the session.
func ExtractFilesChanged ¶ added in v0.3.0
func ExtractFilesChanged(messages []MessageView) []FileChangeView
ExtractFilesChanged scans messages for Edit/Write/MultiEdit tool calls and extracts the files that were modified along with diff stats.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator creates HTML session viewers from stored sessions.
func NewGenerator ¶
NewGenerator creates a generator with embedded templates. The template is parsed once and reused for multiple Generate calls.
func (*Generator) Generate ¶
func (g *Generator) Generate(t *session.StoredSession) ([]byte, error)
Generate creates HTML bytes from a StoredSession.
func (*Generator) GenerateToFile ¶
func (g *Generator) GenerateToFile(t *session.StoredSession, outputPath string) error
GenerateToFile writes HTML to a file. TODO(server-side): move to server-side for MVP+1; client should not write to ledger directly.
func (*Generator) GenerateToFileWithSummary ¶
func (g *Generator) GenerateToFileWithSummary(t *session.StoredSession, summary *session.SummarizeResponse, outputPath string) error
GenerateToFileWithSummary writes HTML to a file with a summary section. TODO(server-side): move to server-side for MVP+1; client should not write to ledger directly.
func (*Generator) GenerateWithSummary ¶
func (g *Generator) GenerateWithSummary(t *session.StoredSession, summary *session.SummarizeResponse) ([]byte, error)
GenerateWithSummary creates HTML bytes from a StoredSession with a summary.
type MessageView ¶
type MessageView struct {
ID int
Type string // user, assistant, system, tool
SenderLabel string // display name (e.g., "user", "assistant")
Timestamp time.Time
Content template.HTML // markdown rendered to HTML via goldmark (server-side)
ToolCall *ToolCallView
IsAhaMoment bool // true if this message is a key insight moment
AhaMomentID int // aha moment index (1-based) for navigation
AhaMoment *AhaMomentView // full aha moment details for inline display
}
MessageView represents a single session entry for display.
type MetadataView ¶
type MetadataView struct {
AgentType string
AgentVersion string
Model string
Username string
StartedAt time.Time
EndedAt time.Time
}
MetadataView holds session metadata for display.
type SageoxInsightView ¶
type SageoxInsightView struct {
Seq int // message sequence number for navigation
Topic string // domain area (e.g., "react-patterns")
Insight string // what guidance was applied
Impact string // the value it provided
}
SageoxInsightView represents a moment where SageOx guidance provided value.
type StatsView ¶
type StatsView struct {
TotalMessages int
UserMessages int
ToolMessages int // count of tool call entries
FilesChanged int // count of distinct files modified
}
StatsView holds session statistics for display.
type SummaryView ¶
type SummaryView struct {
Text string // one paragraph executive summary
KeyActions []string // bullet points of key actions taken
Outcome string // success/partial/failed
TopicsFound []string // topics detected during session
FinalPlan string // final plan/architecture from session
Diagrams []string // extracted mermaid diagrams (raw mermaid code)
ChapterTitles []string // LLM-generated chapter titles for narrative sections
SageoxInsights []SageoxInsightView // moments where SageOx guidance provided value
}
SummaryView holds LLM-generated session summary for display.
type TemplateData ¶
type TemplateData struct {
Title string
Summary *SummaryView // LLM-generated summary (may be nil)
Metadata *MetadataView
Messages []MessageView // flat message list (kept for backward compat)
Chapters []ChapterView // grouped conversation view (preferred for rendering)
FilesChanged []FileChangeView // files modified during the session
AhaMoments []AhaMomentView // pivotal moments of collaborative intelligence
SageoxInsights []SageoxInsightView // moments where SageOx guidance provided value
Statistics *StatsView
BrandColors BrandColors
Styles template.CSS // CSS content (safe)
Scripts template.JS // JS content (safe)
}
TemplateData is the root view model for the HTML template.
func BuildTemplateData ¶ added in v0.3.0
func BuildTemplateData(t *session.StoredSession, summary *session.SummarizeResponse) *TemplateData
BuildTemplateData converts a stored session and optional summary into the full template data model. Exported so callers (e.g., session_html.go) can access the enriched data for writing back to summary.json.
type ToolCallView ¶
type ToolCallView struct {
Name string
Summary string // compact summary like "Edit(file.go) -- +5 / -3 lines"
FormattedInput template.HTML // pre-rendered compact command (e.g., ">_ Bash git status")
IsSimple bool // true = render inline (no collapsible details)
Input string
Output string
}
ToolCallView holds tool invocation details for display.
type WorkBlockView ¶ added in v0.3.0
type WorkBlockView struct {
Messages []MessageView // the tool/system messages in this block
ToolCounts map[string]int // tool name -> count (e.g., {"Read": 5, "Grep": 4})
Summary string // formatted summary text
TotalTools int // total tool call count
HasEdits bool // true if block contains Edit/Write/MultiEdit calls
}
WorkBlockView groups consecutive tool/system calls between conversation turns. Renders as a collapsed summary like "12 tool calls (Read 5, Grep 4, Bash 3)".