AgentLoopConfig class final

Configuration for one agent loop run.

Ported subset of pi's AgentLoopConfig. convertToLlm, shouldStopAfterTurn, getApiKey, and the provider-option fields are not ported (see the library doc).

Constructors

AgentLoopConfig({required Model model, ToolExecutionMode toolExecution = ToolExecutionMode.parallel, BeforeToolCallHook? beforeToolCall, AfterToolCallHook? afterToolCall, TransformContextHook? transformContext, PrepareNextTurnHook? prepareNextTurn, OverWindowRelief? overWindowRelief, QueuedMessagesSource? getSteeringMessages, QueuedMessagesSource? getFollowUpMessages, Stream<void>? steeringNotifications, Future<bool> hasPendingSteering()?, int maxEmptyRetries = 1, int maxSteeringTurns = 20, int? contextWindowCap, bool wireDump = false, ToolMisuseBreaker? toolMisuseBreaker, StuckToolConfig? stuckTool})
const

Properties

afterToolCall → AfterToolCallHook?
Called after each tool execution; can override the result.
final
beforeToolCall → BeforeToolCallHook?
Called before each tool execution; can block it.
final
contextWindowCap → int?
Owner-side effective context override (agent.contextWindowCap, issues #273/#729). The over-window guard measures the outgoing request against effectiveContextWindow — a 1M-window model run under a 256k owner cap trips the guard at 256k, not 1M, and a 200k-catalog model whose endpoint serves ~1M runs at the raised cap instead of falsely overflowing at the catalog value. null = uncapped: the raw model window, byte-identical to the pre-cap loop.
final
getFollowUpMessages → QueuedMessagesSource?
Follow-up messages to process after the run would otherwise stop.
final
getSteeringMessages → QueuedMessagesSource?
Steering messages to inject at the next turn boundary.
final
hashCode → int
The hash code for this object.
no setterinherited
hasPendingSteering → Future<bool> Function()?
Probes for externally pending steering (e.g. the messaging inbox) WITHOUT draining it — polled on a slow timer during the tool-call phase as a second yield trigger. Null when the host has no external steering source.
final
maxEmptyRetries → int
How many times a degenerate EMPTY completion (stopReason stop, no tool calls, no text — some providers answer like this under load) is retried with the same context before the turn accepts it. Default: 1 (one automatic retry — a blank answer never ends a run on the first try).
final
maxSteeringTurns → int
How many steering batches may extend ONE run (mid-run user input or external mail). Without a cap, a self-sustaining agent chatter loop (every inbound message steers a reply that triggers the next inbound) extends the run forever — the spinner never stops and typed input queues behind an endless turn. Once the cap is reached the run settles; undelivered steering stays queued and is picked up by the next run (whose own wake caps apply). Default: 20.
final
model → Model
The model to call each turn.
final
overWindowRelief → OverWindowRelief?
Emergency relief for the over-window guard (issue #387). Called at most once per response before the guard's refusal surfaces; see OverWindowRelief. null = the guard keeps today's behavior.
final
prepareNextTurn → PrepareNextTurnHook?
Adjusts context/model between turns.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
steeringNotifications → Stream<void>?
Fires when a steering message arrives mid-run (the in-process queue). The tool-call phase turns the first arrival into a soft-yield request (see currentYieldToken): yield-aware long-running tools (bash, task) finish the tool call early WITHOUT stopping the underlying work, so the user message is delivered at the next step boundary instead of waiting for the whole tool call.
final
stuckTool → StuckToolConfig?
Stuck-call supervision (gh-1054): liveness heartbeats for long-running tool calls plus the autonomous cancel/retry/convert follow-up. null = unsupervised (byte-identical legacy behavior).
final
toolExecution → ToolExecutionMode
How tool calls within one assistant message are executed. Default: ToolExecutionMode.parallel (pi default).
final
toolMisuseBreaker → ToolMisuseBreaker?
The tool-misuse circuit breaker (issue #862): N consecutive identical rejections of the same tool arm a corrective note for the next request payload; M stop executing that identical call for the rest of the run. null disables the breaker entirely — behavior is byte-identical to the pre-breaker loop (E5).
final
transformContext → TransformContextHook?
Rewrites the message list sent to the provider before each call.
final
wireDump → bool
Opt-in raw wire-dump capture (issue #385 F5). When true, every ModelRequestEvent carries rawWireDump — the serialized outbound request JSON BEFORE provider shaping; hosts redact through their active pipeline and cap before persisting. Default: false.
final

Methods

copyWith({Model? model}) → AgentLoopConfig
Returns a copy with model replaced (used by prepareNextTurn).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited