Cyrene_v2/internal/runtime/loop/loop.go

// Package loop implements the default agent execution engine of the Cyrene v2
// runtime (DevDocs/design/04-运行时.md §1). It owns the loop that package agent
// deliberately leaves out: assemble context from memory, drive the model for up
// to MaxRounds steps, execute any requested tool calls under a per-invoke
// timeout, feed tool results back to the model, persist a checkpoint at every
// step, emit structured traces, deliver streamed deltas and run the
// memory-extraction hook.
//
// The loop is configured with injected dependencies rather than concrete wiring,
// so it stays leaf-testable with mocks (a mock adapter, mock guardrail and mock
// tool, plus real in-memory memory/persist stores and a buffered trace recorder).
package loop

import (
	"errors"
	"io"
	"log/slog"

	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/agent"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/guardrail"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/persist"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/tool"
	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
)

// Constants that bound the loop. These are compile-time so no magic number
// appears in the run path.
const (
	// DefaultMaxRounds is the tool-loop upper bound used when Options.MaxRounds
	// is non-positive. It matches the agent package's own default.
	DefaultMaxRounds = 8

	// StopReasonMaxRounds reports that the loop exhausted its round budget
	// before reaching a final answer.
	StopReasonMaxRounds = "max_rounds"
)

// Sentinel errors returned by the Loop. Use errors.Is to test for them; they are
// returned directly or wrapped with %w so the underlying cause stays available.
var (
	// ErrNilAgent is returned by Run when no *agent.Agent was configured.
	ErrNilAgent = errors.New("loop: nil agent")

	// ErrNoAdapter is returned by Run (streaming path) when the agent was built
	// without a model Adapter.
	ErrNoAdapter = errors.New("loop: no model adapter")
)

// Result is the outcome of a completed Run.
type Result struct {
	// Text is the final assistant text, or empty when the loop exhausted its
	// budget without a final answer.
	Text string
	// Steps is the number of model steps executed.
	Steps int
	// StopReason classifies how the loop ended: an agent StopReason* value or
	// StopReasonMaxRounds.
	StopReason string
	// ToolCallsExecuted is the number of tool calls the loop invoked, including
	// those that failed.
	ToolCallsExecuted int
}

// Loop is the default agent execution engine. It is configured once via New and
// safe for concurrent Run calls as long as the injected dependencies (agent,
// dispatcher, stores, recorder, tracer) are themselves concurrency-safe, which
// they are by contract. Run keeps all loop state on the stack.
type Loop struct {
	agent      *agent.Agent
	tools      *tool.Dispatcher
	memory     *memory.Store
	retriever  *memory.Retriever
	working    *memory.WorkingMemory
	extractor  memory.Extractor
	checkpoint *persist.Store
	tracer     *trace.Tracer
	guards     *guardrail.Pipeline
	personaID  string
	maxRounds  int
	onStream   func(model.StreamEvent)
	log        *slog.Logger
}

// New builds a Loop from opts, applying defaults. A non-positive MaxRounds
// selects DefaultMaxRounds; a nil Log is replaced by a discard logger tagged with
// source "runtime/loop". Every dependency may be nil and is tolerated until the
// step that needs it (mirroring the run-time nil-tolerance of the underlying
// packages); Run returns ErrNilAgent when no agent is configured.
func New(opts Options) *Loop {
	maxRounds := opts.MaxRounds
	if maxRounds <= 0 {
		maxRounds = DefaultMaxRounds
	}
	return &Loop{
		agent:      opts.Agent,
		tools:      opts.Tools,
		memory:     opts.Memory,
		retriever:  opts.Retriever,
		working:    opts.WorkingMemory,
		extractor:  opts.Extractor,
		checkpoint: opts.Checkpoint,
		tracer:     opts.Tracer,
		guards:     opts.Guards,
		personaID:  opts.PersonaID,
		maxRounds:  maxRounds,
		onStream:   opts.OnStream,
		log:        sourcedLog(opts.Log),
	}
}

// MaxRounds returns the tool-loop upper bound configured for the loop.
func (l *Loop) MaxRounds() int { return l.maxRounds }

// Agent returns the injected agent.
func (l *Loop) Agent() *agent.Agent { return l.agent }

// sourcedLog returns a logger tagged with the module source "runtime/loop",
// replacing a nil logger with a discard one so the loop can always log safely.
func sourcedLog(l *slog.Logger) *slog.Logger {
	if l == nil {
		l = slog.New(slog.NewTextHandler(io.Discard, nil))
	}
	return logger.WithSource(l, "runtime/loop")
}