loop

Documentation

Overview

Package loop implements the ReAct (Reasoning + Acting) agent loop.

Index

• type Engine
  • func New(client *llm.Client, registry *tool.Registry, maxIterations int, ...) *Engine
  • func (e *Engine) Run(ctx context.Context, task string) (string, error)
  • func (e *Engine) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)
  • func (e *Engine) SetApprover(a danger.Approver)
  • func (e *Engine) SetDangerousConfig(cfg *danger.DangerousConfig)
  • func (e *Engine) SetEpisodeContextFunc(ef EpisodeContextFunc)
  • func (e *Engine) SetInteractionMode(mode string)
  • func (e *Engine) SetIterationCallback(cb IterationCallback)
  • func (e *Engine) SetMaxToolParallel(n int)
  • func (e *Engine) SetMemoryPromptFunc(fn func() string)
  • func (e *Engine) SetModel(model string)
  • func (e *Engine) SetNarrator(n *narrate.Narrator)
  • func (e *Engine) SetSkillLoader(sl SkillLoader)
  • func (e *Engine) SetSkillVerbose(verbose bool)
  • func (e *Engine) SetToolEventHandler(cb ToolEventHandler)
• type EpisodeContextFunc
• type IterationCallback
• type IterationInfo
• type SkillLoader
• type ToolEventHandler

Types

type Engine

type Engine struct {

	// PromptCaching enables Anthropic/OpenAI/DeepSeek prompt caching markers.
	// When enabled, the system prompt and first user message are annotated
	// with cache_control markers, and the system prompt is moved to the
	// dedicated "system" field for Anthropic compatibility.
	PromptCaching bool

	// MaxToolParallel controls how many tool calls run concurrently per
	// iteration. 0 = use default (4). Models that support parallel tool
	// calling (Claude 3.5+, GPT-4o, DeepSeek V4) can emit multiple tool
	// calls in one response — this setting bounds concurrency so tools
	// like read_file, search_files, and web_search run in parallel while
	// avoiding resource exhaustion.
	MaxToolParallel int

	// Token accounting — accumulated across all iterations of the most recent run.
	// Reset on each Run/RunWithMessages call and read by callers (e.g. WebUI).
	TotalInputTokens  int
	TotalOutputTokens int

	// Cache metrics accumulated across all iterations.
	TotalCacheCreationTokens int // Anthropic: tokens written to cache
	TotalCacheReadTokens     int // Anthropic: tokens read from cache
	TotalCachedTokens        int // OpenAI: cached prompt tokens
	// contains filtered or unexported fields
}

Engine runs the agent loop: observe → think → act → repeat.

func New

func New(client *llm.Client, registry *tool.Registry, maxIterations int, systemMessage string, renderer *render.Renderer, maxContext int) *Engine

New creates a new loop Engine. maxContext is the model's maximum context window in tokens. Pass 0 for no limit enforcement.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, task string) (string, error)

Run executes the loop for a given task and returns the final response.

func (*Engine) RunWithMessages

func (e *Engine) RunWithMessages(ctx context.Context, messages []llm.Message) (string, []llm.Message, error)

RunWithMessages executes the agent loop starting from a pre-built message history. The messages must include the system prompt (if any), all prior conversation turns, and the new user message as the last entry. Returns the final answer plus the full updated message history so callers can persist it (e.g. to a session file).

Use this for multi-turn conversations: load the session, append the new user message, call RunWithMessages, then save the returned messages.

func (*Engine) SetApprover

func (e *Engine) SetApprover(a danger.Approver)

SetApprover sets the approval gate for dangerous operations. When set and the LLM returns multiple tool calls in one iteration, a single batch approval prompt is shown. Individual tool-level approval is bypassed when the batch is approved (if the approver supports SetTrustAll).

func (*Engine) SetDangerousConfig

func (e *Engine) SetDangerousConfig(cfg *danger.DangerousConfig)

SetDangerousConfig provides the DangerousConfig for batch gate pre-classification. Without it, the batch gate cannot know which risk classes require approval and would skip pre-checking.

func (*Engine) SetEpisodeContextFunc

