runtime

package
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// CharsPerTokenEstimate approximates token->char conversion for pruning heuristics.
	CharsPerTokenEstimate = 4
	// ImageCharEstimate approximates image token cost for mixed multimodal prompts.
	ImageCharEstimate = 8000
)
View Source 
const (
	DefaultQueueDebounceMs = 1000
	DefaultQueueCap        = 20
	DefaultQueueDrop       = QueueDropSummarize
	DefaultQueueMode       = QueueModeCollect
)
View Source 
const SilentReplyToken = "NO_REPLY"

Variables

This section is empty.

Functions

func BuildInboundMetaSystemPrompt 

func BuildInboundMetaSystemPrompt(ctx InboundContext) string

func BuildInboundUserContextPrefix 

func BuildInboundUserContextPrefix(ctx InboundContext) string

func BuildQueueSummaryLine 

func BuildQueueSummaryLine(text string, limit int) string

BuildQueueSummaryLine collapses whitespace and elides text to the given limit.

func BuildToolPrunablePredicate 

func BuildToolPrunablePredicate(config *PruningConfig) func(toolName string) bool

BuildToolPrunablePredicate creates a predicate for tool pruning allow/deny lists.

func ContainsMessageIDHint 

func ContainsMessageIDHint(value string) bool

func ElideQueueText 

func ElideQueueText(text string, limit int) string

ElideQueueText truncates text to the given character limit with an ellipsis.

func EstimateMessageChars 

func EstimateMessageChars(msg openai.ChatCompletionMessageParamUnion) int

EstimateMessageChars approximates character usage for one prompt message.

func ExtractAssistantContent 

func ExtractAssistantContent(content openai.ChatCompletionAssistantMessageParamContentUnion) string

func ExtractDeveloperContent 

func ExtractDeveloperContent(content openai.ChatCompletionDeveloperMessageParamContentUnion) string

func ExtractMessageContent 

func ExtractMessageContent(msg openai.ChatCompletionMessageParamUnion) (content, role string)

ExtractMessageContent extracts text content and role from a chat message.

func ExtractSystemContent 

func ExtractSystemContent(content openai.ChatCompletionSystemMessageParamContentUnion) string

func ExtractToolContent 

func ExtractToolContent(content openai.ChatCompletionToolMessageParamContentUnion) string

func ExtractUserContent 

func ExtractUserContent(content openai.ChatCompletionUserMessageParamContentUnion) string

func HasRenderableStreamingContent 

func HasRenderableStreamingContent(result *StreamingDirectiveResult) bool

HasRenderableStreamingContent checks whether a streaming result has text or audio to render.

func IsAbortTriggerText 

func IsAbortTriggerText(text string) bool

func IsSilentReplyPrefixText 

func IsSilentReplyPrefixText(text, token string) bool

IsSilentReplyPrefixText checks whether text is a partial-typing prefix of the silent token (e.g. "NO_RE" for "NO_REPLY"), used during streaming to detect silent replies early.

func IsSilentReplyText 

func IsSilentReplyText(text, token string) bool

IsSilentReplyText checks whether text is exactly the silent reply token (modulo whitespace).

func LimitHistoryTurns 

func LimitHistoryTurns(prompt []openai.ChatCompletionMessageParamUnion, limit int) []openai.ChatCompletionMessageParamUnion

LimitHistoryTurns keeps only the last N user turns plus required preamble.

func NormalizeHintMessageID 

func NormalizeHintMessageID(value string) string

func NormalizeInboundTextNewlines 

func NormalizeInboundTextNewlines(input string) string

NormalizeInboundTextNewlines converts all line endings to \n.

func NormalizeMessageID 

func NormalizeMessageID(value string) string

func PromptTextPayloads 

func PromptTextPayloads(prompt []openai.ChatCompletionMessageParamUnion) ([]string, int)

PromptTextPayloads extracts plain-text payloads from prompt messages for compaction heuristics.

func PruneContext 

func PruneContext(
	prompt []openai.ChatCompletionMessageParamUnion,
	config *PruningConfig,
	contextWindowTokens int,
) []openai.ChatCompletionMessageParamUnion

PruneContext applies proactive context pruning.

func ResolveQueueThreadKey 

