runtime

type Config struct {
	ProviderSelector ProviderSelector
	ToolExecutor     ToolExecutor
	Middleware       []Middleware
	DefaultMaxTurns  int

	// Durable 可选：开启可持久化/可恢复执行。
	//
	// 非 nil 时，Runner 在每个步边界把执行快照 Save 到该端口（详见 durable.go 的
	// DurableExecution 契约），并支持 Resume 从最近快照续跑。nil 时（默认）完全不
	// 触碰持久化，行为与无此字段时一致。
	//
	// 持久化以 Request.ID 作为 RunID（命名空间）；Request.ID 为空时 Save 静默跳过
	// （无可供恢复的标识符）。Resume 必须由调用方提供同一 RunID。
	Durable DurableExecution
}

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

type DurableExecution interface {
	// Save 在步边界持久化一个执行快照。
	Save(ctx context.Context, snap Snapshot) error
	// Load 取某次执行最近的快照；不存在时 ok=false。
	Load(ctx context.Context, runID string) (Snapshot, bool, error)
}

type Error struct {
	Kind      ErrorKind
	Message   string
	Retryable bool
	// contains filtered or unexported fields
}

type ErrorKind string

type Event struct {
	Version      string
	Type         EventType
	RunID        string
	RequestID    string
	SessionID    string
	Turn         int
	Sequence     int64
	Timestamp    time.Time
	TraceID      string
	SpanID       string
	ParentSpanID string

	// State 是运行时**仍在演进的活状态指针**，仅在 emit 回调期间有效。
	// emit 为同步调用：sink 在回调内读取/Snapshot 是安全的；若需在回调返回后保留或
	// 异步读取，**必须先 State.Snapshot() 取独立副本**，否则与后续步边界写入构成 data race。
	// 只需标量视图（Turn/Final/计数）时优先用 StateSummary（已是安全的值拷贝）。
	State        *State
	StateSummary StateSummary
	Response     *llm.CompletionResponse
	Chunk        *llm.StreamChunk
	ToolCall     *llm.ToolCall
	ToolResult   *ToolResult
	Error        error
	RuntimeError *RuntimeError
	Metadata     map[string]any
	Payload      any
	Redaction    Redaction
}

type EventSink interface {
	Emit(ctx context.Context, event Event) error
}

type EventSinkFunc func(ctx context.Context, event Event) error

type EventType string

type JobProgress struct {
	// JobID 任务标识。
	JobID string `json:"job_id,omitempty"`
	// Stage 阶段名（queued/running/progress/preview/done/failed）。
	Stage string `json:"stage,omitempty"`
	// Percent 进度百分比 [0,100]，progress 阶段有效。
	Percent float64 `json:"percent,omitempty"`
	// Message 人类可读进度描述。
	Message string `json:"message,omitempty"`
	// Preview 阶段性预览（缩略图 URL / 部分结果等，任意可序列化值）。
	Preview any `json:"preview,omitempty"`
}

type Limits struct {
	MaxTurns int
}

type Memory interface {
	Search(ctx context.Context, query string, limit int) ([]MemoryEntry, error)
	Save(ctx context.Context, entry MemoryEntry) error
}

type MemoryEntry struct {
	Role    string
	Content string
}

type Middleware interface {
	BeforeLLM(ctx context.Context, state *State) error
	AfterLLM(ctx context.Context, state *State, resp *llm.CompletionResponse) error
	BeforeTool(ctx context.Context, state *State, call llm.ToolCall) error
	AfterTool(ctx context.Context, state *State, call llm.ToolCall, result ToolResult) error
	Finalize(ctx context.Context, state *State) error
}

type MiddlewareFuncSet struct {
	BeforeLLMFunc  func(context.Context, *State) error
	AfterLLMFunc   func(context.Context, *State, *llm.CompletionResponse) error
	BeforeToolFunc func(context.Context, *State, llm.ToolCall) error
	AfterToolFunc  func(context.Context, *State, llm.ToolCall, ToolResult) error
	FinalizeFunc   func(context.Context, *State) error
}

type NoopStrategy struct{}

type PendingTool struct {
	Call       llm.ToolCall   `json:"call"`
	SideEffect ToolSideEffect `json:"side_effect"`
}

type Permission interface {
	CheckTool(ctx context.Context, call llm.ToolCall) error
}

type Provider interface {
	Name() string
	Complete(ctx context.Context, req llm.CompletionRequest) (*llm.CompletionResponse, error)
	Stream(ctx context.Context, req llm.CompletionRequest) (*llm.Stream, error)
}

type ProviderSelection struct {
	Provider Provider
	Name     string
	Model    string
}

