runner

Documentation

Overview

Package runner executes a single agent turn, including multi-round tool calling. It is the canonical execution path used by both the scheduler and the run command.

Index

• Constants
• func BuildRunData(a model.Agent) map[string]any
• func ExpandPromptPayload(a model.Agent, payload map[string]any) (model.Agent, error)
• type ContextSnapshot
• type ProgressEvent
• type Runner
  • func (r *Runner) Run(ctx context.Context, a model.Agent, budget model.TokenBudget) (rec model.RunRecord, runErr error)

Constants

const DefaultToolRounds = 5

DefaultToolRounds is the tool call cycle limit when neither the agent nor Config.MaxToolRounds specifies a value.

Functions

func BuildRunData

func BuildRunData(a model.Agent) map[string]any

BuildRunData returns the standard built-in template variables for an agent run. The returned map is suitable for merging with QueueItem.Payload and passing to ExpandPromptPayload. Built-in vars: agent_name, schedule, now, tags. Lifecycle parameters (a.Parameters) are included so scheduled agents can use {{.param_name}} substitution; queue payloads merged by the caller win on collision.

func ExpandPromptPayload

func ExpandPromptPayload(a model.Agent, payload map[string]any) (model.Agent, error)

ExpandPromptPayload applies text/template substitution to the agent's SystemPrompt and UserPrompt using payload as the template data. Template variables use {{.fieldName}} syntax (standard Go text/template). Returns an error (fail-closed) if any template fails to parse or execute. Returns a unchanged copy of the agent when payload is nil or empty.

Types

type ContextSnapshot

type ContextSnapshot struct {
	AgentName   string
	Turn        int
	Round       int
	Messages    []model.Message
	ToolNames   []string
	ExtraBody   map[string]any
	MaxTokens   int
	Temperature float64
}

ContextSnapshot is a point-in-time view of the exact input sent to one LLM completion call.

type ProgressEvent

type ProgressEvent struct {
	// Kind is "call" when a tool is invoked, "result" when it returns,
	// "system" when the system prompt is added, "user" when a user prompt
	// is added, "skill_start" when a skill is loaded, "context" when the
	// exact LLM input window is captured, or "extract" when a
	// value is captured from a tool result into the turn-variable map.
	Kind string
	// Round is the tool-call cycle index (0-based).
	Round int
	// Tool is the tool name.
	Tool string
	// ToolType is the executor type: "http", "mcp", etc.
	ToolType string
	// ResultBytes is the byte length of the tool result content (Kind=="result" only).
	ResultBytes int
	// ResultPreview is a truncated, human-readable snapshot of the tool result
	// content as it enters the model's context (Kind=="result" only). Capped to
	// keep pretty output tractable; never used for behaviour, only display.
	ResultPreview string
	// Error is non-empty when tool execution failed (Kind=="result" only).
	Error string
	// Args is the JSON-encoded tool arguments (Kind=="call" only).
	Args string
	// Prompt holds the prompt text (Kind=="system" or Kind=="user" only).
	Prompt string
	// Skill is the skill name (Kind=="skill_start" only).
	Skill string
	// VarKey and VarVal are the extracted key and value (Kind=="extract" only).
	VarKey string
	VarVal string
	// Context holds the exact pre-completion message snapshot (Kind=="context" only).
	Context *ContextSnapshot
	// HideID is the buffer ID of the created hide (Kind=="hide" only).
	HideID string
	// TotalPages is the total page count for the hide (Kind=="hide" only).
	TotalPages int
	// Response holds the assistant text reply (Kind=="agent" only).
	Response string
	// PromptTokens, CompletionTokens, TotalTokens record usage for the turn
	// that produced this response (Kind=="agent" only).
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

ProgressEvent describes a single tool-call activity during an agent run.

type Runner

type Runner struct {
	// Client is the LLM backend used for completions.
	Client session.LLMClient
	// Registry provides tool definitions looked up from agent skill lists.
	// May be nil; nil means no tool calling is available.
	Registry *tool.Registry
	// Log is the structured logger for this runner instance.
	Log *logging.Logger
	// MaxToolRounds is the global default tool call cycle limit.
	// Agents may override with Agent.ToolRounds.
	MaxToolRounds int
	// Cache is the sha256-keyed file cache for agent responses.
	// May be nil; nil means caching is disabled globally.
	Cache *cache.FileCache
	// QueueMgr is used for output routing to named queues.
	// May be nil; nil means queue output routing is unavailable.
	QueueMgr *queue.Manager
	// Notifiers maps backend name to a ready Notifier for type=notify output routes.
	// May be nil or empty; missing backend names are logged as warnings.
	Notifiers map[string]notify.Notifier
	// MCPRegistry is the registry of running MCP server clients.
	// May be nil; nil means mcp-type tools are unavailable.
	MCPRegistry *mcp.Registry
	// HideBuffer is the in-process store for large tool outputs.
	// When non-nil, tool results exceeding a threshold are intercepted and
	// paged via the hide/cut API instead of being delivered in full.
	// May be nil; nil means large-output buffering is disabled.
	HideBuffer *hide.HideBuffer
	// ProgressFn, when non-nil, is called for each tool call and result event.
	// It is called synchronously in the run goroutine; implementations must not block.
	ProgressFn func(ProgressEvent)
	// DebugContextFn, when non-nil, receives the exact message window and tool
	// exposure immediately before each LLM completion call. Intended for
	// operator-visible debugging of "what did the model actually see?"
	DebugContextFn func(ContextSnapshot)
	// ForceTextAfterHide, when true, strips all tools from the next LLM call
	// whenever a hide navigation tool (hide_next, hide_jump, hide_search) executes
	// within a round. This prevents the model from chaining additional tool calls
	// immediately after paging — the only valid next action is a text reflection.
	ForceTextAfterHide bool
	// NoToolsForFirstTurn, when true, suppresses all tools for the very first
	// user turn (index 0). Use with ForceTextAfterHide in reflection mode so
	// the model is forced to reflect on the first page content rather than
	// immediately calling hide_next before being asked to.
	NoToolsForFirstTurn bool
	// NoToolsForLastTurn, when true, suppresses all tools for the final user
	// turn. Use in reflection mode so the final structured output is plain text
	// after all pages have been read.
	NoToolsForLastTurn bool
	// Vars holds named values that replace {{key}} placeholders in the agent's
	// system prompt and user prompt before the first LLM call. Populated by
	// leather run when skills declare parameters.
	Vars map[string]string
	// contains filtered or unexported fields
}

Runner executes agents with optional tool calling support.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, a model.Agent, budget model.TokenBudget) (rec model.RunRecord, runErr error)

Run executes a single agent turn. It:

1. Collects tool definitions from the agent's skill list.
2. Builds the session with system and user prompts (augmented by skill prompts).
3. Calls the model in a loop, executing any tool calls and feeding results back.
4. Returns a RunRecord with turn content, token usage, and timing.