workflow

type CancellationRecord struct {
	RunID      string                 `json:"run_id"`
	Reason     string                 `json:"reason"`
	StepID     string                 `json:"step_id,omitempty"`
	Snapshot   map[string]interface{} `json:"snapshot,omitempty"`
	OccurredAt time.Time              `json:"occurred_at"`
}

type Condition struct {
	ID        string
	Name      string
	Condition ConditionFunc
	TrueNode  Node
	FalseNode Node
}

type ConditionConfig struct {
	ID        string
	Name      string
	Condition ConditionFunc
	TrueNode  Node
	FalseNode Node
}

type ConditionFunc func(ctx *ExecutionContext) bool

type Config struct {
	ID     string
	Name   string
	Steps  []Node
	Logger *slog.Logger

	// EnableHistory enables workflow history tracking
	// EnableHistory 启用工作流历史跟踪
	EnableHistory bool `json:"enable_history"`

	// HistoryStore is the storage backend for workflow history
	// HistoryStore 是工作流历史的存储后端
	HistoryStore WorkflowStorage `json:"-"`

	// NumHistoryRuns is the number of recent runs to include in history context
	// NumHistoryRuns 是历史上下文中包含的最近运行数量
	NumHistoryRuns int `json:"num_history_runs"`

	// AddHistoryToSteps automatically adds history context to all steps
	// AddHistoryToSteps 自动将历史上下文添加到所有步骤
	AddHistoryToSteps bool `json:"add_history_to_steps"`
}

type ExecutionContext struct {
	// Input is the input for the workflow execution
	// Input 是工作流执行的输入
	Input string `json:"input"`

	// Output is the output from the workflow execution
	// Output 是工作流执行的输出
	Output string `json:"output"`

	// Data holds temporary execution data
	// Data 保存临时执行数据
	Data map[string]interface{} `json:"data"`

	// Metadata holds additional metadata
	// Metadata 保存额外的元数据
	Metadata map[string]interface{} `json:"metadata"`

	// SessionState holds session-level state that persists across steps
	// SessionState 保存跨步骤持久化的会话级状态
	SessionState *SessionState `json:"session_state,omitempty"`

	// SessionID is the unique session identifier
	// SessionID 是唯一的会话标识符
	SessionID string `json:"session_id,omitempty"`

	// UserID is the user identifier for multi-tenant scenarios
	// UserID 是多租户场景的用户标识符
	UserID string `json:"user_id,omitempty"`

	// WorkflowHistory contains recent workflow run history
	// WorkflowHistory 包含最近的工作流运行历史
	WorkflowHistory []HistoryEntry `json:"workflow_history,omitempty"`

	// HistoryContext is the formatted history context string
	// HistoryContext 是格式化的历史上下文字符串
	HistoryContext string `json:"history_context,omitempty"`
}

type HistoryEntry struct {
	// Input is the input for this history entry
	// Input 是此历史条目的输入
	Input string `json:"input"`

	// Output is the output for this history entry
	// Output 是此历史条目的输出
	Output string `json:"output"`

	// Timestamp is when this entry was created
	// Timestamp 是此条目创建的时间
	Timestamp time.Time `json:"timestamp"`
}

type HistoryFormatOptions struct {
	// Header is the opening tag for history context
	// Header 是历史上下文的开始标签
	Header string

	// Footer is the closing tag for history context
	// Footer 是历史上下文的结束标签
	Footer string

	// IncludeInput controls whether to include input in history
	// IncludeInput 控制是否在历史中包含输入
	IncludeInput bool

	// IncludeOutput controls whether to include output in history
	// IncludeOutput 控制是否在历史中包含输出
	IncludeOutput bool

	// IncludeTimestamp controls whether to include timestamps
	// IncludeTimestamp 控制是否包含时间戳
	IncludeTimestamp bool

	// InputLabel is the label for input field
	// InputLabel 是输入字段的标签
	InputLabel string

	// OutputLabel is the label for output field
	// OutputLabel 是输出字段的标签
	OutputLabel string
}

type Loop struct {
	ID           string
	Name         string
	Body         Node
	Condition    LoopConditionFunc
	MaxIteration int
}

type LoopConditionFunc func(ctx *ExecutionContext, iteration int) bool

type LoopConfig struct {
	ID           string
	Name         string
	Body         Node
	Condition    LoopConditionFunc
	MaxIteration int
}

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

type Node interface {
	Execute(ctx context.Context, input *ExecutionContext) (*ExecutionContext, error)
	GetID() string
	GetType() NodeType
}

type NodeType string

