workflow

type AgentConfig struct {
	Provider      string              `yaml:"provider"`       // agent provider: claude, codex, gemini, opencode, openai_compatible
	Prompt        string              `yaml:"prompt"`         // prompt template with {{inputs.*}} and {{states.*}} (single mode) or initial prompt (conversation mode)
	PromptFile    string              `yaml:"prompt_file"`    // path to external prompt template file (mutually exclusive with Prompt)
	Options       map[string]any      `yaml:"options"`        // provider-specific options (model, temperature, max_tokens, etc.)
	Timeout       int                 `yaml:"timeout"`        // seconds, 0 = use DefaultAgentTimeout
	Mode          string              `yaml:"mode"`           // execution mode: "single" (default) or "conversation"
	SystemPrompt  string              `yaml:"system_prompt"`  // system prompt preserved across conversation (conversation mode only)
	InitialPrompt string              `yaml:"initial_prompt"` // first user message in conversation mode (overrides Prompt if set)
	Conversation  *ConversationConfig `yaml:"conversation"`   // conversation-specific configuration (conversation mode only)
	OutputFormat  OutputFormat        `yaml:"output_format"`  // output post-processing: json (strip fences + validate), text (strip fences only), or empty (no processing)
}

type AgentResult struct {
	Provider        string         // provider name used
	Output          string         // raw output from agent CLI
	Response        map[string]any // parsed JSON response (if applicable)
	Tokens          int            // token usage (if reported by provider)
	TokensEstimated bool           // true if Tokens is an estimation, false if actual count
	Error           error          // execution error, if any
	StartedAt       time.Time
	CompletedAt     time.Time
	Conversation    *ConversationResult // conversation-specific result (conversation mode only)
}

type AuditEvent struct {
	SchemaVersion   int            `json:"schema_version"`
	Event           string         `json:"event"`
	Timestamp       time.Time      `json:"timestamp"`
	ExecutionID     string         `json:"execution_id"`
	User            string         `json:"user"`
	WorkflowName    string         `json:"workflow_name"`
	Inputs          map[string]any `json:"inputs,omitempty"`
	InputsTruncated bool           `json:"inputs_truncated,omitempty"`
	Status          string         `json:"status,omitempty"`
	ExitCode        *int           `json:"exit_code,omitempty"`
	DurationMs      *int64         `json:"duration_ms,omitempty"`
	Error           string         `json:"error,omitempty"`
}

type BranchResult struct {
	Name        string
	Output      string
	Stderr      string
	ExitCode    int
	Error       error
	StartedAt   time.Time
	CompletedAt time.Time
}

type CallWorkflowConfig struct {
	Workflow string            `yaml:"workflow"` // workflow name to invoke
	Inputs   map[string]string `yaml:"inputs"`   // parent var → sub-workflow input template
	Outputs  map[string]string `yaml:"outputs"`  // sub-workflow output → parent var name
	Timeout  int               `yaml:"timeout"`  // seconds, 0 = inherit from step
}

type CaptureConfig struct {
	Stdout   string // variable name to store stdout
	Stderr   string // variable name to store stderr
	MaxSize  string // max bytes (e.g., "10MB")
	Encoding string // e.g., "utf-8"
}

type CircularTemplateError struct {
	Chain []string // chain of template names forming the cycle
}

type ContextWindowManager interface {
	ApplyStrategy(turns []Turn, maxTokens int, strategy ContextWindowStrategy) ([]Turn, bool, error)
	PreserveSystemPrompt(turns []Turn) (*Turn, []Turn)
	CalculateTotalTokens(turns []Turn) int
	EstimateTokens(content string) int
}

type ContextWindowState struct {
	Strategy        ContextWindowStrategy
	TruncationCount int
	TurnsDropped    int
	TokensDropped   int
	LastTruncatedAt int
}

type ContextWindowStrategy string

type ConversationConfig struct {
	MaxTurns         int                   // maximum number of turns (default 10, max 100)
	MaxContextTokens int                   // maximum tokens in context window (0 = provider default)
	Strategy         ContextWindowStrategy // context window management strategy
	StopCondition    string                // expression to evaluate for early exit
	ContinueFrom     string                // step name to continue conversation from
	InjectContext    string                // additional context to inject mid-conversation
}

type ConversationResult struct {
	Provider        string             // provider name used
	State           *ConversationState // final conversation state
	Output          string             // final assistant response (last turn)
	Response        map[string]any     // parsed JSON response from last turn (if applicable)
	TokensInput     int                // total input tokens across all turns
	TokensOutput    int                // total output tokens across all turns
	TokensTotal     int                // sum of input + output tokens
	TokensEstimated bool               // true if token counts are estimates
	Error           error              // execution error, if any
	StartedAt       time.Time
	CompletedAt     time.Time
}

