utils

Documentation

Overview

Package utils provides common utility functions used across the codebase.

This package contains shared helper functions that are used by multiple packages to avoid code duplication. Functions here are generally simple, stateless utilities that don't fit into more specific packages.

Index

• func CalculateTotalTokens(inputTokens, outputTokens int) int
• func Clamp(value, min, max int) int
• func ClampFloat64(value, min, max float64) float64
• func CloneInput(input map[string]any) map[string]any
• func CloneMap[K comparable, V any](input map[K]V) map[K]V
• func CloneSlice[T any](input []T) []T
• func CountTokensInText(text string) int
• func DirIsInGitRepo(cwd string) bool
• func EstimateImageTokens() int
• func FindCanonicalGitRoot(startDir string) string
• func FindGitRoot(startDir string) string
• func GetCachedBranch(root string) string
• func GetCachedDefaultBranch(root string) string
• func GetCachedHead(root string) string
• func GetCachedRemoteUrl(root string) string
• func GetGitExe() string
• func GetIsGit(dir string) bool
• func IsAtGitRoot(cwd string) bool
• func IsValidToolName(name string) bool
• func ReadGitHead(gitDir string) (string, bool)
• func ResolveGitDir(startDir string) string
• func SanitizePathComponent(path string) string
• func ValidateMessageID(id string) error
• func ValidateModelIdentifier(model string) error
• func ValidateSessionID(id string) error
• func ValidateTurnID(id string) error
• type Context
  • func Detect(dir string) *Context
• type ContextManager
  • func NewContextManager() *ContextManager
  • func (m *ContextManager) CalculateCompactionTarget(contextWindow types.ContextWindow, systemPrompt string, ...) int
  • func (m *ContextManager) CalculateMessageTokens(msg types.Message) int
  • func (m *ContextManager) CalculateMessagesTokens(messages []types.Message) int
  • func (m *ContextManager) CalculateRemainingTokens(contextWindow types.ContextWindow, systemPrompt string, ...) int
  • func (m *ContextManager) CalculateSystemPromptTokens(systemPrompt string) int
  • func (m *ContextManager) EstimateRequestTokens(systemPrompt string, messages []types.Message) int
  • func (m *ContextManager) ShouldCompact(contextWindow types.ContextWindow, systemPrompt string, ...) bool
• type LRUCache
  • func (c *LRUCache) Get(key string) (string, bool)
  • func (c *LRUCache) Set(key string, root string, found bool)
• type PathValidator
  • func NewPathValidator(allowedDirs []string) *PathValidator
  • func (v *PathValidator) ValidatePath(path string) error
• type TokenEstimator
  • func NewTokenEstimator() *TokenEstimator
  • func (e *TokenEstimator) EstimateMessageTokens(role string, content string) int
  • func (e *TokenEstimator) EstimateTokens(text string) int
  • func (e *TokenEstimator) EstimateToolResultTokens(result string) int
  • func (e *TokenEstimator) EstimateToolUseTokens(toolName string, input map[string]any) int

Functions

func CalculateTotalTokens

func CalculateTotalTokens(inputTokens, outputTokens int) int

CalculateTotalTokens calculates total tokens from usage

func Clamp

func Clamp(value, min, max int) int

Clamp clamps a value between min and max

func ClampFloat64

func ClampFloat64(value, min, max float64) float64

ClampFloat64 clamps a float64 value between min and max

func CloneInput

func CloneInput(input map[string]any) map[string]any

CloneInput creates a shallow copy of a map[string]any. This is used to prevent mutation of original input during processing. Returns nil if input is nil.

func CloneMap

func CloneMap[K comparable, V any](input map[K]V) map[K]V

CloneMap creates a shallow copy of a generic map. Returns nil if input is nil.

func CloneSlice

func CloneSlice[T any](input []T) []T

CloneSlice creates a shallow copy of a slice. Returns nil if input is nil.

func CountTokensInText

func CountTokensInText(text string) int

CountTokensInText counts tokens in text (alias for EstimateTokens)

func DirIsInGitRepo

func DirIsInGitRepo(cwd string) bool

func EstimateImageTokens

func EstimateImageTokens() int

EstimateImageTokens estimates tokens for an image Based on Anthropic's pricing: each image costs a fixed number of tokens

func FindCanonicalGitRoot

func FindCanonicalGitRoot(startDir string) string

func FindGitRoot

func FindGitRoot(startDir string) string

func GetCachedBranch

func GetCachedBranch(root string) string

func GetCachedDefaultBranch

func GetCachedDefaultBranch(root string) string

func GetCachedHead

func GetCachedHead(root string) string

func GetCachedRemoteUrl