type ProviderSelector interface {
	Select(ctx context.Context, req Request) (ProviderSelection, error)
	Fallback(ctx context.Context, failed ProviderSelection, err error) (ProviderSelection, error)
}

type Redaction struct {
	Applied bool     `json:"applied,omitempty"`
	Fields  []string `json:"fields,omitempty"`
}

type Request struct {
	ID           string
	Messages     []llm.Message
	Tools        []llm.ToolDefinition
	ProviderName string
	ModelName    string
	Metadata     map[string]any
	Limits       Limits
	Strategy     Strategy
	StreamMode   StreamMode
}

type Result struct {
	Content   string
	Reasoning string
	ToolCalls []ToolCallRecord
	// Blocks 是本次运行的**有序内容块流**（text/tool_use/tool_result 按执行序交错），
	// 修复 Content 单串 + ToolCalls 扁平数组无法表达多步 text↔tool 交错的缺陷。
	// 客户端有此字段时按序渲染，否则回退 Content + ToolCalls。
	Blocks     template.Blocks
	Usage      llm.Usage
	Metadata   map[string]any
	StopReason StopReason
}

type Runner interface {
	Run(ctx context.Context, req Request) (*Result, error)
	Stream(ctx context.Context, req Request, sink EventSink) (*Result, error)
}

type RuntimeError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
	Cause   string `json:"cause,omitempty"`
}

type SSEEventSink struct {

	// 可选过滤器：返 false 跳过该事件不发给客户端。nil 表示全发。
	Filter func(event Event) bool
	// contains filtered or unexported fields
}

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

type SideEffectClassifier interface {
	SideEffectOf(call llm.ToolCall) ToolSideEffect
}

type Snapshot struct {
	// RunID 标识一次执行，同时作为持久化命名空间。
	RunID string `json:"run_id"`
	// Step 快照所在的步边界（对应 State.Turn）。
	Step int `json:"step"`
	// Messages 截至本步的消息历史。
	Messages []llm.Message `json:"messages"`
	// ToolCalls 截至本步已完成的工具调用记录。
	ToolCalls []ToolCallRecord `json:"tool_calls,omitempty"`
	// Usage 截至本步的累计 token 用量（计量维度）。
	Usage llm.Usage `json:"usage"`
	// Final 标记执行是否已得出最终答案。
	Final bool `json:"final,omitempty"`
	// FinalText 最终答案文本（Final 为真时有效）。
	FinalText string `json:"final_text,omitempty"`
	// Pending 非空表示这是一个「步内意图快照」：该步的工具调用已发起但尚未确认全部
	// 完成（崩溃窗口）。它记录这些工具的重放安全性，供 Resume 判定能否安全续跑——
	// 含 Unsafe 工具时 Resume fail-closed（ErrUnsafeReplay），全部可重放安全时重跑该步。
	// 步正常完成后的完成快照不带 Pending（同步号覆盖意图快照）。
	Pending []PendingTool `json:"pending,omitempty"`
}

type State struct {
	Request Request

	Messages  []llm.Message
	ToolCalls []ToolCallRecord
	Usage     llm.Usage

	Turn       int
	Final      bool
	FinalText  string
	Reasoning  string
	Attributes map[string]any
	// contains filtered or unexported fields
}

type StateSummary struct {
	Turn      int  `json:"turn"`
	Final     bool `json:"final"`
	Messages  int  `json:"messages"`
	ToolCalls int  `json:"tool_calls"`
}

type StaticProviderSelector struct {
	Provider Provider
	Name     string
	Model    string
}

type StopReason string

type Strategy interface {
	Name() string
	BuildSystemPrefix(ctx context.Context, req Request) string
	BeforeTurn(ctx context.Context, state *State) error
	AfterLLM(ctx context.Context, state *State) error
	ShouldContinue(ctx context.Context, state *State) bool
	Finalize(ctx context.Context, state *State) error
}

type StreamMode string

type ToolCallRecord struct {
	ID        string
	Name      string
	Arguments string
	Result    ToolResult
}

type ToolExecutor interface {
	Execute(ctx context.Context, call llm.ToolCall) (ToolResult, error)
}

type ToolResult struct {
	Content string
	Raw     any
	Error   string
	// Status 是执行结果状态（success / error），由框架在执行点据 execErr 与
	// tool.Result.Success 判定。零值（空串）表示未填充——老快照/老路径向后兼容。
	Status ToolStatus `json:"status,omitempty"`
	// DurationMs 是工具执行耗时（毫秒），由框架在执行点 time.Since 测量。
	DurationMs int64 `json:"duration_ms,omitempty"`
}

type ToolSideEffect int

type ToolStatus string