base

package
v0.3.7 Latest Latest
Warning

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

 Go to latest Published: Sep 21, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package base provides the shared runtime struct and core execution methods used by both the local and temporal runtime backends. It has no dependency on any backend-specific SDK (no Temporal, no workflow/activity imports).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyLLMSampling 

func ApplyLLMSampling(s *types.LLMSampling, req *interfaces.LLMRequest)

ApplyLLMSampling copies non-zero sampling fields from s onto req. A nil sampling value is a no-op.

func ApplyToolCircuitResult added in v0.3.7 

func ApplyToolCircuitResult(cb *CircuitBreaker, unknown bool, kind types.ToolKind, name string, args map[string]any, failed bool, now time.Time)

ApplyToolCircuitResult records success or failure for one telemetry-eligible tool.

func CircuitBreakerSkippedMessage added in v0.3.7 

func CircuitBreakerSkippedMessage(name string) string

CircuitBreakerSkippedMessage is the synthetic tool-role content when a tripped breaker skips a tool.

func ClampExtraIterations added in v0.3.7 

func ClampExtraIterations(extra, originalMax int) int

ClampExtraIterations enforces the extend-iterations hard cap: ExtraIterations ≥ 1 and at most the original max-iter bound (one grant; the caller refuses a second).

func CloneLLMUsage 

func CloneLLMUsage(u *interfaces.LLMUsage) *interfaces.LLMUsage

CloneLLMUsage returns a shallow copy of u, or nil when u is nil.

func CountsTowardCircuitBreaker added in v0.3.7 

func CountsTowardCircuitBreaker(unknown bool, kind types.ToolKind) bool

CountsTowardCircuitBreaker reports whether a tool call participates in the per-tool tracker.

func EffectiveMaxIterations added in v0.3.7 

func EffectiveMaxIterations(configured int) int

EffectiveMaxIterations returns the loop bound used when Limits.MaxIterations is unset.

func FindToolByName 

func FindToolByName(tools []interfaces.Tool, toolName string) (interfaces.Tool, bool)

FindToolByName returns the first tool whose Name() matches toolName.

func FormatMemoryEntries added in v0.2.2 

func FormatMemoryEntries(entries []interfaces.MemoryEntry) string

FormatMemoryEntries formats memories for injection into the LLM system prompt.

func FormatRetrieverDocs 

func FormatRetrieverDocs(docs []interfaces.Document) string

FormatRetrieverDocs formats a list of documents for injection into the LLM system prompt. Each entry is rendered as "[N] content\n(source: s, score: 0.XX)\n\n".

func HashToolArgs added in v0.3.7 

func HashToolArgs(args map[string]any) string

HashToolArgs is a stable SHA-256 of args (encoding/json sorts map keys).

func IsUnknownTool added in v0.3.7 

func IsUnknownTool(tc ToolCallRequest, tools []interfaces.Tool) bool

IsUnknownTool reports whether tc should be skipped (synthetic message, no authorize/execute).

func LLMPolicyAttempts added in v0.3.7 

func LLMPolicyAttempts(maxAttempts int) int

LLMPolicyAttempts is the post-policy attempt count reported to OnLLMFailure.

func LastToolAction added in v0.3.7 

func LastToolAction(toolNames []string) string

LastToolAction is the MaxIterationsInfo.LastAction value: tool names from the last LLM round.

func MergeLLMUsage 

func MergeLLMUsage(acc, add *interfaces.LLMUsage) *interfaces.LLMUsage

MergeLLMUsage accumulates add into acc and returns the result. Either argument may be nil; when both are nil, nil is returned.

func NewAgentTelemetry added in v0.2.2 

func NewAgentTelemetry(startedAt time.Time) *types.AgentTelemetry

func SubAgentQuery 

func SubAgentQuery(args map[string]any) string

SubAgentQuery extracts the query string from a sub-agent tool call's args map.

func SubAgentScope added in v0.2.2 

func SubAgentScope(parent interfaces.MemoryScope, subAgentID string) interfaces.MemoryScope

SubAgentScope derives memory scope for a delegated sub-agent from the parent run scope.

func UnknownToolMessage added in v0.3.7 

func UnknownToolMessage(name string) string

UnknownToolMessage is the synthetic tool-role content when the LLM names a tool that is not registered on the agent.

Types

type AuthorizeResult 

type AuthorizeResult struct {
	Allowed bool
	Reason  string
}

AuthorizeResult is the outcome of a programmatic tool authorization check. When Allowed is false, Reason carries the denial message for logging/events.

type BudgetExceededError added in v0.3.5 

type BudgetExceededError struct {
	Kind             types.BudgetExceededKind
	TotalTokens      int64
	TotalCostUSD     float64
	LimitTokens      int64   // effective window size (ApprovalExtraTokens or MaxTokens)
	LimitCostUSD     float64 // effective window size in USD
	WatermarkTokens  int64   // token total at last approval (0 if never approved)
	WatermarkCostUSD float64 // cost total at last approval (0 if never approved)
}

BudgetExceededError is returned by Add or Check when a limit is breached. When Kind is BudgetExceededKindTokens: TotalTokens, LimitTokens, WatermarkTokens are set. When Kind is BudgetExceededKindCost: TotalCostUSD, LimitCostUSD, WatermarkCostUSD are set.

func (*BudgetExceededError) Error added in v0.3.5 

func (e *BudgetExceededError) Error() string

type BudgetTracker added in v0.3.5 

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

BudgetTracker accumulates token and cost usage for one run and checks limits.

Safe for concurrent use: all methods lock an internal mutex. This matters when a shared tracker (nested sub-agents pass their parent's BudgetTracker down, see AgentLoopInput.BudgetTracker) is mutated from more than one goroutine at once — e.g. two sub-agent delegation tool calls running concurrently under types.AgentToolExecutionModeParallel each call Add for their own LLM usage against the same tracker.

Cost is stored internally as integer nano-dollars (1e-9 USD) to avoid floating-point accumulation drift over hundreds of LLM calls. Public methods return and accept float64 USD for API compatibility; conversions are performed at the boundary.

func NewBudgetTracker added in v0.3.5 

func NewBudgetTracker(cfg *types.BudgetConfig) *BudgetTracker

NewBudgetTracker returns a tracker for cfg. Returns nil when cfg is nil (no enforcement). Precomputes integer nano-dollar rates from the config float64 rates to avoid accumulation drift.

func (*BudgetTracker) Add added in v0.3.5 

func (t *BudgetTracker) Add(u *interfaces.LLMUsage) error

Add accumulates usage from u and returns a BudgetExceededError if any limit is now exceeded. Returns nil when no limit is breached. The tracker is always updated even on error. u may be nil (no-op). Safe to call after a breach — subsequent calls continue accumulating.

func (*BudgetTracker) AdvanceWatermark added in v0.3.5 

func (t *BudgetTracker) AdvanceWatermark() (approvalGranted bool)

AdvanceWatermark moves the approval watermark to the current totals after a BudgetWaitForApproval approval and increments the approval counter. Returns false when MaxApprovals has been reached — caller must treat the next breach as BudgetStopRun.

func (*BudgetTracker) ApprovalCount added in v0.3.5 

func (t *BudgetTracker) ApprovalCount() int

ApprovalCount returns how many BudgetWaitForApproval approvals have been granted this run.

func (*BudgetTracker) ApprovalsExhausted added in v0.3.5 

func (t *BudgetTracker) ApprovalsExhausted() bool

ApprovalsExhausted reports whether the run has consumed all allowed approval pauses. When true, the next budget breach must be treated as BudgetStopRun.

func (*BudgetTracker) Check added in v0.3.5 

func (t *BudgetTracker) Check() error

Check returns a BudgetExceededError when current totals breach limits relative to the watermark, without adding usage. Used after nested sub-agent runs that accumulated into a shared tracker.

func (*BudgetTracker) RestoreState added in v0.3.5 

func (t *BudgetTracker) RestoreState(tokens int64, costUSD float64, wmTokens int64, wmCostUSD float64)

RestoreState reloads accumulated totals and watermark values from durable state (e.g. after a Temporal ContinueAsNew). Must be called before any Add; panics otherwise to prevent silent corruption of accumulated totals.

func (*BudgetTracker) Totals added in v0.3.5 

func (t *BudgetTracker) Totals() (tokens int64, costUSD float64)

Totals returns the accumulated token count and estimated cost in US dollars for the run.

func (*BudgetTracker) WatermarkTotals added in v0.3.5 

func (t *BudgetTracker) WatermarkTotals() (tokens int64, costUSD float64)

WatermarkTotals returns the token and USD values at the last approval watermark.

type CircuitBreaker added in v0.3.7 

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

CircuitBreaker is the per-run same-args / A-B-A-B tracker. Nil receiver is a no-op.

func NewCircuitBreaker added in v0.3.7 

func NewCircuitBreaker(cfg *types.ErrorControlConfig) *CircuitBreaker

NewCircuitBreaker returns a tracker when a detector is enabled (MaxConsecutiveSameArgs > 0 or PatternWindowSize >= 4). PatternWindowSize must also be even to trip A-B-A-B; odd never trips. Nil config or both detectors off returns nil.

func NewCircuitBreakerFromState added in v0.3.7 

func NewCircuitBreakerFromState(cfg *types.ErrorControlConfig, state CircuitBreakerState) *CircuitBreaker

NewCircuitBreakerFromState restores a tracker after continue-as-new or durable replay.

func (*CircuitBreaker) IsTripped added in v0.3.7 

func (c *CircuitBreaker) IsTripped(name string, now time.Time) bool

IsTripped reports whether name is currently skipped. ResetAfter may clear the trip.

func (*CircuitBreaker) RecordFailure added in v0.3.7 

func (c *CircuitBreaker) RecordFailure(name string, args map[string]any, now time.Time) bool

RecordFailure updates consecutive same-args and the sliding window. Returns true if this call trips the tool.

func (*CircuitBreaker) RecordSuccess added in v0.3.7 

func (c *CircuitBreaker) RecordSuccess(name string)

RecordSuccess clears failure streaks. A trip is not cleared (only ResetAfter / end of run).

func (*CircuitBreaker) Restore added in v0.3.7 

func (c *CircuitBreaker) Restore(state CircuitBreakerState)

Restore replaces in-memory state after replay or continue-as-new.

func (*CircuitBreaker) State added in v0.3.7 

func (c *CircuitBreaker) State() CircuitBreakerState

State returns a copy safe to persist.

type CircuitBreakerState added in v0.3.7 

type CircuitBreakerState struct {
	Tools map[string]CircuitBreakerToolState `json:"tools,omitempty"`
}

CircuitBreakerState is the persisted per-run tracker (Temporal continue-as-new, Restate/durable journal).

type CircuitBreakerToolState added in v0.3.7 

type CircuitBreakerToolState struct {
	LastHash          string   `json:"last_hash,omitempty"`
	Consecutive       int      `json:"consecutive,omitempty"`
	Window            []string `json:"window,omitempty"`
	Tripped           bool     `json:"tripped,omitempty"`
	TrippedAtUnixNano int64    `json:"tripped_at_unix_nano,omitempty"`
}

CircuitBreakerToolState is one tool's consecutive / pattern / trip fields.

type ExecuteLLMInput added in v0.2.2 

type ExecuteLLMInput struct {
	Logger           logger.Logger
	AgentName        string
	MessageID        string
	RunID            string
	Iteration        int
	Messages         []interfaces.Message
	SkipTools        bool
	MemoryContext    string
	RetrieverContext string
	Tools            []interfaces.Tool
	Emit             func(events.AgentEvent)
	// Client overrides AgentConfig.LLM.Client for this call (per-run fallback). Nil = primary.
	Client interfaces.LLMClient
}

type ExecuteMemoryRecallInput added in v0.2.3 

type ExecuteMemoryRecallInput struct {
	Logger    logger.Logger
	RunID     string
	Iteration int
	Scope     interfaces.MemoryScope
	Query     string
}

ExecuteMemoryRecallInput holds per-invocation inputs for Runtime.ExecuteMemoryRecall. RunID and Iteration populate hooks.RunMeta for memory load middleware hooks.

type ExecuteMemoryStoreInput added in v0.2.3 

type ExecuteMemoryStoreInput struct {
	Logger    logger.Logger
	RunID     string
	Iteration int
	Scope     interfaces.MemoryScope
	Messages  []interfaces.Message
}

ExecuteMemoryStoreInput holds per-invocation inputs for Runtime.ExecuteMemoryStore. RunID and Iteration populate hooks.RunMeta for memory store middleware hooks.

type ExecuteRetrieversInput added in v0.2.3 

type ExecuteRetrieversInput struct {
	Logger    logger.Logger
	RunID     string
	Iteration int
	Query     string
}

ExecuteRetrieversInput holds per-invocation inputs for Runtime.ExecuteRetrievers. RunID and Iteration populate hooks.RunMeta for retrieve middleware hooks.

type ExecuteToolInput added in v0.2.3 

type ExecuteToolInput struct {
	Logger     logger.Logger
	Tools      []interfaces.Tool
	ToolName   string
	Args       map[string]any
	ToolCallID string
	RunID      string
	Iteration  int
}

ExecuteToolInput holds per-invocation inputs for Runtime.ExecuteTool. RunID and Iteration populate hooks.RunMeta for tool middleware hooks.

func (ExecuteToolInput) IdempotencyKey added in v0.3.5 

func (i ExecuteToolInput) IdempotencyKey() string

IdempotencyKey returns a stable 32-char hex key for a tool invocation, derived from runID, iteration, and toolCallID via SHA-256. Fixed-length output is safe for all external API idempotency key fields.

type LLMResult 

type LLMResult struct {
	Content   string
	ToolCalls []ToolCallRequest
	Usage     *interfaces.LLMUsage
}

LLMResult is the result of a successful LLM call. Content holds the assistant text; ToolCalls holds any tool invocations resolved against the registered tools list (NeedsApproval pre-computed from the approval policy).

type MemoryResult added in v0.2.2 

type MemoryResult struct {
	Context       string
	TotalRecalls  int64
	FailedRecalls int64
}

MemoryResult is the outcome of ExecuteMemoryRecall.

type RetrieverResult added in v0.2.2 

type RetrieverResult struct {
	Context        string
	TotalSearches  int64
	FailedSearches int64
}

RetrieverResult is the outcome of ExecuteRetrievers (prefetch / hybrid pre-loop).

type Runtime 

type Runtime struct {
	AgentSpec   runtime.AgentSpec
	AgentConfig runtime.AgentConfig
	Tracer      interfaces.Tracer
	Metrics     interfaces.Metrics
	// ToolExecutionMode controls whether tool calls in one LLM round are executed
	// in parallel or sequentially. Defaults to parallel when empty.
	ToolExecutionMode types.AgentToolExecutionMode
}

Runtime holds the execution inputs shared by all runtime backends. Local and Temporal runtimes embed this struct and call its methods directly.

func (*Runtime) AuthorizeTool 

func (rt *Runtime) AuthorizeTool(ctx context.Context, log logger.Logger, tools []interfaces.Tool, toolName string, args map[string]any) (AuthorizeResult, error)

AuthorizeTool checks programmatic authorization for a tool before approval/execution. Tools that do not implement interfaces.ToolAuthorizer are allowed by default.

func (*Runtime) BuildLLMRequest 

func (rt *Runtime) BuildLLMRequest(messages []interfaces.Message, skipTools bool, memoryContext, retrieverContext string, tools []interfaces.Tool) *interfaces.LLMRequest

BuildLLMRequest constructs an LLMRequest from the given messages and options. SystemMessage is the static system prompt only. When memoryContext or retrieverContext is non-empty each is prepended as a labeled user message (memory then RAG) before the conversation messages. Message content is sanitized for the LLM copy only; the caller's slice is not modified. tools is the per-run resolved tool list from runtime.ExecuteRequest or activity resolve.

func (*Runtime) DecideLLMFailure added in v0.3.7 

func (rt *Runtime) DecideLLMFailure(ctx context.Context, info types.LLMFailureInfo, log logger.Logger) types.ErrorControlDecision

DecideLLMFailure runs OnLLMFailure or returns Abort. Invalid actions and FallbackModel without a resolvable client become Abort.

func (*Runtime) DecideMaxIterations added in v0.3.7 

func (rt *Runtime) DecideMaxIterations(ctx context.Context, info types.MaxIterationsInfo, alreadyExtended bool, log logger.Logger) types.ErrorControlDecision

DecideMaxIterations runs OnMaxIterationsExceeded or returns ContinueWithFinalCall. alreadyExtended (one grant) and invalid / empty ExtraIterations use the default.

func (*Runtime) ExecuteLLM 

func (rt *Runtime) ExecuteLLM(ctx context.Context, input ExecuteLLMInput) (*LLMResult, error)

ExecuteLLM calls the LLM in non-streaming mode, records metrics and traces, emits TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END events, and returns LLMResult. messageID and agentName are used only for event construction; emit may be nil.

func (*Runtime) ExecuteLLMStream 

func (rt *Runtime) ExecuteLLMStream(ctx context.Context, input ExecuteLLMInput) (*LLMResult, error)

ExecuteLLMStream calls the LLM in streaming mode. When the LLM client does not support streaming it falls back to Generate automatically. Delta events (text content, reasoning) are emitted via emit as chunks arrive; a final TEXT_MESSAGE_START/CONTENT/END triple is emitted for non-streaming fallback. emit may be nil.

func (*Runtime) ExecuteMemoryRecall added in v0.2.2 

func (rt *Runtime) ExecuteMemoryRecall(ctx context.Context, input ExecuteMemoryRecallInput) (*MemoryResult, error)

ExecuteMemoryRecall loads scoped memories for query and returns formatted prompt context.

func (*Runtime) ExecuteMemoryStore added in v0.2.2 

func (rt *Runtime) ExecuteMemoryStore(ctx context.Context, input ExecuteMemoryStoreInput) error

ExecuteMemoryStore extracts long-term memories from the run and persists them in scope.

func (*Runtime) ExecuteRetrievers 

func (rt *Runtime) ExecuteRetrievers(ctx context.Context, input ExecuteRetrieversInput) (*RetrieverResult, error)

ExecuteRetrievers runs all configured retrievers in parallel for the given query and returns a combined document context string for injection into the LLM system prompt. Partial failures are logged and skipped; all retrievers failing returns an error.

func (*Runtime) ExecuteTool 

func (rt *Runtime) ExecuteTool(ctx context.Context, input ExecuteToolInput, memScope interfaces.MemoryScope) (string, error)

ExecuteTool runs a tool with optional memory scope; save_memory on on-demand store routes to [StoreMemoryRecords]. Retriever tools use [Runtime.executeRetrieverTool] inside [Runtime.executeTool]. For types.ToolKindNative and types.ToolKindMCP tools, hooks.BeforeToolHook and

func (*Runtime) FetchConversationMessages 

func (rt *Runtime) FetchConversationMessages(ctx context.Context, log logger.Logger, conversationID string) ([]interfaces.Message, error)

FetchConversationMessages loads prior messages from the conversation store. Returns an error when no conversation is configured or the store call fails.

func (*Runtime) MemoryConfigured added in v0.2.2 

func (rt *Runtime) MemoryConfigured() bool

MemoryConfigured reports whether long-term memory is wired on the runtime.

func (*Runtime) MemoryStoreOnDemand added in v0.2.2 

func (rt *Runtime) MemoryStoreOnDemand() bool

MemoryStoreOnDemand reports whether save_memory tool store is active.

func (*Runtime) NoteCircuitSkip added in v0.3.7 

func (rt *Runtime) NoteCircuitSkip(ctx context.Context, log logger.Logger, toolName string)

NoteCircuitSkip logs a warning and increments types.MetricToolCallCircuitOpen.

func (*Runtime) NoteUnknownTool added in v0.3.7 

func (rt *Runtime) NoteUnknownTool(ctx context.Context, log logger.Logger, toolName string)

NoteUnknownTool logs a warning and increments types.MetricToolCallUnknown.

func (*Runtime) RecallEnabled added in v0.2.2 

func (rt *Runtime) RecallEnabled() bool

RecallEnabled reports whether the SDK should load memories before each run.

func (*Runtime) RequiresApproval 

func (rt *Runtime) RequiresApproval(t interfaces.Tool) bool

RequiresApproval reports whether t requires human approval before execution. When no approval policy is configured the tool's own ApprovalRequired flag is used.

func (*Runtime) ResolveLLMClient added in v0.3.7 

func (rt *Runtime) ResolveLLMClient(useFallback bool) (interfaces.LLMClient, error)

ResolveLLMClient returns the primary client, or the named fallback when useFallback is true.

func (*Runtime) ResolveMemoryScope added in v0.2.2 

func (rt *Runtime) ResolveMemoryScope(ctx context.Context) (interfaces.MemoryScope, error)

ResolveMemoryScope builds scope from the request context using configured resolvers.

func (*Runtime) RunEndMemoryStoreEnabled added in v0.2.2 

func (rt *Runtime) RunEndMemoryStoreEnabled() bool

RunEndMemoryStoreEnabled reports whether run-end memory store runs (memory.StoreModeAlways).

func (*Runtime) StoreMemoryRecords added in v0.2.2 

func (rt *Runtime) StoreMemoryRecords(ctx context.Context, input StoreMemoryRecordsInput) error

StoreMemoryRecords persists records through kind policy, dedup, TTL, and the memory backend.

type StoreMemoryRecordsInput added in v0.2.3 

type StoreMemoryRecordsInput struct {
	Logger    logger.Logger
	RunID     string
	Iteration int
	Scope     interfaces.MemoryScope
	Records   []interfaces.MemoryRecord
}

StoreMemoryRecordsInput holds per-invocation inputs for Runtime.StoreMemoryRecords. RunID and Iteration populate hooks.RunMeta for memory store middleware hooks.

type ToolCallRequest 

type ToolCallRequest struct {
	ToolCallID      string
	ToolName        string
	ToolDisplayName string
	ToolKind        types.ToolKind
	Args            map[string]any
	NeedsApproval   bool
	Unknown         bool
}

ToolCallRequest describes one tool call returned by the LLM. NeedsApproval is pre-computed from the tool approval policy so orchestration loops (local agent loop, temporal workflow) do not need to re-evaluate the policy. Unknown is true when ToolName is not in the registered tools list; the run continues with a synthetic tool-role message and does not authorize or execute the call.

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.