core

Sep 23, 2026

Changes in this version

+ const MetaKeyMsgID

+ func IsTransientUserMessage(m Message) bool

+ func RebaseCheckpoints(state *State, survivorOf map[int]int)

type State

+ func (s *State) LastCompactionRebase() map[int]int

Sep 22, 2026

Changes in this version

type CompactInputs

+ TargetTokens int

type PruneCallOptions

+ TargetTokens int

Sep 15, 2026

Changes in this version

type ResponseValidator

+ func (rv *ResponseValidator) LooksLikeIntentNarration(content string) bool

Sep 13, 2026

Changes in this version

type ConversationOptimizer

+ func (opt *ConversationOptimizer) OptimizeConversationWithReport(messages []Message, opts OptimizeOptions) ([]Message, bool)

Sep 11, 2026

Changes in this version

+ func ToolCallIDFromContext(ctx context.Context) string

+ func ToolCallIndexFromContext(ctx context.Context) int

+ func ToolNameFromContext(ctx context.Context) string

+ func WithToolCallMetadata(ctx context.Context, callID, toolName string, callIndex int) context.Context

Sep 8, 2026

Changes in this version

type Message

+ func ToolResultMessageWithImages(toolCallID, toolName string, content string, images []ImageData) Message

May 27, 2026

Changes in this version

type Options

+ CompactionStartFraction float64

Sep 1, 2026

Changes in this version

+ const BriefWordLimit

+ const DetailedWordLimit

+ const DiagnosticTriggerPreSendValidation

+ const DiagnosticTriggerProviderRejection

+ const LayeredThreshold

+ const MetaArchiveBatchSize

+ const MetaCompactionThreshold

+ const MinLayerSize

+ const StructuralMinMessagesToCompact

+ const StructuralMinMiddleMessages

+ const StructuralRecentToKeep

+ const SummaryWordLimit

+ const ToolStatusCompleted

+ const ToolStatusError

+ const ToolThreadingViolationGapBeforeResult

+ const ToolThreadingViolationMissingResult

+ const ToolThreadingViolationOrphanResult

+ const ToolThreadingViolationOutOfOrder

+ func IsToolThreadingError(err error) bool

+ func WriteDiagnosticTranscript(c DiagnosticCapture, dir string) (string, error)

type Agent

+ func (a *Agent) Checkpoints() []TurnCheckpoint

+ func (a *Agent) Interrupt()

+ func (a *Agent) ResetInterrupt() context.Context

type ChatUsage

+ ImageTokens int

+ type CompactInputs struct

+ Checkpoints []TurnCheckpoint

+ EstimateFn func(messages []Message) int

+ MaskNameFn func(callID string) string

+ Messages []Message

+ SubstitutionTargetFraction float64

+ TokenLimit int

type CompactionResult

+ func CompactWith(in CompactInputs) CompactionResult

type ConversationOptimizer

+ func (opt *ConversationOptimizer) OptimizeConversationWithOptions(messages []Message, opts OptimizeOptions) []Message

+ type ConversationPruner struct

+ func NewConversationPruner(opts PrunerOptions) *ConversationPruner

+ func (cp *ConversationPruner) MinMessagesToKeep() int

+ func (cp *ConversationPruner) Prune(ctx context.Context, messages []Message, currentTokens, maxTokens int, ...) []Message

+ func (cp *ConversationPruner) RecentMessagesToKeep() int

+ func (cp *ConversationPruner) SetRecentMessagesToKeep(n int)

+ func (cp *ConversationPruner) SetSlidingWindowSize(n int)

+ func (cp *ConversationPruner) SetStrategy(s PruningStrategy)

+ func (cp *ConversationPruner) SetThreshold(t float64)

+ func (cp *ConversationPruner) ShouldPrune(currentTokens, maxTokens int) bool

+ func (cp *ConversationPruner) SlidingWindowSize() int

+ func (cp *ConversationPruner) Strategy() PruningStrategy

