feat(loop): agent loop（8 轮 + checkpoint + 流式 + 记忆注入/提取 + trace + 工具超时回喂）

internal/runtime/loop/options.go

@@ -0,0 +1,56 @@
+package loop
+
+import (
+	"log/slog"
+
+	"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/persist"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/tool"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
+)
+
+// Options configures a Loop. All fields are optional and nil is tolerated until
+// the step that actually needs the field: the agent is required for Run (Run
+// returns ErrNilAgent otherwise); a missing tool dispatcher causes a requested
+// call to be fed back as an error; a missing retriever/persona skips memory
+// injection; a missing extractor/store skips the memory hook; a missing
+// checkpoint skips persistence; a missing tracer skips tracing.
+type Options struct {
+	// Agent is the loop's execution unit: an instruction string plus a backend
+	// adapter, an optional tool dispatcher and optional guardrails.
+	Agent *agent.Agent
+	// Tools is the tool dispatcher used to execute model-requested calls. When
+	// nil the loop falls back to the agent's own dispatcher (if any).
+	Tools *tool.Dispatcher
+	// Memory is the long-term memory store used to persist extracted items.
+	Memory *memory.Store
+	// Retriever injects relevant memories into the first-turn context.
+	Retriever *memory.Retriever
+	// WorkingMemory is the per-session sliding window, provided for the
+	// orchestrator to inspect; the loop does not mutate it.
+	WorkingMemory *memory.WorkingMemory
+	// Extractor derives memory items to persist after every step.
+	Extractor memory.Extractor
+	// Checkpoint persists a durable snapshot of the loop state at every step.
+	Checkpoint *persist.Store
+	// Tracer emits a structured span for every step, LLM call and tool call.
+	Tracer *trace.Tracer
+	// Guards validates request/response payloads on the streaming path, where
+	// RunStep is bypassed. On the non-streaming path the agent runs its own
+	// guardrails inside RunStep.
+	Guards *guardrail.Pipeline
+	// PersonaID scopes memory retrieval and extraction. Blank skips both.
+	PersonaID string
+	// MaxRounds is the tool-loop upper bound. Non-positive selects
+	// DefaultMaxRounds (8).
+	MaxRounds int
+	// OnStream, when non-nil, switches the loop to the streaming path: the model
+	// adapter's ChatStream is driven directly and each token delta is forwarded
+	// to this callback.
+	OnStream func(delta string)
+	// Log is the base logger. Nil is replaced with a discard logger tagged with
+	// source "runtime/loop".
+	Log *slog.Logger
+}