loop

type CompletionMarkerConfig struct {
	// Marker is the completion marker that stops the loop when present in the
	// latest response text.
	Marker string

	// FeedbackMessageTemplate is used when the marker is absent. When nil, the
	// default template is used. The
	// completionMarkerPlaceholder token is replaced when the evaluator is
	// created, and lastResponsePlaceholder is replaced on each evaluation.
	FeedbackMessageTemplate *string
}

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

type Config struct {
	// Evaluators decide after each iteration whether the wrapped agent should
	// be re-invoked. Evaluators are checked in order; the first evaluator that
	// asks to continue wins, and the loop stops only when all evaluators stop.
	Evaluators []Evaluator

	// MaxIterations is the absolute safety cap for a single run. When nil,
	// DefaultMaxIterations is used.
	MaxIterations *int

	// OnBehalfOfAuthorName stamps loop-synthesized feedback messages. When empty,
	// feedback messages are unattributed.
	OnBehalfOfAuthorName string

	// ExcludeOnBehalfOfMessages prevents loop-synthesized feedback messages
	// from being yielded to the caller. They are still sent to the agent.
	ExcludeOnBehalfOfMessages bool

	// FreshContextPerIteration restarts each reinvocation from the original
	// input messages plus an aggregated feedback log, and resets the session
	// to a pristine snapshot taken before the first iteration.
	FreshContextPerIteration bool

	// NonStreamingReturnsLastResponseOnly causes non-streaming runs (those
	// without agent.Stream(true)) to surface only the final iteration response.
	NonStreamingReturnsLastResponseOnly bool

	// SessionCreatedCallback is invoked when the loop creates a fresh session
	// for reinvocation.
	SessionCreatedCallback func(context.Context, *agent.Session) error
}

type Context struct {
	// InitialMessages are the messages passed to the first iteration.
	InitialMessages []*message.Message

	// LastResponse is the response produced by the most recent iteration.
	LastResponse *agent.Response

	// Options are the options supplied to the agent run.
	Options []agent.Option

	// Iteration is the number of completed agent runs so far.
	Iteration int

	// Feedback contains one entry for each reinvocation requested by an
	// evaluator. Entries are empty when the reinvocation supplied no feedback
	// string or used explicit messages.
	Feedback []string

	// AdditionalProperties is a mutable bag for evaluator-specific per-run
	// state.
	AdditionalProperties map[string]any
}

type Evaluation struct {
	// ShouldReinvoke indicates whether the agent should run another iteration.
	ShouldReinvoke bool

	// Feedback is sent as a user message on the next iteration when Messages is
	// empty.
	Feedback string

	// Messages, when non-empty, are sent verbatim on the next iteration instead
	// of the loop building a feedback message.
	Messages []*message.Message
}

type Evaluator interface {
	Evaluate(ctx context.Context, loop *Context) (Evaluation, error)
}

type EvaluatorFunc func(ctx context.Context, loop *Context) (Evaluation, error)