func (e *Engine) SetEpisodeContextFunc(ef EpisodeContextFunc)

SetEpisodeContextFunc sets the optional per-turn episode search callback. When set, it is called once per new user message to search for relevant past session episodes. The returned context is injected as a system message before the LLM invocation.

func (*Engine) SetInteractionMode

func (e *Engine) SetInteractionMode(mode string)

SetInteractionMode sets how progress is surfaced. "off" suppresses all per-iteration render output except the final answer.

func (*Engine) SetIterationCallback

func (e *Engine) SetIterationCallback(cb IterationCallback)

SetIterationCallback sets the iteration progress callback. If nil, no callback is fired.

func (*Engine) SetMaxToolParallel

func (e *Engine) SetMaxToolParallel(n int)

SetMaxToolParallel sets the maximum concurrency for tool execution per iteration. 0 or negative = use default (4).

func (*Engine) SetMemoryPromptFunc

func (e *Engine) SetMemoryPromptFunc(fn func() string)

SetMemoryPromptFunc sets the optional memory prompt callback. When set, it is called before each LLM invocation to get fresh memory content. This ensures the agent sees the latest facts even if it modifies memory during a session.

func (*Engine) SetModel

func (e *Engine) SetModel(model string)

SetModel updates the LLM model used by this engine at runtime. The model string must be a valid OpenAI-compatible model identifier.

func (*Engine) SetNarrator

func (e *Engine) SetNarrator(n *narrate.Narrator)

SetNarrator sets the optional narrator for engaging mode. When nil (the default), tools render in verbose mode via the Renderer.

func (*Engine) SetSkillLoader

func (e *Engine) SetSkillLoader(sl SkillLoader)

SetSkillLoader sets the optional skill loader callback.

func (*Engine) SetSkillVerbose

func (e *Engine) SetSkillVerbose(verbose bool)

SetSkillVerbose controls whether skill loading shows full banners (true) or condensed markers (false, default). Condensed saves context window space.

func (*Engine) SetToolEventHandler

func (e *Engine) SetToolEventHandler(cb ToolEventHandler)

SetToolEventHandler sets the optional tool event callback for live streaming.

type EpisodeContextFunc

type EpisodeContextFunc func(userInput string) string

EpisodeContextFunc is an optional callback that the loop engine calls before each LLM invocation to discover relevant past session episodes. The callback receives the latest user input as a search query and returns formatted episode context to inject, or empty string if nothing matches.

type IterationCallback

type IterationCallback func(info IterationInfo)

IterationCallback is an optional callback invoked after each iteration of the agent loop. Used by Telegram/WebUI for progress reporting.

type IterationInfo

type IterationInfo struct {
	Turn                int           // current iteration (1-indexed)
	MaxTurns            int           // max iterations configured
	ToolNames           []string      // tools called this turn (duplicates possible)
	InputTokens         int           // cumulative input tokens
	OutputTokens        int           // cumulative output tokens
	CacheCreationTokens int           // cumulative cache creation tokens
	CacheReadTokens     int           // cumulative cache read tokens
	CachedTokens        int           // cumulative cached tokens (OpenAI)
	TotalLatency        time.Duration // cumulative wall time
	HasFinalAnswer      bool          // true when the agent reached a final answer
	ReasoningContent    string        // LLM reasoning before tool calls (empty if none)
	IsPreTool           bool          // true when fired BEFORE tool execution (shows reasoning + tools)
}

IterationInfo holds data about a single agent loop iteration, passed to the IterationCallback after each turn. Used for progress reporting.

type SkillLoader

type SkillLoader func(userInput string) string

SkillLoader is an optional callback that the loop engine calls before each LLM invocation to discover contextually relevant skills. The callback receives the latest user input and returns additional system context (formatted skill content) to inject, or empty string if no skills match.

type ToolEventHandler

type ToolEventHandler func(event string, name string, data string)

ToolEventHandler is an optional callback invoked for each tool execution during the agent loop — fires before (tool_call) and after (tool_result) each tool invocation. Used by the WebUI for live streaming of tool events.