agentloop

type AuditFunc func(ctx context.Context, rec AuditRecord) error

type AuditKind string

type AuditRecord struct {
	// Iteration is the 1-based Completer-call count this record
	// belongs to, matching Result.Iterations at the same point.
	Iteration int
	// Kind names which event this record describes.
	Kind AuditKind
	// Request is the exact provider.Request sent to Completer.Chat
	// this iteration. Set only when Kind == AuditKindCompletion.
	Request provider.Request
	// Response is the provider.Response Completer.Chat returned this
	// iteration. Set only when Kind == AuditKindCompletion.
	Response provider.Response
	// ToolCall is the model-requested call this record describes. Set
	// only when Kind == AuditKindToolCall.
	ToolCall provider.ToolCall
	// ToolResult is the RoleTool message runOneToolCall appended to
	// history for ToolCall, including any ToolErrorPrefix marker. Set
	// only when Kind == AuditKindToolCall.
	ToolResult provider.Message
	// Err is the tool-run error runOneToolCall reported, or nil on a
	// successful call. Set only when Kind == AuditKindToolCall.
	Err error
	// ThinkingContent is the response's readable reasoning text, copied out
	// so a renderer can sign or audit it independently of Response.
	// Empty on a completion whose assistant turn produced no reasoning
	// and on every tool-call record.
	ThinkingContent string
	// CacheUsage is the response's prompt-cache accounting, copied out
	// for the same reason. Reported is false on every completion whose
	// Completer did not report cache usage and on every tool-call
	// record.
	CacheUsage provider.CacheUsage
}

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

type Bounds struct {
	// MaxIterations bounds the Completer-call count of one Run.
	MaxIterations int
	// MaxCallsPerTurn bounds one turn's model-requested tool calls.
	// Zero inside a partial Bounds means unbounded.
	MaxCallsPerTurn int
	// MaxTotalTokens caps the run's cumulative billed tokens. Zero
	// inside a partial Bounds means unbounded.
	MaxTotalTokens int
	// MaxConcurrentTools bounds one turn's parallel tool calls. Zero
	// and one both mean serial.
	MaxConcurrentTools int
	// MaxConsecutiveToolFailures bounds consecutive all-failing turns.
	// A turn counts as failing when every dispatched (non-duplicate)
	// call in it carries a reported tool error under
	// ErrorPolicyReport — any reported error, not only
	// tools.ErrUnknownName. Zero inside a partial Bounds means
	// unbounded.
	MaxConsecutiveToolFailures int
}

type Compaction struct {
	// Window plans every iteration against a token budget. Nil asks
	// for derivation at New. Requires Summarizer and Calibrated, and
	// excludes Options.Trim.
	Window *plan.Window
	// Summarizer runs the LLM summary every compaction requires.
	// Required when Window is set. See the Summarizer interface for
	// the sanctioned constructors and the typed-nil check Validate
	// runs against them.
	Summarizer Summarizer
	// Calibrated estimates tokens for planning and receives one Observe
	// call after every Chat. Required when Window is set.
	Calibrated *plan.Calibrated
}

type Conclude struct {
	// Margin nudges the model once MaxIterations-k < Margin holds.
	// Zero disables the step-count term.
	Margin int
	// Deadline, when positive, fires the nudge once
	// StartTime.Add(Deadline) has passed. Zero disables the term.
	Deadline time.Duration
	// Notice is the RoleUser content Run appends once nudging starts.
	// Empty Notice uses DefaultConcludeNotice.
	Notice string
}

type ErrorFunc func(ctx context.Context, call provider.ToolCall, err error) (provider.Message, error)

type ErrorPolicy string

type Extensions struct {
	// OnToolCallError runs on the ErrorPolicyReport path after a
	// decodeAndRun or render failure. See ErrorFunc for the contract.
	OnToolCallError ErrorFunc
	// Surface, when non-nil, replaces the iteration's advertised
	// definitions, registry, and scope from iteration two onward.
	Surface func() *Surface
	// StreamingWriter, when non-nil, mirrors what the Completer
	// writes; on a Steered stop the buffered bytes become
	// Result.Final.Content. Must be safe for concurrent use.
	StreamingWriter io.Writer
	// Conclude groups the graceful-conclude terms; see the Conclude
	// type for Margin, Deadline, and Notice.
	Conclude Conclude
	// StartTime is the wall-clock anchor for Conclude.Deadline. Zero
	// falls back to the time of New.
	StartTime time.Time
	// DedupWithinTurn serves DuplicateCallNotice for a repeated
	// (tool, canonical-argument) call within one turn.
	DedupWithinTurn bool
	// WorkBudget, when non-nil, is the token-reservation surface the
	// loop invokes around each Completer call.
	WorkBudget *WorkBudget
	// ToolBudget, when non-nil, is the cumulative tool-call budget
	// invoked once per turn before dispatch.
	ToolBudget *ToolBudget
	// ContinueOnStop is consulted on every graceful stop; a non-empty
	// return continues the loop. See StopDecision.
	ContinueOnStop func(ctx context.Context, d StopDecision) []provider.Message
}

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