type ConversationState struct {
	SessionID   string     // provider-assigned session identifier for resume capability
	Turns       []Turn     // ordered array of conversation turns
	TotalTurns  int        // total number of turns executed
	TotalTokens int        // cumulative token count across all turns
	StoppedBy   StopReason // reason the conversation stopped
}

type DryRunAgent struct {
	Provider       string
	ResolvedPrompt string
	CLICommand     string
	Options        map[string]any
	Timeout        int
	OutputFormat   OutputFormat
}

type DryRunCapture struct {
	Stdout  string
	Stderr  string
	MaxSize string
}

type DryRunHook struct {
	Type    string
	Content string
}

type DryRunHooks struct {
	Pre  []DryRunHook
	Post []DryRunHook
}

type DryRunInput struct {
	Name     string
	Value    any
	Default  bool
	Required bool
}

type DryRunLoop struct {
	Type           string
	Items          string
	Condition      string
	Body           []string
	MaxIterations  int
	BreakCondition string
	OnComplete     string
}

type DryRunPlan struct {
	WorkflowName string
	Description  string
	Inputs       map[string]DryRunInput
	Steps        []DryRunStep
}

type DryRunRetry struct {
	MaxAttempts        int
	InitialDelayMs     int
	MaxDelayMs         int
	Backoff            string
	Multiplier         float64
	Jitter             float64
	RetryableExitCodes []int
}

type DryRunStep struct {
	Name            string
	Type            StepType
	Description     string
	Command         string
	ScriptFile      string
	Dir             string
	Hooks           DryRunHooks
	Transitions     []DryRunTransition
	Timeout         int
	Retry           *DryRunRetry
	Capture         *DryRunCapture
	ContinueOnError bool
	Branches        []string
	Strategy        string
	MaxConcurrent   int
	Loop            *DryRunLoop
	Status          TerminalStatus
	Agent           *DryRunAgent
}

type DryRunTransition struct {
	Condition string
	Target    string
	Type      string
}

type EvaluatorFunc func(expr string) (bool, error)

type ExecutionContext struct {
	WorkflowID   string
	WorkflowName string
	Status       ExecutionStatus
	CurrentStep  string
	ExitCode     int // process exit code propagated from terminal steps (FR-004)
	Inputs       map[string]any
	States       map[string]StepState
	Env          map[string]string
	StartedAt    time.Time
	UpdatedAt    time.Time
	CompletedAt  time.Time
	CurrentLoop  *LoopContext // current loop iteration context (nil when not in a loop)
	CallStack    []string     // active workflow names for circular detection (F023)
	// contains filtered or unexported fields
}

type ExecutionRecord struct {
	ID           string
	WorkflowID   string
	WorkflowName string
	Status       string // success, failed, cancelled
	ExitCode     int
	StartedAt    time.Time
	CompletedAt  time.Time
	DurationMs   int64
	ErrorMessage string
}

type ExecutionStatus string

type ExpressionCompiler func(expression string) error

type HistoryFilter struct {
	WorkflowName string
	Status       string
	Since        time.Time
	Until        time.Time
	Limit        int
}

type HistoryStats struct {
	TotalExecutions int
	SuccessCount    int
	FailedCount     int
	CancelledCount  int
	AvgDurationMs   int64
}

type Hook []HookAction

type HookAction struct {
	Log     string
	Command string
}

type Input struct {
	Name        string
	Type        string // string, integer, boolean
	Description string
	Required    bool
	Default     any
	Validation  *InputValidation // validation rules
}

type InputValidation struct {
	Pattern       string   // regex pattern for strings
	Enum          []string // allowed values
	Min           *int     // minimum for integers
	Max           *int     // maximum for integers
	FileExists    bool     // file must exist
	FileExtension []string // allowed file extensions
}

type InteractiveAction string

type InteractiveResult struct {
	StepName   string          // executed step name
	Status     ExecutionStatus // completion status
	Output     string          // stdout
	Stderr     string          // stderr
	ExitCode   int             // process exit code
	DurationMs int64           // execution duration in milliseconds
	NextStep   string          // next step to execute
	WasSkipped bool            // true if step was skipped
	WasRetried bool            // true if this was a retry
	RetryCount int             // number of retries attempted
}

type InteractiveStepInfo struct {
	Name        string   // step name
	Index       int      // 1-based step index
	Total       int      // total steps discovered
	Step        *Step    // reference to the step definition
	Command     string   // resolved command (with interpolation)
	Transitions []string // formatted transition descriptions
}