type Parallel struct {
	ID    string
	Name  string
	Nodes []Node
}

type ParallelConfig struct {
	ID    string
	Name  string
	Nodes []Node
}

type Router struct {
	ID     string
	Name   string
	Router RouterFunc
	Routes map[string]Node
}

type RouterConfig struct {
	ID     string
	Name   string
	Router RouterFunc
	Routes map[string]Node
}

type RouterFunc func(ctx *ExecutionContext) string

type RunOption func(*runOptions)

type RunStatus string

type SessionFilter struct {
	// WorkflowID filters sessions by workflow ID
	// WorkflowID 按工作流 ID 过滤会话
	WorkflowID string

	// UserID filters sessions by user ID
	// UserID 按用户 ID 过滤会话
	UserID string

	// CreatedAfter filters sessions created after this time
	// CreatedAfter 过滤在此时间之后创建的会话
	CreatedAfter time.Time

	// CreatedBefore filters sessions created before this time
	// CreatedBefore 过滤在此时间之前创建的会话
	CreatedBefore time.Time

	// Limit is the maximum number of sessions to return (0 = no limit)
	// Limit 是要返回的最大会话数（0 = 无限制）
	Limit int

	// Offset is the number of sessions to skip
	// Offset 是要跳过的会话数
	Offset int
}

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

type SessionStats struct {
	// TotalSessions is the total number of sessions
	// TotalSessions 是会话的总数
	TotalSessions int

	// TotalRuns is the total number of workflow runs across all sessions
	// TotalRuns 是所有会话中工作流运行的总数
	TotalRuns int

	// CompletedRuns is the number of completed runs
	// CompletedRuns 是已完成运行的数量
	CompletedRuns int

	// SuccessfulRuns is the number of successful runs
	// SuccessfulRuns 是成功运行的数量
	SuccessfulRuns int

	// FailedRuns is the number of failed runs
	// FailedRuns 是失败运行的数量
	FailedRuns int

	// AverageDuration is the average duration of completed runs
	// AverageDuration 是已完成运行的平均持续时间
	AverageDuration time.Duration
}

type Step struct {
	ID          string
	Name        string
	Agent       *agent.Agent
	Description string
	// contains filtered or unexported fields
}

type StepConfig struct {
	ID          string
	Name        string
	Agent       *agent.Agent
	Description string

	// AddHistoryToStep enables/disables history for this step
	// nil means inherit from workflow
	// AddHistoryToStep 为此步骤启用/禁用历史
	// nil 表示从 workflow 继承
	AddHistoryToStep *bool `json:"add_history_to_step,omitempty"`

	// NumHistoryRuns specifies history count for this step
	// nil means use workflow default
	// NumHistoryRuns 指定此步骤的历史数量
	// nil 表示使用 workflow 默认值
	NumHistoryRuns *int `json:"num_history_runs,omitempty"`
}

type StorageStats interface {
	// GetStats returns statistics about the stored sessions
	// GetStats 返回有关存储会话的统计信息
	GetStats(ctx context.Context) (*SessionStats, error)

	// GetWorkflowStats returns statistics for a specific workflow
	// GetWorkflowStats 返回特定工作流的统计信息
	GetWorkflowStats(ctx context.Context, workflowID string) (*SessionStats, error)
}

type Workflow struct {
	ID    string
	Name  string
	Steps []Node
	// contains filtered or unexported fields
}

type WorkflowHistoryConfig struct {
	// AddHistoryToSteps enables automatic history injection to all steps
	// AddHistoryToSteps 启用自动向所有步骤注入历史
	AddHistoryToSteps bool `json:"add_history_to_steps"`

	// NumHistoryRuns is the default number of history runs to include
	// NumHistoryRuns 是默认包含的历史运行数量
	NumHistoryRuns int `json:"num_history_runs"`
}

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