func GetCachedRemoteUrl(root string) string

func GetGitExe

func GetGitExe() string

func GetIsGit

func GetIsGit(dir string) bool

func IsAtGitRoot

func IsAtGitRoot(cwd string) bool

func IsValidToolName

func IsValidToolName(name string) bool

IsValidToolName validates a tool name

func ReadGitHead

func ReadGitHead(gitDir string) (string, bool)

func ResolveGitDir

func ResolveGitDir(startDir string) string

func SanitizePathComponent

func SanitizePathComponent(path string) string

SanitizePathComponent sanitizes a path component for use in filenames

func ValidateMessageID

func ValidateMessageID(id string) error

ValidateMessageID validates a message ID format

func ValidateModelIdentifier

func ValidateModelIdentifier(model string) error

ValidateModelIdentifier validates a model identifier

func ValidateSessionID

func ValidateSessionID(id string) error

ValidateSessionID validates a session ID format

func ValidateTurnID

func ValidateTurnID(id string) error

ValidateTurnID validates a turn ID format

Types

type Context

type Context struct {
	Root       string
	Branch     string
	Head       string
	IsGit      bool
	IsWorktree bool
}

func Detect

func Detect(dir string) *Context

type ContextManager

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

ContextManager manages context window limits

func NewContextManager

func NewContextManager() *ContextManager

NewContextManager creates a new context manager

func (*ContextManager) CalculateCompactionTarget

func (m *ContextManager) CalculateCompactionTarget(
	contextWindow types.ContextWindow,
	systemPrompt string,
	messages []types.Message,
	targetPercentage float64,
) int

CalculateCompactionTarget calculates how many tokens need to be removed

func (*ContextManager) CalculateMessageTokens

func (m *ContextManager) CalculateMessageTokens(msg types.Message) int

CalculateMessageTokens calculates tokens for a message

func (*ContextManager) CalculateMessagesTokens

func (m *ContextManager) CalculateMessagesTokens(messages []types.Message) int

CalculateMessagesTokens calculates total tokens for a list of messages

func (*ContextManager) CalculateRemainingTokens

func (m *ContextManager) CalculateRemainingTokens(
	contextWindow types.ContextWindow,
	systemPrompt string,
	messages []types.Message,
) int

CalculateRemainingTokens calculates remaining tokens before hitting the limit

func (*ContextManager) CalculateSystemPromptTokens

func (m *ContextManager) CalculateSystemPromptTokens(systemPrompt string) int

CalculateSystemPromptTokens calculates tokens for the system prompt

func (*ContextManager) EstimateRequestTokens

func (m *ContextManager) EstimateRequestTokens(
	systemPrompt string,
	messages []types.Message,
) int

EstimateRequestTokens estimates total tokens for an API request

func (*ContextManager) ShouldCompact

func (m *ContextManager) ShouldCompact(
	contextWindow types.ContextWindow,
	systemPrompt string,
	messages []types.Message,
	threshold float64,
) bool

ShouldCompact returns true if compaction is needed

type LRUCache

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

func (*LRUCache) Get

func (c *LRUCache) Get(key string) (string, bool)

func (*LRUCache) Set

func (c *LRUCache) Set(key string, root string, found bool)

type PathValidator

type PathValidator struct {
	// AllowedDirectories are the only directories that can be accessed
	AllowedDirectories []string
}

PathValidator validates and sanitizes file paths

func NewPathValidator

func NewPathValidator(allowedDirs []string) *PathValidator

NewPathValidator creates a new path validator

func (*PathValidator) ValidatePath

func (v *PathValidator) ValidatePath(path string) error

ValidatePath validates that a path is within allowed directories

type TokenEstimator

type TokenEstimator struct {
	// CharactersPerToken is the average characters per token
	CharactersPerToken float64
}

TokenEstimator estimates token counts for text

func NewTokenEstimator

func NewTokenEstimator() *TokenEstimator

NewTokenEstimator creates a new token estimator

func (*TokenEstimator) EstimateMessageTokens

func (e *TokenEstimator) EstimateMessageTokens(role string, content string) int

EstimateMessageTokens estimates tokens in a message

func (*TokenEstimator) EstimateTokens

func (e *TokenEstimator) EstimateTokens(text string) int

EstimateTokens estimates the number of tokens in a string

func (*TokenEstimator) EstimateToolResultTokens

func (e *TokenEstimator) EstimateToolResultTokens(result string) int

EstimateToolResultTokens estimates tokens for a tool result

func (*TokenEstimator) EstimateToolUseTokens

func (e *TokenEstimator) EstimateToolUseTokens(toolName string, input map[string]any) int

EstimateToolUseTokens estimates tokens for a tool use