type IterationResult struct {
	Index       int
	Item        any // for for_each
	StepResults map[string]*StepState
	Error       error
	StartedAt   time.Time
	CompletedAt time.Time
}

type LoopConfig struct {
	Type                       LoopType          // for_each or while
	Items                      string            // template expression for items (for_each)
	Condition                  string            // expression to evaluate (while)
	Body                       []string          // step names to execute each iteration
	MaxIterations              int               // safety limit (default: 100, max: 10000)
	MaxIterationsExpr          string            // dynamic expression for max_iterations (e.g., "{{inputs.limit}}")
	MaxIterationsExplicitlySet bool              // true if max_iterations was explicitly set in YAML (even if zero)
	BreakCondition             string            // optional early exit expression
	OnComplete                 string            // next state after loop completes
	MemoryConfig               *LoopMemoryConfig // C019: Rolling window memory management
}

type LoopContext struct {
	Item   any          // current item value (for_each)
	Index  int          // 0-based iteration index
	First  bool         // true on first iteration
	Last   bool         // true on last iteration (for_each only)
	Length int          // total items count (for_each only, -1 for while)
	Parent *LoopContext // reference to enclosing loop (F043: nested loops)
}

type LoopMemoryConfig struct {
	MaxRetainedIterations int // 0 = keep all (default for backward compatibility)
}

type LoopResult struct {
	Iterations  []IterationResult
	TotalCount  int
	BrokeAt     int    // -1 if completed normally, index if break triggered
	NextStep    string // F048 T007: Target step when loop exits early via transition
	StartedAt   time.Time
	CompletedAt time.Time

	// C019: Memory management fields
	PrunedCount int // Number of iterations pruned from memory (for rolling window)
}

type LoopType string

type MissingParameterError struct {
	TemplateName  string   // template name
	ParameterName string   // missing parameter name
	Required      []string // list of all required parameters
}

type OutputFormat string

type OutputLimits struct {
	MaxSize           int64  // Max bytes per output field (0 = unlimited)
	StreamLargeOutput bool   // If true, stream to file; if false, truncate
	TempDir           string // Directory for temp files
}

type ParallelConfig struct {
	Strategy      ParallelStrategy
	MaxConcurrent int
}

type ParallelResult struct {
	Results      map[string]*BranchResult
	FirstError   error
	SuccessCount int
	FailureCount int
	StartedAt    time.Time
	CompletedAt  time.Time
}

type ParallelStrategy string

type ReferenceType string

type RetryConfig struct {
	MaxAttempts        int     // max retry attempts (default: 1)
	InitialDelayMs     int     // initial delay in milliseconds
	MaxDelayMs         int     // max delay in milliseconds
	Backoff            string  // constant, linear, exponential
	Multiplier         float64 // for exponential backoff
	Jitter             float64 // ± randomization (0.0-1.0)
	RetryableExitCodes []int   // exit codes to retry on
}

type RuntimeContext struct {
	Inputs   map[string]any
	States   map[string]RuntimeStepState
	Workflow RuntimeWorkflowData
	Env      map[string]string
	Context  RuntimeContextData
	Error    *RuntimeErrorData
	Loop     *RuntimeLoopData
}

type RuntimeContextData struct {
	WorkingDir string
	User       string
	Hostname   string
}

type RuntimeErrorData struct {
	Message  string
	State    string
	ExitCode int
	Type     string
}

type RuntimeLoopData struct {
	Item   any
	Index  int
	First  bool
	Last   bool
	Length int
	Parent *RuntimeLoopData
}

type RuntimeStepState struct {
	Output   string
	Stderr   string
	ExitCode int
	Status   string
}

type RuntimeWorkflowData struct {
	ID           string
	Name         string
	CurrentState string
	StartedAt    time.Time
}

type SlidingWindowStrategy struct{}

type StateReferenceError struct {
	StepName        string
	ReferencedState string
	AvailableStates []string
	Field           string // "initial", "on_success", "on_failure", "transition", "loop_body", "on_complete"
}