+ func (cp *ConversationPruner) Threshold() float64

+ type DiagnosticCapture struct

+ Error string

+ Iteration int

+ Messages []Message

+ Provider string

+ SystemPrompt string

+ Trigger string

+ Violations []ToolThreadingViolation

+ type FileChange struct

+ Op string

+ Path string

+ type LLMSummarizer func(ctx context.Context, messages []Message, hint SummarizerHint) (string, error)

type Message

+ Status string

+ func IterativelyMaskOldestConsumedToolResults(messages []Message, nameFn func(callID string) string, target int, ...) ([]Message, int, bool)

+ func IterativelySubstituteCheckpoints(messages []Message, checkpoints []TurnCheckpoint, target int, ...) ([]Message, int, bool)

+ func ToolErrorMessage(toolCallID, toolName string, errMsg string) Message

+ type MessageImportance struct

+ Age int

+ ContentLength int

+ HasToolCalls bool

+ ImportanceScore float64

+ Index int

+ IsError bool

+ IsToolResult bool

+ IsUserQuery bool

+ Role string

+ TokenEstimate int

+ type OptimizeOptions struct

+ MaskConsumedToolResults bool

type Options

+ CompactionTriggerFraction float64

+ DisableMinimumSubstanceGuard bool

+ InitialCheckpoints []TurnCheckpoint

+ LLMSummarizer LLMSummarizer

+ OnDiagnosticCapture func(DiagnosticCapture)

+ Pruner *ConversationPruner

+ SubstitutionTargetFraction float64

type ProviderInfo

+ MaxOutputTokens int

+ type PruneCallOptions struct

+ EstimateFn func([]Message) int

+ IsAgenticFlow bool

+ Optimizer *ConversationOptimizer

+ Provider string

+ RequiredAvailableTokens int

+ Summarizer LLMSummarizer

+ type PrunerOptions struct

+ ContextThreshold float64

+ MinMessagesToKeep int

+ RecentMessagesToKeep int

+ SlidingWindowSize int

+ Strategy PruningStrategy

+ type PruningStrategy string

+ const PruneStrategyAdaptive

+ const PruneStrategyHybrid

+ const PruneStrategyImportance

+ const PruneStrategyNone

+ const PruneStrategySlidingWindow

type ResponseValidator

+ func (rv *ResponseValidator) LooksInsufficientAfterToolCalls(content string) bool

+ func (rv *ResponseValidator) LooksLikeReasoningOnlyAfterToolResults(content, reasoningContent string) bool

+ type StructuralCompactionResult struct

+ Messages []Message

+ Strategy string

+ Summarized int

+ func CompactWithLLMSummary(ctx context.Context, messages []Message, summarizer LLMSummarizer) StructuralCompactionResult

+ type SummarizerHint struct

+ DetailLevel string

+ MaxWords int

+ type ToolThreadingError struct

+ Provider string

+ Violations []ToolThreadingViolation

+ Wrapped error

+ func (e *ToolThreadingError) Error() string

+ func (e *ToolThreadingError) Unwrap() error

+ type ToolThreadingViolation struct

+ Detail string

+ Index int

+ Kind string

+ ToolCallID string

+ func ValidateToolThreading(messages []Message) []ToolThreadingViolation

type TurnCheckpoint

+ ArchiveLine string

+ FileChanges []FileChange

+ RevisionID string

+ func ArchiveOldCheckpoints(ctx context.Context, checkpoints []TurnCheckpoint, keepRecent int, ...) []TurnCheckpoint

May 14, 2026

Changes in this version

+ func IsClientError(err error) bool

+ type ClientError struct

+ Provider string

+ Wrapped error

+ func (e *ClientError) Error() string

+ func (e *ClientError) Unwrap() error

May 14, 2026

Changes in this version

type Options

+ OnCheckpoint func(TurnCheckpoint)

May 13, 2026

Changes in this version

type Message

+ func DropOldestTurns(messages []Message, targetTokens int) []Message

