chain

Documentation

Overview

Package chain builds the chronological "prompt chain" of a work session: the conversation replayed turn-by-turn with a cumulative-cost gutter, grouped by the user prompt (PromptID) that triggered each run of turns.

It is the data layer for the receipt's chain view (design-documents/DESIGN.md). Rendering (cursor, tab, color) lives in the surface layers; this package is pure and depends only on package event, so it is cheap to test and reuse from both the static ANSI surface and the deferred interactive TUI.

Honesty: cost is the api-equivalent view; a turn whose api-equivalent is not computable (nil) contributes 0 to the running total and flips the chain to not-Confident, so the gutter is never silently overstated.

Index

• type Chain
  • func Build(evs []event.AgentEvent) Chain
• type Group
• type Turn

Types

type Chain

type Chain struct {
	Turns       []Turn
	Groups      []Group
	TotalMicros int64
	Confident   bool // false if any turn's cost was not computable
}

Chain is a session's turns in time order, plus their grouping by prompt.

func Build

func Build(evs []event.AgentEvent) Chain

Build orders evs chronologically (stable, tie-broken by EventID), threads the cumulative-cost gutter, and groups turns by PromptID in first-seen order. Input need not be pre-sorted and is not mutated.

type Group

type Group struct {
	PromptID    string
	Turns       []Turn
	TotalMicros int64
	Start       time.Time
}

Group is the run of turns triggered by one user prompt. PromptID == "" is the single bucket for turns whose prompt boundary the logs didn't record.

type Turn

type Turn struct {
	EventID    string
	PromptID   string
	TS         time.Time
	Model      string
	CostMicros int64 // api-equivalent micros; 0 when not computable
	HasCost    bool  // false when api-equivalent was nil (render faint)
	CumMicros  int64 // running cumulative micros through this turn
	Files      []string
}

Turn is one billable turn in the chain, carrying its own cost and the running cumulative total through it (the gutter).