type WorkflowRun struct {
	// RunID is the unique identifier for this run
	// RunID 是此次运行的唯一标识符
	RunID string `json:"run_id"`

	// SessionID is the session this run belongs to
	// SessionID 是此次运行所属的会话 ID
	SessionID string `json:"session_id"`

	// WorkflowID is the ID of the workflow that was executed
	// WorkflowID 是被执行的工作流的 ID
	WorkflowID string `json:"workflow_id"`

	// Input is the input provided to the workflow
	// Input 是提供给工作流的输入
	Input string `json:"input"`

	// Output is the final output of the workflow
	// Output 是工作流的最终输出
	Output string `json:"output"`

	// Messages contains the conversation history for this run
	// Messages 包含此次运行的对话历史
	Messages []*types.Message `json:"messages,omitempty"`

	// Status indicates the current status of the run
	// Status 表示运行的当前状态
	Status RunStatus `json:"status"`

	// Error contains error message if the run failed
	// Error 包含运行失败时的错误信息
	Error string `json:"error,omitempty"`

	// StartedAt is the timestamp when the run started
	// StartedAt 是运行开始的时间戳
	StartedAt time.Time `json:"started_at"`

	// CompletedAt is the timestamp when the run completed
	// CompletedAt 是运行完成的时间戳
	CompletedAt time.Time `json:"completed_at,omitempty"`

	// Metadata contains additional metadata for this run
	// Metadata 包含此次运行的额外元数据
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// CancellationReason provides context when run is cancelled.
	CancellationReason string `json:"cancellation_reason,omitempty"`

	// CancellationSnapshot stores the last known snapshot before cancellation.
	CancellationSnapshot map[string]interface{} `json:"cancellation_snapshot,omitempty"`

	// LastStepID indicates the last step identifier processed before cancellation/failure.
	LastStepID string `json:"last_step_id,omitempty"`

	// ResumedFrom records the step the run resumed from, if applicable.
	ResumedFrom string `json:"resumed_from,omitempty"`

	// Events captures structured run output events for observability.
	Events run.Events `json:"events,omitempty"`
}

type WorkflowSession struct {

	// SessionID is the unique identifier for this session
	// SessionID 是此会话的唯一标识符
	SessionID string `json:"session_id"`

	// WorkflowID is the ID of the workflow this session belongs to
	// WorkflowID 是此会话所属工作流的 ID
	WorkflowID string `json:"workflow_id"`

	// UserID is the user who owns this session
	// UserID 是拥有此会话的用户
	UserID string `json:"user_id,omitempty"`

	// Runs contains all workflow runs in this session
	// Runs 包含此会话中的所有工作流运行
	Runs []*WorkflowRun `json:"runs"`

	// CreatedAt is the timestamp when the session was created
	// CreatedAt 是会话创建的时间戳
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is the timestamp when the session was last updated
	// UpdatedAt 是会话最后更新的时间戳
	UpdatedAt time.Time `json:"updated_at"`

	// Metadata contains additional session metadata
	// Metadata 包含额外的会话元数据
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Cancellations captures cancellation snapshots for later recovery.
	Cancellations []*CancellationRecord `json:"cancellations,omitempty"`
	// contains filtered or unexported fields
}

type WorkflowStorage interface {
	// CreateSession creates a new workflow session
	// CreateSession 创建新的工作流会话
	// Returns ErrSessionExists if a session with the same ID already exists
	// 如果具有相同 ID 的会话已存在则返回 ErrSessionExists
	CreateSession(ctx context.Context, sessionID, workflowID, userID string) (*WorkflowSession, error)

	// GetSession retrieves a workflow session by ID
	// GetSession 通过 ID 检索工作流会话
	// Returns ErrSessionNotFound if the session does not exist
	// 如果会话不存在则返回 ErrSessionNotFound
	GetSession(ctx context.Context, sessionID string) (*WorkflowSession, error)

	// UpdateSession updates an existing workflow session
	// UpdateSession 更新现有的工作流会话
	// Returns ErrSessionNotFound if the session does not exist
	// 如果会话不存在则返回 ErrSessionNotFound
	UpdateSession(ctx context.Context, session *WorkflowSession) error

	// DeleteSession deletes a workflow session by ID
	// DeleteSession 通过 ID 删除工作流会话
	// Returns ErrSessionNotFound if the session does not exist
	// 如果会话不存在则返回 ErrSessionNotFound
	DeleteSession(ctx context.Context, sessionID string) error

	// ListSessions lists all sessions for a given workflow
	// ListSessions 列出给定工作流的所有会话
	// Returns empty slice if no sessions found
	// 如果未找到会话则返回空切片
	ListSessions(ctx context.Context, workflowID string, limit, offset int) ([]*WorkflowSession, error)

	// ListUserSessions lists all sessions for a given user
	// ListUserSessions 列出给定用户的所有会话
	// Returns empty slice if no sessions found
	// 如果未找到会话则返回空切片
	ListUserSessions(ctx context.Context, userID string, limit, offset int) ([]*WorkflowSession, error)

	// Clear removes all sessions older than the specified duration
	// Clear 删除早于指定持续时间的所有会话
	Clear(ctx context.Context, olderThan time.Duration) (int, error)

	// Close closes the storage and releases any resources
	// Close 关闭存储并释放任何资源
	Close() error
}