May 13, 2026

Changes in this version

+ const MetaKeyCheckpoint

+ var ErrZeroChoices = errors.New("provider returned zero choices")

type CompactionResult

+ func Compact(messages []Message, tokenLimit int) CompactionResult

type Message

+ Meta map[string]string

+ func DropOldestCheckpointSummaries(messages []Message, targetTokens int) []Message

+ func (m *Message) SetMeta(key, value string)

type TurnCheckpoint

+ UserMessage string

May 13, 2026

Changes in this version

type Message

+ func ToolResultMessage(toolCallID, toolName string, content string) Message

+ type ParameterConfig struct

+ Alternatives []string

+ Description string

+ Name string

+ Required bool

+ Type string

+ type ToolConfig struct

+ Aliases []string

+ Description string

+ Handler ToolHandler

+ HandlerWithImages ToolHandlerWithImages

+ MaxResultSize int

+ Name string

+ Parameters []ParameterConfig

+ SafeForParallel bool

+ Timeout time.Duration

+ type ToolHandler func(ctx context.Context, args map[string]interface{}) (string, error)

+ type ToolHandlerWithImages func(ctx context.Context, args map[string]interface{}) ([]ImageData, string, error)

+ type ToolRegistry struct

+ PostExecuteHook func(name string, result string) string

+ PreExecuteHook func(name string, args map[string]interface{}) error

+ func NewToolRegistry(opts ToolRegistryOptions) *ToolRegistry

+ func (r *ToolRegistry) Execute(ctx context.Context, calls []ToolCall) []Message

+ func (r *ToolRegistry) GetTool(name string) *Tool

+ func (r *ToolRegistry) GetTools() []Tool

+ func (r *ToolRegistry) HasTool(name string) bool

+ func (r *ToolRegistry) Register(config ToolConfig) error

+ func (r *ToolRegistry) RegisterAll(configs []ToolConfig) error

+ func (r *ToolRegistry) ToolNames() []string

+ func (r *ToolRegistry) Unregister(name string) bool

+ type ToolRegistryOptions struct

+ CircuitBreakerThreshold int

+ CircuitBreakerTimeout time.Duration

+ DefaultTimeout time.Duration

+ EventPublisher EventPublisher

+ MaxResultSize int

+ PostExecuteHook func(name string, result string) string

+ PreExecuteHook func(name string, args map[string]interface{}) error

May 13, 2026

Changes in this version

type Options

+ InitialMessages []Message

+ MaxTokens int

May 12, 2026

Changes in this version

type ChatResponse

+ Created int64

+ Object string

type ChatUsage

+ CacheWriteTokens *int

+ CachedTokens int

May 12, 2026

Changes in this version

+ func IsBlankResponse(err error) bool

+ func IsContentFiltered(err error) bool

+ type BlankResponseError struct

+ Count int

+ Provider string

+ func (e *BlankResponseError) Error() string

type ChatRequest

+ Model string

+ Reasoning string

+ Stream bool

+ ToolChoice string

type ChatUsage

+ Cost float64

+ EstimatedCost float64

+ type ContentFilteredError struct

+ Provider string

+ func (e *ContentFilteredError) Error() string

type ImageData

+ Base64 string

+ Type string

type Message

+ ReasoningContent string

type Tool

+ Function ToolFunction

+ Type string

+ type ToolFunction struct

+ Description string

+ Name string

+ Parameters ToolParameters

May 12, 2026

Changes in this version

+ const DefaultSystemPrompt

+ const EventTypeCompaction

+ const EventTypeError

+ const EventTypeMetricsUpdate

+ const EventTypeQueryCompleted

+ const EventTypeQueryStarted

+ const EventTypeStreamChunk

+ const EventTypeToolEnd

+ const EventTypeToolStart

+ var ErrInterrupted = errors.New("conversation interrupted")

+ var ErrMaxIterations = errors.New("maximum iterations exceeded")

+ var ErrNoExecutor = errors.New("no tool executor configured")