type Options struct {
	// Completer runs each chat turn. Required.
	Completer provider.Completer
	// Tools is the registry Definitions builds the offered tool set
	// from, and RunScoped resolves a model-chosen call against.
	// Required.
	Tools *tools.Registry
	// Scope narrows which tools a model-chosen call may invoke. Run
	// always calls Registry.RunScoped, never Registry.Run.
	Scope *tools.Scope
	// Model names the model Request.Model carries. An empty Model
	// means the Completer's own default.
	Model string
	// Bounds groups the loop's numeric caps; see the Bounds type for
	// the members and their zero values.
	Bounds Bounds
	// OnToolError governs what Run does with a tool-run error.
	OnToolError ErrorPolicy
	// Hooks fires PointPreTool and PointPostTool per tool call, and
	// PointStop once at the end. Optional.
	Hooks *events.Registry
	// Tracer opens one span per iteration and one per tool call.
	// Optional.
	Tracer *trace.Tracer
	// Usage records per-iteration provider.Usage under SessionID.
	// Requires SessionID. Optional.
	Usage *provider.Accumulator
	// SessionID keys Usage's running total. Required when Usage is
	// set.
	SessionID string
	// Bus receives Run's iteration, completion-heartbeat, and
	// tool-call events. Required when HeartbeatInterval is positive;
	// Run emits nothing through a nil Bus otherwise. Optional.
	Bus *events.Bus
	// Budget caps one Completer call's message history by byte count
	// and message count. A nil Budget means uncapped. When Window is
	// also set, Budget checks the history after window compaction runs,
	// so a history Window would compact under Budget never fails here.
	// When Window is nil, Budget checks history exactly as sent.
	Budget *budget.Limits
	// Trim runs before each Completer call on the full message
	// history. A nil Trim passes the history through unchanged. See
	// docs/history/agentloop.md for its contract with
	// plan.Planner.Plan.
	Trim func(ctx context.Context, msgs []provider.Message) ([]provider.Message, error)
	// Audit receives one AuditRecord per completed Completer turn and
	// per tool call whose result reaches history. A nil Audit means
	// Run performs no audit call, at no added cost.
	Audit AuditFunc
	// Compaction groups the context-window planning triple. The zero
	// value disables planning. See the Compaction type.
	Compaction Compaction
	// ObserveRequest runs after reserveWork and before every
	// Completer.Chat call, including the prompt-too-long recovery retry's
	// call. A non-nil error fails the iteration before the call runs.
	// This is not Options.Audit: Audit records after the fact and cannot
	// fail a call. A nil hook is a no-op.
	ObserveRequest func(ctx context.Context, req provider.Request) error
	// HeartbeatInterval emits a heartbeat Event on Bus every interval
	// while one Completer call or one tool call is in flight. Zero
	// disables heartbeats. A positive HeartbeatInterval requires a
	// non-nil Bus.
	HeartbeatInterval time.Duration
	// Extensions holds the host-integration knobs. A nil Extensions
	// means every knob at its zero value. Optional.
	Extensions *Extensions
}

type Result struct {
	// Final is the last message the model produced. Zero value when
	// the stop happened before a new response arrived, or on
	// StopHookVeto, StopMaxIterations, and StopSteered by design, and
	// on every hard-fail return.
	Final provider.Message
	// History carries every message appended so far, including the
	// caller's starting messages.
	History []provider.Message
	// Iterations counts the number of Completer calls that completed.
	Iterations int
	// Usage sums provider.Usage across every completed Completer call.
	Usage provider.Usage
	// Stop names why Run stopped gracefully. Zero value on a hard-fail
	// error return.
	Stop StopReason
}

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

type StopDecision struct {
	// Stop is the graceful reason the loop picked.
	Stop StopReason
	// Message is the assistant turn that ended the run.
	Message provider.Message
	// Iterations counts the Completer calls that completed.
	Iterations int
	// History carries every message appended so far.
	History []provider.Message
}

type StopReason string

type Summarizer interface {
	Summarize(ctx context.Context, msgs []provider.Message) (plan.Summary, error)
}

type Surface struct {
	// Advertised is the tool-definition list sent to the model this
	// iteration. Replaces the previous iteration's set wholesale.
	Advertised []provider.ToolDefinition
	// Registry resolves model-chosen calls this iteration. Nil keeps
	// the previous iteration's registry.
	Registry *tools.Registry
	// Scope narrows Registry lookups this iteration. Nil keeps the
	// previous iteration's scope.
	Scope *tools.Scope
}

type ToolBudget struct {
	// Reserve runs once per turn before its tool calls dispatch, with
	// the count about to run. A non-nil return fails the run.
	Reserve func(ctx context.Context, calls int) error
}

type WorkBudget struct {
	// Reserve runs before each Completer call with the exact request
	// about to be sent. A non-nil return fails the run.
	Reserve func(ctx context.Context, req provider.Request) error
	// Refund runs after the call outcome is known: zero Usage means
	// the call never consumed its reservation; non-zero Usage carries
	// the response's real billed usage.
	Refund func(ctx context.Context, req provider.Request, used provider.Usage)
}