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 Bounds struct {
	// MaxIterations bounds the Completer-call count of one Run.
	MaxIterations int
	// MaxCallsPerTurn bounds one turn's model-requested tool calls.
	// Zero means unbounded.
	MaxCallsPerTurn int
	// MaxTotalTokens caps the run's cumulative billed tokens. Zero
	// 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 means unbounded.
	MaxConsecutiveToolFailures int
}

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 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
	// OnToolCallError runs only on the ErrorPolicyReport path after a
	// decodeAndRun or render failure, between the policy's
	// report-to-model branch and the [tool-error] body construction. It
	// lets a host synthesize a RoleTool message to append in place of
	// the default body, or skip the call entirely by returning a
	// non-nil error. Return (msg, nil) with a non-zero msg to append
	// msg; return (nil, err) to skip the call and fail the run with
	// err; return the zero Message and nil to fall through to the
	// default [tool-error] body, preserving the pre-hook contract.
	// Never fires under ErrorPolicyFail: that path hard-fails Run
	// before consulting the hook.
	OnToolCallError ErrorFunc
	// Hooks fires PointPreTool and PointPostTool per tool call, and
	// PointStop once at the end. Optional.
	Hooks *hooks.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 *usage.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 *contextbudget.Limits
	// Trim runs before each Completer call on the full message
	// history. A nil Trim passes the history through unchanged. See
	// docs/plans/agentloop.md for its contract with
	// contextplan.Planner.Plan.
	Trim func(ctx context.Context, msgs []provider.Message) ([]provider.Message, error)
	// Surface, when non-nil, is consulted at the top of every
	// iteration from the second one onward (after the steer
	// injector drain, before the Completer call). The returned
	// Surface replaces the iteration's advertised definitions,
	// call-resolution registry, and scope; a nil return keeps the
	// previous surface. A panic inside the hook fails the run.
	// Optional; the default (nil) runs every iteration on the
	// Options-level Tools and Scope unchanged.
	Surface func() *Surface
	// StreamingWriter, when non-nil, mirrors what the Completer
	// writes through Request.StreamingWriter during a call. The
	// loop buffers the same bytes; on a Steered stop the buffered
	// bytes become Result.Final.Content, so a partial reply
	// survives the cancel. A nil writer keeps Result.Final empty on
	// Steered stop. Must be safe for concurrent use.
	StreamingWriter io.Writer
	// 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
	// Window plans every iteration against a token budget. A nil Window
	// disables planning; the loop then runs exactly as before. A non-nil
	// Window requires Summarizer and Calibrated, and excludes Trim. When
	// Budget is also set, Window's compaction runs before the Budget
	// check, so Budget sees the compacted history, not the raw one.
	Window *contextplan.Window
	// Summarizer runs the LLM summary every compaction requires.
	// Required when Window is set.
	Summarizer *contextsummary.Summarizer
	// Calibrated estimates tokens for planning and receives one Observe
	// call after every Chat. Required when Window is set.
	Calibrated *contextplan.Calibrated
	// Conclude groups the graceful-conclude terms; see the Conclude
	// type for Margin, Deadline, and Notice.
	Conclude Conclude
	// StartTime is the wall-clock anchor the SDK uses for the
	// time-based Conclude.Deadline term. The work deadline the loop
	// measures against is StartTime.Add(Conclude.Deadline) when
	// Conclude.Deadline is positive; zero StartTime falls back to the
	// time of New, so the threshold fires the deadline into the run
	// from the moment of construction. Zero StartTime and zero
	// Conclude.Deadline together disable the term entirely.
	StartTime time.Time
	// DedupWithinTurn detects a duplicate (tool, canonical-argument) call
	// already served earlier in the same turn, and serves
	// DuplicateCallNotice instead of running the tool again. False, the
	// zero value, runs every call, unchanged from the base plan.
	DedupWithinTurn bool
	// 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
	// WorkBudget, when non-nil, is a host-callable token-reservation
	// surface the loop invokes around each Completer call. A non-nil
	// WorkBudget requires both functions; Validate rejects a half-wired
	// one with ErrIncompleteWorkBudget. See WorkBudget for details.
	WorkBudget *WorkBudget
	// ToolBudget, when non-nil, is a host-callable cumulative tool-call
	// budget invoked once per turn before dispatch. The zero value
	// (nil) disables it. See ToolBudget for details.
	ToolBudget *ToolBudget
	// ContinueOnStop is consulted when the loop is about to stop
	// gracefully. A non-empty return appends those messages to the run
	// history and continues the loop. A nil or empty return stops the run
	// unchanged. A nil hook changes no behavior. Runs on the loop
	// goroutine, like Surface; a panic fails the run closed. A
	// continuation is an ordinary iteration and obeys every bound the
	// loop owns. The loop adds no bound of its own for this hook: a
	// caller that sets neither MaxIterations nor MaxTotalTokens and
	// always returns messages gets an unbounded run. That is the
	// caller's choice. See docs/plans/agentloop.md.
	ContinueOnStop func(ctx context.Context, d StopDecision) []provider.Message
}

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 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)
}