+ var ErrNoProvider = errors.New("no provider configured")

+ var ErrPaused = errors.New("agent is paused")

+ func BuildCheckpointCompactedMessages(messages []Message, checkpoints []TurnCheckpoint) ([]Message, []TurnCheckpoint)

+ func ClassifyError(err error, provider string) error

+ func IsAuthError(err error) bool

+ func IsContextOverflow(err error) bool

+ func IsRateLimit(err error) bool

+ func IsTransient(err error) bool

+ func RecordTurnCheckpointAsync(state *State, messages []Message, startIndex, endIndex int, ...)

+ type Agent struct

+ func NewAgent(opts Options) (*Agent, error)

+ func (a *Agent) ExportState() ([]byte, error)

+ func (a *Agent) ImportState(data []byte) error

+ func (a *Agent) InjectInput(input string) bool

+ func (a *Agent) IsPaused() bool

+ func (a *Agent) Pause()

+ func (a *Agent) Provider() Provider

+ func (a *Agent) ReasoningBuffer() *StreamingBuffer

+ func (a *Agent) Resume()

+ func (a *Agent) Run(ctx context.Context, query string) (string, error)

+ func (a *Agent) RunStream(ctx context.Context, query string) (string, error)

+ func (a *Agent) SetFlushCallback(fn func())

+ func (a *Agent) SetProvider(p Provider)

+ func (a *Agent) SetSystemPrompt(prompt string)

+ func (a *Agent) State() *State

+ func (a *Agent) Steer(msg Message)

+ func (a *Agent) SteerSystem(content string)

+ func (a *Agent) StreamingBuffer() *StreamingBuffer

+ type AgentState struct

+ Checkpoints []TurnCheckpoint

+ CompletionTokens int

+ Messages []Message

+ PromptTokens int

+ SessionID string

+ TotalCost float64

+ TotalTokens int

+ type AgentStreamHandler struct

+ func NewAgentStreamHandler(agent *Agent, state *State) *AgentStreamHandler

+ func (h *AgentStreamHandler) OnContent(content string)

+ func (h *AgentStreamHandler) OnDone(resp *ChatResponse)

+ func (h *AgentStreamHandler) OnError(err error)

+ func (h *AgentStreamHandler) OnReasoning(reasoning string)

+ func (h *AgentStreamHandler) Response() *ChatResponse

+ type AuthError struct

+ Provider string

+ Wrapped error

+ func (e *AuthError) Error() string

+ func (e *AuthError) Unwrap() error

+ type ChatChoice struct

+ FinishReason string

+ Index int

+ Message Message

+ type ChatRequest struct

+ MaxTokens int

+ Messages []Message

+ Temperature float64

+ Tools []Tool

+ type ChatResponse struct

+ Choices []ChatChoice

+ ID string

+ Model string

+ Usage ChatUsage

+ func (r ChatResponse) ToMessage() Message

+ type ChatUsage struct

+ CompletionTokens int

+ PromptTokens int

+ TotalTokens int

+ type CompactionResult struct

+ Messages []Message

+ Strategy string

+ TokensAfter int

+ TokensBefore int

+ func (r CompactionResult) MessageCountDelta(before int) int

+ func (r CompactionResult) TokensSaved() int

+ type Compactor struct

+ func NewCompactor() *Compactor

+ func (c *Compactor) Compact(messages []Message, tokenLimit int) CompactionResult

+ type ContextOverflowError struct

+ TokensLimit int

+ TokensUsed int

+ Wrapped error

+ func (e *ContextOverflowError) Error() string

+ func (e *ContextOverflowError) Unwrap() error

+ type ConversationHandler struct

+ func (ch *ConversationHandler) ProcessQuery(ctx context.Context, query string) (string, error)

+ func (ch *ConversationHandler) ProcessQueryStream(ctx context.Context, query string) (string, error)

+ type ConversationOptimizer struct

