Documentation
¶
Overview ¶
Package converge implements convergence monitoring for agent loops. The Monitor is a pure function over events — it takes no I/O and emits Verdicts. The runtime consults it each iteration to detect:
Oscillation: the same (tool, argsHash) signature appears k times within a sliding window of w iterations.
ZeroProgress: the state hash (from LoopFinished/IterationStarted events) is unchanged for k consecutive iterations.
DepthRunaway: spawn depth exceeds max (reserved for SP5).
Responses:
- Warn: record a warning; continue.
- Redirect: inject a ConvergenceWarning event that the transition can inspect.
- Terminate: return Stuck outcome.
Index ¶
Constants ¶
const ( DetectorOscillation = "oscillation" DetectorZeroProgress = "zero-progress" DetectorDepth = "depth" )
Detector names identify which detector fired.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// OscillationK is the number of identical (tool,args) signatures in the window before firing.
// Default: 3.
OscillationK int
// OscillationWindow is the size of the sliding window in iterations.
// Default: 10.
OscillationWindow int
// ZeroProgressK is how many consecutive iterations with the same state hash before firing.
// Default: 5.
ZeroProgressK int
// MaxDepth is the maximum spawn depth (SP5). 0 = disabled.
MaxDepth int
// Response controls what happens when any detector fires.
// Default: Terminate.
Response Response
// OscillationResponse overrides Response for oscillation specifically (optional).
// Zero value means use Response.
OscillationResponse *Response
// ZeroProgressResponse overrides Response for zero-progress specifically (optional).
ZeroProgressResponse *Response
}
Config configures the convergence thresholds.
type Monitor ¶
type Monitor struct {
// contains filtered or unexported fields
}
Monitor tracks convergence state. It is NOT thread-safe; the runner calls it sequentially from within the main loop.
func NewMonitor ¶
NewMonitor creates a Monitor with the given config. Zero-value Config fields are filled from DefaultConfig.
func (*Monitor) ObserveIteration ¶
ObserveIteration is called each time an iteration starts. stateHash is the SHA-256 of the serialized loop state at iteration start. Returns a Verdict if a zero-progress condition fires; empty Verdict otherwise.
func (*Monitor) ObserveToolCall ¶
ObserveToolCall is called each time a tool is called. It checks for oscillation (repeated identical (tool,args) signatures). Returns a Verdict if the oscillation detector fires; empty Verdict otherwise.
type ToolSignature ¶
ToolSignature is the key used by the oscillation detector.
type Verdict ¶
type Verdict struct {
// Fired is true when any detector has fired.
Fired bool
// Detector is the name of the detector that fired.
Detector string
// Reason is a human-readable explanation.
Reason string
// Count is how many times the condition has been observed.
Count int
// Response is the action the runtime should take.
Response Response
}
Verdict is returned by Monitor.Observe when a detector fires.
Source Files