execution

type ChunkMetadata struct {
	// 序列信息
	Sequence  int64     `json:"sequence"`  // 序列号
	Timestamp time.Time `json:"timestamp"` // 时间戳
	Source    string    `json:"source"`    // 数据源

	// 进度信息
	Progress float64       `json:"progress,omitempty"` // 进度百分比 (0-100)
	Current  int64         `json:"current,omitempty"`  // 当前处理项
	Total    int64         `json:"total,omitempty"`    // 总项数
	ETA      time.Duration `json:"eta,omitempty"`      // 预计剩余时间

	// 状态信息
	Status string `json:"status,omitempty"` // 状态描述
	Phase  string `json:"phase,omitempty"`  // 处理阶段

	// 性能信息
	Latency    time.Duration `json:"latency,omitempty"`    // 延迟
	Throughput float64       `json:"throughput,omitempty"` // 吞吐量

	// 扩展信息
	Extra map[string]interface{} `json:"extra,omitempty"` // 额外元数据
}

type ChunkTransformFunc func(*LegacyStreamChunk) (*LegacyStreamChunk, error)

type ChunkType string

type LegacyStreamChunk struct {
	// 数据类型
	Type ChunkType `json:"type"` // 数据类型

	// 数据内容
	Data interface{} `json:"data"`           // 实际数据
	Text string      `json:"text,omitempty"` // 文本数据（仅 Type=ChunkTypeText 时）

	// 元数据
	Metadata ChunkMetadata `json:"metadata"` // 元数据

	// 控制信息
	IsLast bool  `json:"is_last"`         // 是否是最后一个块
	Error  error `json:"error,omitempty"` // 错误信息（如果有）
}

type Runtime[C any, S state.State] struct {
	// Context holds user-defined application context
	Context C

	// State holds the agent's current state
	State S

	// Store provides long-term persistent storage
	Store store.Store

	// Checkpointer handles session state persistence
	Checkpointer checkpoint.Checkpointer

	// ToolCallID is the unique identifier for the current tool call
	ToolCallID string

	// SessionID is the unique identifier for the current session/thread
	SessionID string

	// Timestamp is when this runtime was created
	Timestamp time.Time

	// Metadata holds additional runtime metadata
	Metadata map[string]interface{}
}

type RuntimeConfig struct {
	// EnableAutoSave automatically saves state after tool execution
	EnableAutoSave bool

	// SaveInterval specifies how often to auto-save state (if enabled)
	SaveInterval time.Duration

	// MaxStateSize limits the maximum state size in bytes
	MaxStateSize int64

	// EnableMetrics enables runtime metrics collection
	EnableMetrics bool
}

type RuntimeManager[C any, S state.State] struct {
	// contains filtered or unexported fields
}

type RuntimeMetrics struct {
	// TotalToolCalls is the total number of tool calls executed
	TotalToolCalls int64

	// TotalStateUpdates is the total number of state updates
	TotalStateUpdates int64

	// TotalStorageOperations is the total number of storage operations
	TotalStorageOperations int64

	// TotalCheckpoints is the total number of checkpoints saved
	TotalCheckpoints int64

	// LastToolCall is the timestamp of the last tool call
	LastToolCall time.Time

	// LastStateUpdate is the timestamp of the last state update
	LastStateUpdate time.Time

	// AverageToolLatency is the average tool execution latency
	AverageToolLatency time.Duration
}

type StreamConsumer interface {
	// OnChunk 处理数据块
	OnChunk(chunk *LegacyStreamChunk) error

	// OnStart 流开始时调用
	OnStart() error

	// OnComplete 流完成时调用
	OnComplete() error

	// OnError 发生错误时调用
	OnError(err error) error
}

type StreamController interface {
	// Pause 暂停流
	Pause() error

	// Resume 恢复流
	Resume() error

	// Cancel 取消流
	Cancel() error

	// Status 获取流状态
	Status() *StreamStatus

	// IsRunning 检查流是否运行中
	IsRunning() bool

	// IsPaused 检查流是否暂停
	IsPaused() bool
}

type StreamMultiplexer interface {
	// AddConsumer 添加消费者
	AddConsumer(consumer StreamConsumer) (id string, err error)

	// RemoveConsumer 移除消费者
	RemoveConsumer(id string) error

	// Consumers 返回所有消费者
	Consumers() []string

	// Start 开始多路复用
	Start(ctx context.Context, source StreamOutput) error

	// Close 关闭多路复用器
	Close() error
}