+ func NewConversationOptimizer(opts ConversationOptimizerOptions) *ConversationOptimizer

+ func (opt *ConversationOptimizer) OptimizeConversation(messages []Message) []Message

+ type ConversationOptimizerOptions struct

+ Enabled bool

+ KnownToolFn func(name string) ToolCategory

+ type EventPublisher interface

+ Publish func(eventType string, data any)

+ type ExponentialBackoff struct

+ InitialDelay time.Duration

+ Jitter float64

+ MaxAttempts int

+ MaxDelay time.Duration

+ Multiplier float64

+ func NewExponentialBackoff(initialDelay, maxDelay time.Duration, multiplier float64, maxAttempts int, ...) *ExponentialBackoff

+ func (b *ExponentialBackoff) Delay() time.Duration

+ func (b *ExponentialBackoff) NextAttempt() bool

+ func (b *ExponentialBackoff) Reset()

+ func (b *ExponentialBackoff) WithRand(rs randSource) *ExponentialBackoff

+ type FallbackParseResult struct

+ CleanedContent string

+ ToolCalls []ToolCall

+ type FallbackParser struct

+ func NewFallbackParser(opts FallbackParserOptions) *FallbackParser

+ func (fp *FallbackParser) Parse(content string) *FallbackParseResult

+ func (fp *FallbackParser) ShouldUseFallback(content string, hasStructuredToolCalls bool) bool

+ type FallbackParserOptions struct

+ Debug bool

+ KnownToolNames func(string) bool

+ type ImageData struct

+ Data []byte

+ MIMEType string

+ URL string

+ type Message struct

+ Content string

+ Images []ImageData

+ Role string

+ ToolCallID string

+ ToolCalls []ToolCall

+ type NormalizedToolCalls []ToolCall

+ type Options struct

+ Debug bool

+ DisableFallbackParser bool

+ DisableNormalizer bool

+ DisableValidator bool

+ EventPublisher EventPublisher

+ Executor ToolExecutor

+ MaxIterations int

+ OnIteration func(iteration int, messages int)

+ Optimizer *ConversationOptimizer

+ Provider Provider

+ RetryConfig RetryConfig

+ SystemPrompt string

+ UI UI

+ type OutputEvent struct

+ Content string

+ Metadata map[string]string

+ Source string

+ Timestamp time.Time

+ Type string

+ type OutputManager interface

+ AsyncOutput func() <-chan OutputEvent

+ Close func()

+ ContentBuffer func() *StreamingBuffer

+ Flush func()

+ GetEventMetadata func(key string) string

+ PublishOutput func(event OutputEvent)

+ ReasoningBuffer func() *StreamingBuffer

+ Reset func()

+ SetEventMetadata func(key string, value string)

+ SetFlushCallback func(fn func())

+ func NewOutputManager(eventBus EventPublisher) OutputManager

+ type Provider interface

+ Chat func(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

+ ChatStream func(ctx context.Context, req *ChatRequest, handler StreamHandler) error

+ EstimateTokens func(req *ChatRequest) int

+ Info func() ProviderInfo

+ type ProviderInfo struct

+ ContextSize int

+ HasVision bool

+ Model string

+ type RateLimitError struct

+ Attempt int

+ Provider string

+ RetryAfter time.Duration

+ Wrapped error

+ func (e *RateLimitError) Error() string

+ func (e *RateLimitError) Unwrap() error

+ type ResponseValidator struct

+ func NewResponseValidator(opts ResponseValidatorOptions) *ResponseValidator

+ func (rv *ResponseValidator) IsIncomplete(content string) bool

+ func (rv *ResponseValidator) LooksLikeTentativePostToolResponse(content string) bool

+ func (rv *ResponseValidator) LooksTruncated(content string) bool

+ type ResponseValidatorOptions struct

+ DebugLog func(format string, args ...interface{})

+ type RetryConfig struct

+ InitialDelay time.Duration

+ Jitter float64

+ MaxAttempts int

+ MaxDelay time.Duration

+ Multiplier float64

+ func (rc RetryConfig) InitialDelayOrDefault() time.Duration

+ func (rc RetryConfig) JitterOrDefault() float64

+ func (rc RetryConfig) MaxAttemptsOrDefault() int

+ func (rc RetryConfig) MaxDelayOrDefault() time.Duration

+ func (rc RetryConfig) MultiplierOrDefault() float64

+ type State struct

+ func NewState() *State

+ func (s *State) AddCheckpoint(cp TurnCheckpoint)

+ func (s *State) AddCost(cost float64)

+ func (s *State) AddMessage(msg Message)

+ func (s *State) AddTokens(prompt, completion, total int)

+ func (s *State) ClearCheckpoints()

+ func (s *State) EnsureSessionID()

+ func (s *State) ExportState() ([]byte, error)

+ func (s *State) GetCheckpoints() []TurnCheckpoint

+ func (s *State) ImportState(data []byte) error

+ func (s *State) LastAssistantMessage() *Message

+ func (s *State) Len() int

+ func (s *State) Messages() []Message

+ func (s *State) SessionID() string

+ func (s *State) SetCheckpoints(cps []TurnCheckpoint)

+ func (s *State) SetMessages(msgs []Message)

+ func (s *State) SetSessionID(id string)

+ func (s *State) TotalCost() float64

+ func (s *State) TotalTokens() int

+ type StreamHandler interface

+ OnContent func(content string)

+ OnDone func(resp *ChatResponse)

+ OnError func(err error)

+ OnReasoning func(reasoning string)

+ type StreamingBuffer struct

+ func NewStreamingBuffer() *StreamingBuffer

+ func (b *StreamingBuffer) Len() int

+ func (b *StreamingBuffer) Reset()

+ func (b *StreamingBuffer) String() string

+ func (b *StreamingBuffer) Write(p []byte) (int, error)

+ type Tool struct

+ Description string

+ Name string

+ Parameters ToolParameters

+ type ToolCall struct

+ Function ToolCallFunction

+ ID string

+ Type string

+ type ToolCallFunction struct

+ Arguments string

+ Name string

+ type ToolCallNormalizer struct

+ func NewToolCallNormalizer() *ToolCallNormalizer

+ func (n *ToolCallNormalizer) Normalize(calls []ToolCall) NormalizedToolCalls

+ type ToolCategory int

+ const ToolCategoryFileRead

+ const ToolCategoryShellCommand

+ const ToolCategoryUnknown

+ type ToolExecutor interface

+ Execute func(ctx context.Context, calls []ToolCall) []Message

+ GetTools func() []Tool

+ var NoopExecutor ToolExecutor = &noopExecutor{}

+ type ToolParameter struct

+ Description string

+ Type string

+ type ToolParameters struct

+ Properties map[string]ToolParameter

+ Required []string

+ Type string

+ type TransientError struct

+ Op string

+ Provider string

+ RetryAfter time.Duration

+ Wrapped error

+ func (e *TransientError) Error() string

+ func (e *TransientError) Unwrap() error

+ type TurnCheckpoint struct

+ ActionableSummary string

+ EndIndex int

+ StartIndex int

+ Summary string

+ func BuildCheckpointSummary(messages []Message) TurnCheckpoint

+ func ShiftCheckpointIndices(oldMessages, newMessages []Message, checkpoints []TurnCheckpoint) []TurnCheckpoint

+ type TurnSummaryBuilder struct

+ KnownErrorPatterns []string

+ KnownFileTools map[string]bool

+ KnownShellTools map[string]bool

+ func NewTurnSummaryBuilder() *TurnSummaryBuilder

+ func (b *TurnSummaryBuilder) Build(messages []Message) TurnCheckpoint

+ type UI interface

+ Confirm func(message string) (bool, error)

+ Print func(message string)

+ PrintLine func(message string)

+ Prompt func(message string) (string, error)

+ var NoopUI UI = &noopUI{}