func ResolveQueueThreadKey(mode ThreadReplyMode, threadRootID, eventID string) string

func SanitizeChatMessageForDisplay 

func SanitizeChatMessageForDisplay(text string, isUser bool) string

func SmartTruncatePrompt 

func SmartTruncatePrompt(prompt []openai.ChatCompletionMessageParamUnion, targetReduction float64) []openai.ChatCompletionMessageParamUnion

SmartTruncatePrompt is the reactive fallback for context overflow retries.

func SoftTrimToolResult 

func SoftTrimToolResult(content string, config *PruningConfig) string

SoftTrimToolResult truncates a large tool result while preserving head/tail context.

func SplitTrailingDirective 

func SplitTrailingDirective(text string) (string, string)

SplitTrailingDirective splits text at the last unclosed [[ directive tag, returning the body before and the incomplete tag after.

func StripEnvelope 

func StripEnvelope(text string) string

func StripMessageIDHintLines 

func StripMessageIDHintLines(text string) string

Types

type CompactionDecision 

type CompactionDecision struct {
	Applied       bool
	DroppedCount  int
	OriginalChars int
	FinalChars    int
	Reason        string
}

CompactionDecision captures deterministic compaction outcomes for observability.

type CompactionInput 

type CompactionInput struct {
	Messages      []string
	MaxChars      int
	ProtectedTail int
}

CompactionInput describes text-level compaction parameters.

type CompactionResult 

type CompactionResult struct {
	Messages []string
	Decision CompactionDecision
}

CompactionResult holds the outcome of a text-level compaction pass.

func ApplyCompaction 

func ApplyCompaction(input CompactionInput) CompactionResult

ApplyCompaction drops oldest messages until the total character count fits within budget, while respecting the protected tail window.

type FailureClass 

type FailureClass string

FailureClass groups error types for fallback and UX handling. 

const (
	FailureClassUnknown         FailureClass = "unknown"
	FailureClassAuth            FailureClass = "auth"
	FailureClassRateLimit       FailureClass = "rate_limit"
	FailureClassTimeout         FailureClass = "timeout"
	FailureClassNetwork         FailureClass = "network"
	FailureClassContextOverflow FailureClass = "context_overflow"
	FailureClassProviderHard    FailureClass = "provider_hard"
)

func ClassifyFallbackError 

func ClassifyFallbackError(err error) FailureClass

type FallbackAction 

type FallbackAction string

FallbackAction is the runtime-prescribed fallback handling mode. 

const (
	FallbackActionNone      FallbackAction = "none"
	FallbackActionRetry     FallbackAction = "retry"
	FallbackActionFailover  FallbackAction = "failover"
	FallbackActionTrimRetry FallbackAction = "trim_retry"
	FallbackActionAbort     FallbackAction = "abort"
)

type FallbackDecision 

type FallbackDecision struct {
	Class       FailureClass
	Action      FallbackAction
	Reason      string
	StatusText  string
	ShouldRetry bool
}

FallbackDecision standardizes fallback behavior and UX copy.

func DecideFallback 

func DecideFallback(err error) FallbackDecision

DecideFallback converts raw errors into runtime-standard retry/failover behavior.

type InboundContext 

type InboundContext struct {
	Provider          string
	Surface           string
	ChatType          string
	ChatID            string
	ConversationLabel string
	SenderLabel       string
	SenderID          string
	MessageID         string
	MessageIDFull     string
	ReplyToID         string
	ThreadID          string
	Body              string
	BodyForAgent      string
	BodyForCommands   string
	RawBody           string
	ThreadStarterBody string
	CommandAuthorized bool
	MediaURLs         []string
	MediaTypes        []string
	TimestampMs       int64
}

InboundContext is the canonical normalized inbound payload used by runtime modules.

func FinalizeInboundContext 

func FinalizeInboundContext(ctx InboundContext) InboundContext

FinalizeInboundContext normalizes an InboundContext by trimming fields, normalizing newlines, and filling in body fallbacks.

type InlineDirectiveParseOptions 

type InlineDirectiveParseOptions struct {
	CurrentMessageID    string
	StripAudioTag       bool
	StripReplyTags      bool
	NormalizeWhitespace bool
	SilentToken         string
}

type InlineDirectiveParseResult 

type InlineDirectiveParseResult struct {
	Text              string
	AudioAsVoice      bool
	ReplyToID         string
	ReplyToExplicitID string
	ReplyToCurrent    bool
	HasAudioTag       bool
	HasReplyTag       bool
	IsSilent          bool
}

func ParseInlineDirectives 

func ParseInlineDirectives(text string, options InlineDirectiveParseOptions) InlineDirectiveParseResult

type OverflowCompactionInput 

type OverflowCompactionInput struct {
	Prompt              []openai.ChatCompletionMessageParamUnion
	ContextWindowTokens int
	RequestedTokens     int
	CurrentPromptTokens int
	ReserveTokens       int
	KeepRecentTokens    int
	CompactionMode      string
	Summarization       bool
	MaxSummaryTokens    int
	RefreshPrompt       string
	MaxHistoryShare     float64
	ProtectedTail       int
}

type OverflowCompactionResult 

type OverflowCompactionResult struct {
	Prompt   []openai.ChatCompletionMessageParamUnion
	Decision CompactionDecision
	Success  bool
}

func CompactPromptOnOverflow 

func CompactPromptOnOverflow(input OverflowCompactionInput) OverflowCompactionResult

CompactPromptOnOverflow applies deterministic compaction + smart truncation for overflow retries.

type OverflowFlushConfig 

type OverflowFlushConfig struct {
	Enabled             *bool  `yaml:"enabled" json:"enabled,omitempty"`
	SoftThresholdTokens int    `yaml:"soft_threshold_tokens" json:"soft_threshold_tokens,omitempty"`
	Prompt              string `yaml:"prompt" json:"prompt,omitempty"`
	SystemPrompt        string `yaml:"system_prompt" json:"system_prompt,omitempty"`
}

OverflowFlushConfig configures pre-compaction flush behavior.

type PruningConfig 

type PruningConfig struct {
	Mode string        `yaml:"mode" json:"mode,omitempty"`
	TTL  time.Duration `yaml:"ttl" json:"ttl,omitempty"`

	Enabled bool `yaml:"enabled" json:"enabled"`

	SoftTrimRatio  float64 `yaml:"soft_trim_ratio" json:"soft_trim_ratio,omitempty"`
	HardClearRatio float64 `yaml:"hard_clear_ratio" json:"hard_clear_ratio,omitempty"`

	KeepLastAssistants int `yaml:"keep_last_assistants" json:"keep_last_assistants,omitempty"`
	MinPrunableChars   int `yaml:"min_prunable_chars" json:"min_prunable_chars,omitempty"`
	SoftTrimMaxChars   int `yaml:"soft_trim_max_chars" json:"soft_trim_max_chars,omitempty"`
	SoftTrimHeadChars  int `yaml:"soft_trim_head_chars" json:"soft_trim_head_chars,omitempty"`
	SoftTrimTailChars  int `yaml:"soft_trim_tail_chars" json:"soft_trim_tail_chars,omitempty"`

	HardClearEnabled     *bool  `yaml:"hard_clear_enabled" json:"hard_clear_enabled,omitempty"`
	HardClearPlaceholder string `yaml:"hard_clear_placeholder" json:"hard_clear_placeholder,omitempty"`

	ToolsAllow []string `yaml:"tools_allow" json:"tools_allow,omitempty"`
	ToolsDeny  []string `yaml:"tools_deny" json:"tools_deny,omitempty"`

	SummarizationEnabled   *bool                `yaml:"summarization_enabled" json:"summarization_enabled,omitempty"`
	SummarizationModel     string               `yaml:"summarization_model" json:"summarization_model,omitempty"`
	MaxSummaryTokens       int                  `yaml:"max_summary_tokens" json:"max_summary_tokens,omitempty"`
	CompactionMode         string               `yaml:"compaction_mode" json:"compaction_mode,omitempty"`
	KeepRecentTokens       int                  `yaml:"keep_recent_tokens" json:"keep_recent_tokens,omitempty"`
	MaxHistoryShare        float64              `yaml:"max_history_share" json:"max_history_share,omitempty"`
	ReserveTokens          int                  `yaml:"reserve_tokens" json:"reserve_tokens,omitempty"`
	ReserveTokensFloor     int                  `yaml:"reserve_tokens_floor" json:"reserve_tokens_floor,omitempty"`
	CustomInstructions     string               `yaml:"custom_instructions" json:"custom_instructions,omitempty"`
	IdentifierPolicy       string               `yaml:"identifier_policy" json:"identifier_policy,omitempty"`
	IdentifierInstructions string               `yaml:"identifier_instructions" json:"identifier_instructions,omitempty"`
	PostCompactionRefresh  string               `yaml:"post_compaction_refresh_prompt" json:"post_compaction_refresh_prompt,omitempty"`
	OverflowFlush          *OverflowFlushConfig `yaml:"overflow_flush" json:"overflow_flush,omitempty"`

	MaxHistoryTurns int `yaml:"max_history_turns" json:"max_history_turns,omitempty"`
}

PruningConfig configures context pruning behavior (OpenClaw-style).

func ApplyPruningDefaults 

func ApplyPruningDefaults(config *PruningConfig) *PruningConfig

ApplyPruningDefaults fills in missing pruning config values.

func DefaultPruningConfig 

func DefaultPruningConfig() *PruningConfig

DefaultPruningConfig returns OpenClaw-like default settings.

type QueueBehavior 

type QueueBehavior struct {
	Steer        bool
	Followup     bool
	Collect      bool
	BacklogAfter bool
}

QueueBehavior controls steer/followup/collect semantics.

func ResolveQueueBehavior 

func ResolveQueueBehavior(mode QueueMode) QueueBehavior

type QueueDecision 

type QueueDecision struct {
	Action QueueDecisionAction
	Reason string
}

QueueDecision is a deterministic decision output for queue handling.

func DecideQueueAction 

func DecideQueueAction(mode QueueMode, hasActiveRun bool, isHeartbeat bool) QueueDecision

type QueueDecisionAction 

type QueueDecisionAction string

QueueDecisionAction is the runtime's final queue decision. 

const (
	QueueActionRunNow          QueueDecisionAction = "run_now"
	QueueActionEnqueue         QueueDecisionAction = "enqueue"
	QueueActionDrop            QueueDecisionAction = "drop"
	QueueActionInterruptAndRun QueueDecisionAction = "interrupt_and_run"
)

type QueueDropPolicy 

type QueueDropPolicy string

QueueDropPolicy controls overflow behavior for queued messages. 

const (
	QueueDropOld       QueueDropPolicy = "old"
	QueueDropNew       QueueDropPolicy = "new"
	QueueDropSummarize QueueDropPolicy = "summarize"
)

func NormalizeQueueDropPolicy 

func NormalizeQueueDropPolicy(raw string) (QueueDropPolicy, bool)

type QueueInlineOptions 

type QueueInlineOptions struct {
	DebounceMs *int
	Cap        *int
	DropPolicy *QueueDropPolicy
}

QueueInlineOptions carries per-message queue overrides.

type QueueMode 

type QueueMode string

QueueMode models OpenClaw-like queue behavior presets. 

const (
	QueueModeInterrupt    QueueMode = "interrupt"
	QueueModeBacklog      QueueMode = "backlog"
	QueueModeSteer        QueueMode = "steer"
	QueueModeFollowup     QueueMode = "followup"
	QueueModeCollect      QueueMode = "collect"
	QueueModeSteerBacklog QueueMode = "steer-backlog"
)

func NormalizeQueueMode 

func NormalizeQueueMode(raw string) (QueueMode, bool)

type QueueOverflowResult 

type QueueOverflowResult struct {
	KeepNew         bool
	ItemsToDrop     int
	ShouldSummarize bool
}

func ResolveQueueOverflow 

func ResolveQueueOverflow(capacity int, currentLen int, policy QueueDropPolicy) QueueOverflowResult

type QueueSettings 

type QueueSettings struct {
	Mode       QueueMode
	DebounceMs int
	Cap        int
	DropPolicy QueueDropPolicy
}

QueueSettings is the canonical runtime queue configuration.

type ReplyDirectiveResult 

type ReplyDirectiveResult struct {
	Text              string
	ReplyToID         string
	ReplyToExplicitID string
	ReplyToCurrent    bool
	HasReplyTag       bool
	AudioAsVoice      bool
	IsSilent          bool
}

ReplyDirectiveResult describes parsed reply/silent/audio directives.

func ParseReplyDirectives 

func ParseReplyDirectives(raw string, currentMessageID string) ReplyDirectiveResult

ParseReplyDirectives parses reply/silent/audio directives for final assistant text.

type ReplyPayload 

type ReplyPayload struct {
	Text           string
	MediaURL       string
	MediaURLs      []string
	ReplyToID      string
	ReplyToTag     bool
	ReplyToCurrent bool
	AudioAsVoice   bool
	IsError        bool
}

ReplyPayload is a normalized assistant payload fragment.

func ApplyReplyToMode 

func ApplyReplyToMode(payloads []ReplyPayload, policy ReplyThreadPolicy) []ReplyPayload

type ReplyTargetDecision 

type ReplyTargetDecision struct {
	ReplyToID  string
	ThreadRoot string
	Reason     string
}

ReplyTargetDecision is the resolved target for a reply action.

func ResolveInboundReplyTarget 

func ResolveInboundReplyTarget(mode ThreadReplyMode, replyToID, threadRootID, eventID string) ReplyTargetDecision

type ReplyThreadPolicy 

type ReplyThreadPolicy struct {
	Mode                     ReplyToMode
	AllowExplicitWhenModeOff bool
}

type ReplyToMode 

type ReplyToMode string

ReplyToMode controls how reply IDs are applied to payloads. 

const (
	ReplyToModeOff   ReplyToMode = "off"
	ReplyToModeFirst ReplyToMode = "first"
	ReplyToModeAll   ReplyToMode = "all"
)

func NormalizeReplyToMode 

func NormalizeReplyToMode(raw string) ReplyToMode

type StreamingDirectiveAccumulator 

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

StreamingDirectiveAccumulator parses streamed assistant deltas while keeping directive state.

func NewStreamingDirectiveAccumulator 

func NewStreamingDirectiveAccumulator() *StreamingDirectiveAccumulator

func (*StreamingDirectiveAccumulator) Consume 

func (acc *StreamingDirectiveAccumulator) Consume(raw string, final bool) *StreamingDirectiveResult

type StreamingDirectiveResult 

type StreamingDirectiveResult struct {
	Text              string
	ReplyToExplicitID string
	ReplyToCurrent    bool
	HasReplyTag       bool
	AudioAsVoice      bool
	IsSilent          bool
}

StreamingDirectiveResult is a streaming-safe directive parse result.

func ParseStreamingChunk 

func ParseStreamingChunk(raw string) *StreamingDirectiveResult

ParseStreamingChunk parses inline directives from a streaming chunk.

type ThreadReplyMode 

type ThreadReplyMode string
const (
	ThreadReplyModeOff     ThreadReplyMode = "off"
	ThreadReplyModeInbound ThreadReplyMode = "inbound"
	ThreadReplyModeAlways  ThreadReplyMode = "always"
)

func NormalizeThreadReplyMode 

func NormalizeThreadReplyMode(raw string) ThreadReplyMode

type ToolApprovalDecision 

type ToolApprovalDecision struct {
	State   ToolApprovalState
	Reason  string
	Tool    string
	CallID  string
	IsError bool
}

ToolApprovalDecision is a policy decision output.

func DecideToolApproval 

func DecideToolApproval(input ToolPolicyInput) ToolApprovalDecision

type ToolApprovalState 

type ToolApprovalState string

ToolApprovalState tracks the approval lifecycle for tools. 

const (
	ToolApprovalRequired ToolApprovalState = "required"
	ToolApprovalPending  ToolApprovalState = "pending"
	ToolApprovalApproved ToolApprovalState = "approved"
	ToolApprovalDenied   ToolApprovalState = "denied"
	ToolApprovalTimedOut ToolApprovalState = "timed_out"
	ToolApprovalStale    ToolApprovalState = "stale"
)

type ToolPolicyInput 

type ToolPolicyInput struct {
	ToolName      string
	ToolKind      string // builtin|mcp|provider
	CallID        string
	RequireForMCP bool
	RequiredTools map[string]struct{}
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.