Documentation
¶
Overview ¶
Package conversation manages message history and emits events for LLM interactions.
Index ¶
- type Builder
- func (b *Builder) AddAssistantMessage(msg message.Message)
- func (b *Builder) AddBookmark(label string)
- func (b *Builder) AddDisplayMessage(ctx context.Context, role roles.Role, content string)
- func (b *Builder) AddEphemeralToolResult(ctx context.Context, toolName, toolCallID, result string, estimatedTokens int)
- func (b *Builder) AddMetadata(data map[string]any)
- func (b *Builder) AddToolCall(id, name string, args map[string]any)
- func (b *Builder) AddToolResult(ctx context.Context, toolName, toolCallID, result string, estimatedTokens int)
- func (b *Builder) AddUserMessage(ctx context.Context, text string, estimatedTokens int)
- func (b *Builder) AddUserMessageWithImages(ctx context.Context, text string, images message.Images, estimatedTokens int)
- func (b *Builder) AppendContent(content string)
- func (b *Builder) AppendThinking(thinking string)
- func (b *Builder) BackfillToolTokens(delta int)
- func (b *Builder) Clear()
- func (b *Builder) CompleteToolCall(ctx context.Context, id, result string, err error)
- func (b *Builder) DeduplicateSystemMessages()
- func (b *Builder) DropN(n int)
- func (b *Builder) EjectEphemeralMessages()
- func (b *Builder) EjectSyntheticMessages()
- func (b *Builder) Estimate(ctx context.Context, text string) int
- func (b *Builder) FinalizeAssistant()
- func (b *Builder) History() message.Messages
- func (b *Builder) InjectMessage(ctx context.Context, role roles.Role, content string)
- func (b *Builder) Len() int
- func (b *Builder) NextID() string
- func (b *Builder) PruneEmptyAssistantMessages()
- func (b *Builder) PruneToolResults(protectTokens, argThreshold int, estimate func(string) int)
- func (b *Builder) RebuildAfterCompaction(summary string, summaryTokens int, preserved message.Messages)
- func (b *Builder) Restore(msgs message.Messages)
- func (b *Builder) SetError(err error)
- func (b *Builder) StartAssistant()
- func (b *Builder) StartToolCall(id string)
- func (b *Builder) SystemPrompt() string
- func (b *Builder) TrimDuplicateSynthetics()
- func (b *Builder) Turns() []sdk.Turn
- func (b *Builder) UpdateSystemPrompt(ctx context.Context, prompt string)
- func (b *Builder) UpdateThinking(index int, thinking string)
- type EventSink
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder manages conversation history and emits UI events.
Message lifecycle:
StartAssistant() → creates current message, emits MessageStarted AppendContent/AppendThinking → appends to current, emits MessagePartAdded/Updated AddToolCall/StartToolCall/CompleteToolCall → manages tool call parts FinalizeAssistant() → commits current to history, emits MessageFinalized
current is nil between messages. Methods that require current log a warning and return if called outside the Start/Finalize lifecycle.
func NewBuilder ¶
func NewBuilder(sink EventSink, systemPrompt string, systemTokens int, estimate func(context.Context, string) int) *Builder
NewBuilder creates a new conversation builder with the given event sink, system prompt, pre-computed system token count, and estimate function.
func (*Builder) AddAssistantMessage ¶
AddAssistantMessage adds a complete assistant message to the API history. This should be called after receiving a response from the provider.
func (*Builder) AddBookmark ¶
AddBookmark adds a structural bookmark divider to the history and emits MessageAdded. Bookmarks are rendered as separators in the UI, persisted, but never sent to any LLM.
func (*Builder) AddDisplayMessage ¶
AddDisplayMessage adds a display-only message to the history and emits MessageAdded. Display-only messages are visible in the UI and persisted but never sent to any LLM.
func (*Builder) AddEphemeralToolResult ¶
func (b *Builder) AddEphemeralToolResult(ctx context.Context, toolName, toolCallID, result string, estimatedTokens int)
AddEphemeralToolResult adds a tool result that will be pruned after one model turn. Used for pre-execution errors (tool not found, policy deny, parse failures, etc.) that the model needs to see once but shouldn't persist in history. When estimatedTokens > 0, it is used directly (avoids re-estimation).
func (*Builder) AddMetadata ¶
AddMetadata adds a structured metadata message to the history. Metadata is not rendered in the UI and never sent to any LLM, but persists in sessions and is included in structured exports (JSON/JSONL).
func (*Builder) AddToolCall ¶
AddToolCall adds a pending tool call to the current message with pre-formatted args.
func (*Builder) AddToolResult ¶
func (b *Builder) AddToolResult(ctx context.Context, toolName, toolCallID, result string, estimatedTokens int)
AddToolResult adds a tool execution result to the API history. When estimatedTokens > 0, it is used directly (avoids re-estimation).
func (*Builder) AddUserMessage ¶
AddUserMessage adds a completed user message and emits MessageAdded. When estimatedTokens > 0, it is used directly (avoids re-estimation of already-estimated text).
func (*Builder) AddUserMessageWithImages ¶
func (b *Builder) AddUserMessageWithImages(ctx context.Context, text string, images message.Images, estimatedTokens int)
AddUserMessageWithImages adds a completed user message with images and emits MessageAdded. Images flow through to providers via their convert layers (Ollama: raw bytes, OpenRouter/LlamaCPP: base64 data URLs). When estimatedTokens > 0, it is used directly (avoids re-estimation).
func (*Builder) AppendContent ¶
AppendContent appends content text to the current assistant message. Merges with the last content part if present, otherwise creates a new part.
func (*Builder) AppendThinking ¶
AppendThinking appends thinking text to the current assistant message.
func (*Builder) BackfillToolTokens ¶
BackfillToolTokens distributes an API-reported token delta across tool result messages added since the last assistant message. Walks backward from the end. Single tool result (common case) gets the full delta; multiple distribute proportionally by content length.
func (*Builder) Clear ¶
func (b *Builder) Clear()
Clear removes all messages except the system prompt from the history.
func (*Builder) CompleteToolCall ¶
CompleteToolCall marks a tool call as complete with its result, matching by ID.
func (*Builder) DeduplicateSystemMessages ¶
func (b *Builder) DeduplicateSystemMessages()
DeduplicateSystemMessages keeps only the first system message, removing duplicates.
func (*Builder) EjectEphemeralMessages ¶
func (b *Builder) EjectEphemeralMessages()
EjectEphemeralMessages removes ephemeral tool results and their matching calls from history. Ephemeral messages influence one turn, then get stripped along with their paired calls.
func (*Builder) EjectSyntheticMessages ¶
func (b *Builder) EjectSyntheticMessages()
EjectSyntheticMessages removes all synthetic messages from history. Used when eject is enabled — synthetics influence one turn, then get stripped.
func (*Builder) Estimate ¶
Estimate returns the token count for text using the configured estimator.
func (*Builder) FinalizeAssistant ¶
func (b *Builder) FinalizeAssistant()
FinalizeAssistant completes the current assistant message and emits MessageFinalized.
func (*Builder) InjectMessage ¶
InjectMessage adds a synthetic message to the API history. The assistant emits a SyntheticInjected event for UI display separately.
func (*Builder) PruneEmptyAssistantMessages ¶
func (b *Builder) PruneEmptyAssistantMessages()
PruneEmptyAssistantMessages removes assistant messages with no content, thinking, or tool calls.
func (*Builder) PruneToolResults ¶
PruneToolResults prunes old tool results in the history in-place. Takes an explicit local estimate function (not the stored context-aware callback) because pruning is high-frequency and should always use local estimation.
func (*Builder) RebuildAfterCompaction ¶
func (b *Builder) RebuildAfterCompaction(summary string, summaryTokens int, preserved message.Messages)
RebuildAfterCompaction replaces conversation history with a compaction summary and preserved recent message. The system prompt (index 0) is kept in place. summaryTokens is the pre-computed token estimate for the compaction summary.
func (*Builder) Restore ¶
Restore replaces the conversation history with the given message. The first message in msgs should be the system prompt.
func (*Builder) StartAssistant ¶
func (b *Builder) StartAssistant()
StartAssistant begins a new assistant message and emits MessageStarted.
func (*Builder) StartToolCall ¶
StartToolCall transitions a Pending tool call to Running and emits MessagePartUpdated.
func (*Builder) SystemPrompt ¶
SystemPrompt returns the assembled system prompt sent to the model.
func (*Builder) TrimDuplicateSynthetics ¶
func (b *Builder) TrimDuplicateSynthetics()
TrimDuplicateSynthetics removes duplicate synthetic messages from history, keeping only the most recent occurrence of each.
func (*Builder) Turns ¶
Turns returns conversation turns as sdk.Turn slices. Includes only normal user/assistant text messages — excludes system, tool, synthetic, and ephemeral message.
func (*Builder) UpdateSystemPrompt ¶
UpdateSystemPrompt updates the system prompt without clearing conversation history. This is used when switching modes — the conversation context is preserved. If the system prompt is missing (e.g., after clear on empty history), it is prepended.
func (*Builder) UpdateThinking ¶
UpdateThinking replaces the thinking content on the message at the given history index. Used by thinking management to mutate the builder in place (strip or rewrite).
Source Files