type StreamOptions struct {
	// 缓冲配置
	BufferSize   int  `json:"buffer_size,omitempty"`   // 缓冲区大小（块数）
	EnableBuffer bool `json:"enable_buffer,omitempty"` // 是否启用缓冲

	// 超时配置
	ChunkTimeout  time.Duration `json:"chunk_timeout,omitempty"`  // 单个块的超时
	StreamTimeout time.Duration `json:"stream_timeout,omitempty"` // 整个流的超时

	// 重试配置
	MaxRetries   int           `json:"max_retries,omitempty"`    // 最大重试次数
	RetryDelay   time.Duration `json:"retry_delay,omitempty"`    // 重试延迟
	RetryOnError bool          `json:"retry_on_error,omitempty"` // 错误时是否重试

	// 背压控制
	EnableBackpressure bool `json:"enable_backpressure,omitempty"` // 是否启用背压
	BackpressureWindow int  `json:"backpressure_window,omitempty"` // 背压窗口大小
	MaxPendingChunks   int  `json:"max_pending_chunks,omitempty"`  // 最大待处理块数

	// 流控制
	EnableThrottle  bool          `json:"enable_throttle,omitempty"`    // 是否启用限流
	MaxChunksPerSec float64       `json:"max_chunks_per_sec,omitempty"` // 最大块速率
	MinChunkDelay   time.Duration `json:"min_chunk_delay,omitempty"`    // 最小块间隔

	// 监控配置
	EnableProgress   bool          `json:"enable_progress,omitempty"`   // 是否发送进度更新
	ProgressInterval time.Duration `json:"progress_interval,omitempty"` // 进度更新间隔

	// 转换配置
	EnableTransform bool               `json:"enable_transform,omitempty"` // 是否启用数据转换
	TransformFunc   ChunkTransformFunc `json:"-"`                          // 数据转换函数

	// 多路复用
	EnableMultiplex bool `json:"enable_multiplex,omitempty"` // 是否支持多个消费者
	MaxConsumers    int  `json:"max_consumers,omitempty"`    // 最大消费者数

	// 内存保护
	MaxCollectSize int64 `json:"max_collect_size,omitempty"` // Collect/CollectText 最大字节数限制（默认 100MB），防止 OOM
}

type StreamOutput interface {
	// Next 读取下一个数据块
	// 返回 io.EOF 表示流结束
	Next() (*LegacyStreamChunk, error)

	// Close 关闭流并释放资源
	Close() error

	// IsClosed 检查流是否已关闭
	IsClosed() bool

	// Context 返回流的上下文
	Context() context.Context
}

type StreamState string

type StreamStatus struct {
	State       StreamState   `json:"state"`                // 流状态
	ChunksRead  int64         `json:"chunks_read"`          // 已读取块数
	BytesRead   int64         `json:"bytes_read"`           // 已读取字节数
	StartTime   time.Time     `json:"start_time"`           // 开始时间
	ElapsedTime time.Duration `json:"elapsed_time"`         // 已用时间
	Progress    float64       `json:"progress"`             // 进度百分比
	ErrorCount  int           `json:"error_count"`          // 错误计数
	LastError   error         `json:"last_error,omitempty"` // 最后的错误
}

type StreamWriter interface {
	io.Writer

	// WriteChunk 写入数据块
	WriteChunk(chunk *LegacyStreamChunk) error

	// WriteBatch 批量写入数据块
	WriteBatch(chunks []*LegacyStreamChunk) error

	// WriteText 写入文本数据
	WriteText(text string) error

	// WriteProgress 写入进度更新
	WriteProgress(progress float64, message string) error

	// WriteStatus 写入状态更新
	WriteStatus(status string) error

	// WriteError 写入错误信息
	WriteError(err error) error

	// Close 关闭写入器并标记流结束
	Close() error

	// IsClosed 检查写入器是否已关闭
	IsClosed() bool
}

type StreamingAgent interface {
	// ExecuteStream 以流式方式执行 Agent 逻辑
	// 返回一个可以持续读取输出块的 StreamOutput
	ExecuteStream(ctx context.Context, input interface{}) (StreamOutput, error)
}

type ToolFunc[I, O, C any, S state.State] func(ctx context.Context, input I, runtime *Runtime[C, S]) (O, error)

type ToolWithRuntime[I, O, C any, S state.State] struct {
	// contains filtered or unexported fields
}