type Step struct {
	Name            string
	Type            StepType
	Description     string
	Command         string               // for command type
	ScriptFile      string               // F064: external script file (XOR with Command)
	Dir             string               // working directory for command execution
	Operation       string               // F021: plugin operation name (e.g., "slack.send")
	OperationInputs map[string]any       // F021: plugin operation input parameters
	Branches        []string             // for parallel type
	Strategy        string               // for parallel: all_succeed, any_succeed, best_effort
	MaxConcurrent   int                  // for parallel: max concurrent branches
	Timeout         int                  // seconds
	OnSuccess       string               // next state name (legacy, use Transitions)
	OnFailure       string               // next state name (legacy, use Transitions)
	Transitions     Transitions          // conditional transitions (takes precedence over OnSuccess/OnFailure)
	DependsOn       []string             // for ordering in parallel execution
	Retry           *RetryConfig         // retry configuration
	Capture         *CaptureConfig       // output capture configuration
	Hooks           StepHooks            // pre/post hooks
	ContinueOnError bool                 // don't fail workflow on error
	Status          TerminalStatus       // for terminal type: success or failure
	Message         string               // for terminal type: message template (interpolated at runtime)
	ExitCode        int                  // for terminal type: process exit code (FR-004: inline default 1)
	Loop            *LoopConfig          // for for_each and while types
	TemplateRef     *WorkflowTemplateRef // template reference (for use_template steps)
	CallWorkflow    *CallWorkflowConfig  // for call_workflow type: sub-workflow configuration
	Agent           *AgentConfig         // for agent type: AI agent configuration
	Config          map[string]any       // C069: plugin-provided step type configuration
}

type StepHooks struct {
	Pre  Hook
	Post Hook
}

type StepState struct {
	Name        string
	Status      ExecutionStatus
	Output      string
	Stderr      string
	ExitCode    int
	Attempt     int
	Error       string
	StartedAt   time.Time
	CompletedAt time.Time
	Response    map[string]any // parsed JSON response from agent steps
	JSON        any            // parsed JSON output when output_format: json is specified (map[string]any or []any)
	// F033: Conversation mode fields
	Conversation       *ConversationState  // conversation history and state (nil for non-conversation steps)
	TokensUsed         int                 // total tokens used in conversation mode
	ContextWindowState *ContextWindowState // context window management state (nil if not applicable)

	// C019: Output streaming fields for memory management
	OutputPath string // Path to temp file if output was streamed (empty if in-memory)
	StderrPath string // Path to temp file if stderr was streamed (empty if in-memory)
	Truncated  bool   // True if output was truncated (not streamed)

	// C069: Structured output from custom step types, accessible via {{states.step_name.Data.key}}
	Data map[string]any
}

type StepType string

type StepTypeChecker func(typeName string) bool

type StopReason string

type SubWorkflowResult struct {
	WorkflowName string         // name of the executed sub-workflow
	Outputs      map[string]any // mapped output values
	Error        error          // execution error, if any
	StartedAt    time.Time
	CompletedAt  time.Time
}

type SummarizeStrategy struct{}

type Template struct {
	Name       string
	Parameters []TemplateParam
	States     map[string]*Step
}

type TemplateAnalyzer interface {
	// ExtractReferences parses a template string and returns all interpolation references.
	ExtractReferences(template string) ([]TemplateReference, error)
}

type TemplateNotFoundError struct {
	TemplateName string // name of the missing template
	ReferencedBy string // file or step that referenced it
}

type TemplateParam struct {
	Name     string
	Required bool
	Default  any
}

type TemplateReference struct {
	Type      ReferenceType // namespace type (inputs, states, etc.)
	Namespace string        // first path segment (e.g., "inputs")
	Path      string        // full dot-separated path (e.g., "name" for inputs.name)
	Property  string        // property being accessed (e.g., "output" for states.step.output)
	Raw       string        // original template string (e.g., "{{inputs.name}}")
}

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

type TerminalStatus string

type Transition struct {
	When string
	Goto string
}

type Transitions []Transition

type TruncateMiddleStrategy struct{}

type Turn struct {
	Role    TurnRole // system, user, or assistant
	Content string   // message content
	Tokens  int      // token count for this turn
}

type TurnRole string

type ValidationCode string

type ValidationError struct {
	Level   ValidationLevel
	Code    ValidationCode
	Message string
	Path    string // e.g., "states.validate.on_success"
}

type ValidationLevel string

type ValidationResult struct {
	Errors   []ValidationError
	Warnings []ValidationError
}

type VisitState string

type Workflow struct {
	Name        string
	Description string
	Version     string
	Author      string
	Tags        []string
	Inputs      []Input
	Env         []string          // required environment variables
	Initial     string            // initial state name
	Steps       map[string]*Step  // state name -> step
	Hooks       WorkflowHooks     // workflow-level hooks
	Plugins     map[string]string // alias → manifest name (e.g. "pg" → "database")
	SourceDir   string            // workflow file directory for path resolution (runtime metadata)
}

type WorkflowHooks struct {
	WorkflowStart  Hook
	WorkflowEnd    Hook
	WorkflowError  Hook
	WorkflowCancel Hook
}

type WorkflowTemplateRef struct {
	TemplateName string
	Parameters   map[string]any
}