core

type ApprovalConfig struct {
	// Prompt is the message displayed to the approver.
	Prompt string `json:"prompt,omitempty"`
	// Input is the list of expected input field names from the approver.
	Input []string `json:"input,omitempty"`
	// Required is the subset of Input fields that must be provided.
	Required []string `json:"required,omitempty"`
	// RewindTo is the step name or ID to restart from on push-back.
	// When empty, push-back re-executes the approval step itself.
	RewindTo string `json:"rewindTo,omitempty"`
}

type ArtifactsConfig struct {
	Enabled bool   `json:"enabled"`
	Dir     string `json:"dir,omitempty"`
}

type AuthConfig struct {
	// Username for registry authentication
	Username string `json:"username,omitempty"`
	// Password for registry authentication
	Password string `json:"password,omitempty"`
	// Auth can be used instead of username/password for pre-encoded credentials
	// This should be base64(username:password)
	Auth string `json:"auth,omitempty"`
}

type BastionConfig struct {
	// Host is the bastion host address.
	Host string `json:"host,omitempty"`
	// Port is the bastion SSH port. Default is "22".
	Port string `json:"port,omitempty"`
	// User is the bastion SSH user.
	User string `json:"user,omitempty"`
	// Key is the path to the SSH private key for the bastion.
	Key string `json:"key,omitempty"`
	// Password is the SSH password for the bastion.
	Password string `json:"password,omitempty"`
}

type CommandEntry struct {
	// Command is the executable name or path.
	Command string `json:"command"`
	// Args contains the arguments for the command.
	Args []string `json:"args,omitempty"`
	// CmdWithArgs is the original command string for display purposes.
	CmdWithArgs string `json:"cmdWithArgs,omitempty"`
}

type Condition struct {
	Condition string // Condition to evaluate
	Eval      string // Dynamic value to evaluate
	Expected  string // Expected value
	Negate    bool   // Negate the condition result (run when condition does NOT match)
	// contains filtered or unexported fields
}

type Container struct {
	// Exec specifies an existing container name to exec into.
	// Mutually exclusive with Image.
	Exec string `yaml:"exec,omitempty"`
	// Name is the container name to use. If empty, Docker generates a random name.
	Name string `yaml:"name,omitempty"`
	// Image is the container image to use.
	Image string `yaml:"image,omitempty"`
	// PullPolicy is the policy to pull the image (e.g., "Always", "IfNotPresent").
	PullPolicy PullPolicy `yaml:"pull_policy,omitempty"`
	// Env specifies environment variables for the container.
	// Serialized to JSON so it can be restored when ReadDAG deserializes from
	// the stored DAGDefinition file.
	Env []string `yaml:"env,omitempty" json:"env,omitempty"` // List of environment variables in "key=value" format
	// Volumes specifies the volumes to mount in the container.
	Volumes []string `yaml:"volumes,omitempty"` // Map of volume names to volume definitions
	// User is the user to run the container as.
	User string `yaml:"user,omitempty"` // User to run the container as
	// WorkingDir is the working directory inside the container.
	WorkingDir string `yaml:"working_dir,omitempty"` // Working directory inside the container
	// Platform specifies the platform for the container (e.g., "linux/amd64").
	Platform string `yaml:"platform,omitempty"` // Platform for the container
	// Ports specifies the ports to expose from the container.
	Ports []string `yaml:"ports,omitempty"` // List of ports to expose
	// Network is the network configuration for the container.
	Network string `yaml:"network,omitempty"` // Network configuration for the container
	// KeepContainer is the flag to keep the container after the DAG run.
	KeepContainer bool `yaml:"keep_container,omitempty"` // Keep the container after the DAG run
	// Startup determines how the DAG-level container starts up.
	// One of: "keepalive" (default), "entrypoint", "command".
	Startup ContainerStartup `yaml:"startup,omitempty"`
	// Command is used when Startup == "command".
	Command []string `yaml:"command,omitempty"`
	// WaitFor determines readiness gate before steps run: "running" (default) or "healthy".
	WaitFor ContainerWaitFor `yaml:"wait_for,omitempty"`
	// LogPattern optionally waits for a regex to appear in container logs before proceeding.
	LogPattern string `yaml:"log_pattern,omitempty"`
	// RestartPolicy applies Docker restart policy for long-running containers ("no", "always", or "unless-stopped").
	RestartPolicy string `yaml:"restart_policy,omitempty"`
	// Healthcheck specifies a custom healthcheck for the container.
	// If specified with waitFor: healthy, this healthcheck is used instead of
	// relying on the image's built-in healthcheck.
	Healthcheck *Healthcheck `yaml:"healthcheck,omitempty"`
	// Shell specifies the shell wrapper for executing step commands.
	// When specified, all step commands are wrapped with this shell.
	// Format: ["/bin/bash", "-o", "errexit", "-o", "xtrace", "-c"]
	// The step command will be appended as the final argument.
	// Works in both exec mode and image mode.
	Shell []string `yaml:"shell,omitempty"`
}

type ContainerRuntime string

type ContainerStartup string

type ContainerWaitFor string

type ContinueOn struct {
	Failure     bool     `json:"failure,omitempty"`     // Failure is the flag to continue to the next step on failure.
	Skipped     bool     `json:"skipped,omitempty"`     // Skipped is the flag to continue to the next step on skipped.
	ExitCode    []int    `json:"exitCode,omitempty"`    // ExitCode is the list of exit codes to continue to the next step.
	Output      []string `json:"output,omitempty"`      // Output is the list of output (stdout/stderr) to continue to the next step.
	MarkSuccess bool     `json:"markSuccess,omitempty"` // MarkSuccess is the flag to mark the step as success when the condition is met.
}

type ControllerTask struct {
	// Name identifies the task. It is unique within the DAG.
	Name string `json:"name"`
	// Description states the completion criteria in natural language.
	Description string `json:"description,omitempty"`
}

type DAG struct {
	// WorkingDir is the working directory to run the DAG.
	// Default value is the directory of DAG file.
	// Relative paths are resolved at build time; variables are expanded at runtime.
	// Supports environment variable templates (e.g., ${MY_DIR}).
	WorkingDir string `json:"workingDir,omitempty"`
	// WorkingDirExplicit is true when WorkingDir was explicitly set in YAML,
	// base config, or via DefaultWorkingDir option. When false, WorkingDir
	// was auto-defaulted by the loader to the DAG file's parent directory.
	// Not serialized — runtime-only flag.
	WorkingDirExplicit bool `json:"-"`
	// Location is the absolute path to the DAG file.
	// It is used to generate unix socket name and can be blank
	Location string `json:"location,omitempty"`
	// SourceFile is the original DAG file path this run was loaded from.
	// Unlike Location, it is provenance-only and is preserved even when queued
	// execution clears or rewrites runtime locations.
	SourceFile string `json:"sourceFile,omitempty"`
	// Group is the group name of the DAG. This is optional.
	Group string `json:"group,omitempty"`
	// Name is the name of the DAG. The default is the filename without the extension.
	Name string `json:"name,omitempty"`
	// Type is the execution type (graph, chain, or controller). Default is graph.
	Type string `json:"type,omitempty"`
	// Tasks are the goals a controller DAG must satisfy before it concludes.
	// Only meaningful when Type is TypeController.
	Tasks []ControllerTask `json:"tasks,omitempty"`
	// Shell is the default shell to use for all steps in this DAG.
	// If not specified, the system default shell is used.
	// Can be overridden at the step level.
	// Supports environment variable templates (e.g., ${MY_SHELL}).
	Shell string `json:"shell,omitempty"`
	// ShellArgs contains additional arguments to pass to the shell.
	// These are populated when Shell is specified as a string with arguments
	// (e.g., "bash -e") or as an array (e.g., ["bash", "-e"]).
	// Supports environment variable templates.
	ShellArgs []string `json:"shellArgs,omitempty"`
	// Dotenv is the path to the dotenv file. This is optional.
	Dotenv []string `json:"dotenv,omitempty"`
	// Labels contains the list of labels for the DAG. This is optional.
	Labels Labels `json:"labels,omitempty"`
	// Description is the description of the DAG. This is optional.
	Description string `json:"description,omitempty"`
	// Schedule configuration for starting, stopping, and restarting the DAG.
	Schedule []Schedule `json:"schedule,omitempty"`
	// StopSchedule contains the cron expressions for stopping the DAG.
	StopSchedule []Schedule `json:"stopSchedule,omitempty"`
	// RestartSchedule contains the cron expressions for restarting the DAG.
	RestartSchedule []Schedule `json:"restartSchedule,omitempty"`
	// SkipIfSuccessful indicates whether to skip the DAG if it was successful previously.
	// E.g., when the DAG has already been executed manually before the scheduled time.
	SkipIfSuccessful bool `json:"skipIfSuccessful,omitempty"`
	// CatchupWindow is the lookback horizon for missed cron intervals.
	// If set, enables catch-up on scheduler restart. If omitted, no catch-up.
	CatchupWindow time.Duration `json:"catchupWindow,omitempty"`
	// OverlapPolicy controls behavior when a new run is triggered while one is active.
	// Defaults to "skip". See OverlapPolicy constants for options.
	OverlapPolicy OverlapPolicy `json:"overlapPolicy,omitempty"`
	// Env contains a list of environment variables to be set before running the DAG.
	// Note: This field is evaluated at build time and may contain secrets.
	// It is excluded from JSON serialization to prevent secret leakage.
	Env []string `json:"-"`
	// Consts contains immutable values resolved while loading the DAG.
	Consts map[string]any `json:"consts,omitempty"`
	// EnvEvaluated reports whether Env is safe to reuse as resolved build env.
	EnvEvaluated bool `json:"-"`
	// PresolvedBuildEnv stores resolved DAG/base-config env entries needed to
	// rebuild the DAG from persisted YAML during retry/restart paths.
	// It is serialized with dag.json because direct retry/restart cannot rely on
	// parent-process transport once the original process has exited.
	PresolvedBuildEnv map[string]string `json:"presolvedBuildEnv,omitempty"`
	// LogDir is the directory where the logs are stored.
	LogDir string `json:"logDir,omitempty"`
	// Artifacts config controls optional DAG run artifact storage.
	Artifacts *ArtifactsConfig `json:"artifacts,omitempty"`
	// LogOutput specifies how stdout and stderr are handled in log files.
	// Can be "separate" (default) for separate .out and .err files,
	// or "merged" for a single combined .log file.
	LogOutput LogOutputMode `json:"logOutput,omitempty"`
	// DefaultParams contains the default parameters to be passed to the DAG.
	DefaultParams string `json:"defaultParams,omitempty"`
	// ParamDefs contains ordered parameter metadata derived from DAG params.
	// It is exposed to the API for typed UI rendering and validation hints.
	ParamDefs []ParamDef `json:"paramDefs,omitempty"`
	// ParamSchema contains the resolved JSON Schema for schema-backed DAG params
	// when that schema is safe for direct UI form rendering.
	ParamSchema json.RawMessage `json:"paramSchema,omitempty"`
	// Params contains the list of parameters to be passed to the DAG.
	// Note: This field is evaluated at build time and may contain secrets.
	// It is excluded from JSON serialization to prevent secret leakage.
	Params []string `json:"-"`
	// ParamsJSON contains the JSON representation of the resolved parameters.
	// When params were supplied as JSON, the original payload is preserved.
	// Steps can consume this via the DAG_PARAMS_JSON environment variable.
	// Note: This field is evaluated at build time and may contain secrets.
	// It is excluded from JSON serialization to prevent secret leakage.
	ParamsJSON string `json:"-"`
	// Steps contains the list of steps in the DAG.
	Steps []Step `json:"steps,omitempty"`
	// HandlerOn contains the steps to be executed on different events.
	HandlerOn HandlerOn `json:"handlerOn,omitzero"`
	// Preconditions contains the conditions to be met before running the DAG.
	Preconditions []*Condition `json:"preconditions,omitempty"`
	// SMTP contains the SMTP configuration.
	// Excluded from JSON: may contain password.
	SMTP *SMTPConfig `json:"-"`
	// ErrorMail contains the mail configuration for errors.
	ErrorMail *MailConfig `json:"errorMail,omitempty"`
	// InfoMail contains the mail configuration for informational messages.
	InfoMail *MailConfig `json:"infoMail,omitempty"`
	// WaitMail contains the mail configuration for wait status.
	WaitMail *MailConfig `json:"waitMail,omitempty"`
	// MailOn contains the conditions to send mail.
	MailOn *MailOn `json:"mailOn,omitempty"`
	// Timeout specifies the maximum execution time of the DAG task.
	Timeout time.Duration `json:"timeout,omitempty"`
	// Delay is the delay before starting the DAG.
	Delay time.Duration `json:"delay,omitempty"`
	// RestartWait is the time to wait before restarting the DAG.
	RestartWait time.Duration `json:"restartWait,omitempty"`
	// MaxActiveSteps specifies the maximum concurrent steps to run in an execution.
	MaxActiveSteps int `json:"maxActiveSteps,omitempty"`
	// MaxActiveRuns specifies the maximum number of concurrent dag-runs.
	// DEPRECATED: This field is ignored for local (DAG-based) queues.
	// For concurrency control, define a global queue in config and use the 'queue' field.
	MaxActiveRuns int `json:"maxActiveRuns,omitempty"`
	// MaxCleanUpTime is the maximum time to wait for cleanup when the DAG is stopped.
	MaxCleanUpTime time.Duration `json:"maxCleanUpTime,omitempty"`
	// HistRetentionDays is the number of days to keep the history of dag-runs.
	HistRetentionDays int `json:"histRetentionDays,omitempty"`
	// HistRetentionRuns is the number of dag-runs to keep in history.
	HistRetentionRuns int `json:"histRetentionRuns,omitempty"`
	// Queue is the name of the queue to assign this DAG to.
	Queue string `json:"queue,omitempty"`
	// RetryPolicy controls automatic DAG-level retry behavior for failed runs.
	RetryPolicy *DAGRetryPolicy `json:"retryPolicy,omitempty"`
	// WorkerSelector defines labels required for worker selection in distributed execution.
	// If specified, the DAG will only run on workers with matching labels.
	WorkerSelector map[string]string `json:"workerSelector,omitempty"`
	// ForceLocal forces the DAG to run locally even when the server default is distributed.
	// Set by worker_selector: local in the DAG spec.
	ForceLocal bool `json:"forceLocal,omitempty"`
	// MaxOutputSize is the maximum size of step output to capture in bytes.
	// Default is 1MB. Output exceeding this will return an error.
	MaxOutputSize int `json:"maxOutputSize,omitempty"`
	// OTel contains the OpenTelemetry configuration for the DAG.
	OTel *OTelConfig `json:"otel,omitempty"`
	// BuildErrors contains any errors encountered while building the DAG.
	BuildErrors []error `json:"-"`
	// BuildWarnings contains non-fatal warnings detected while building the DAG.
	BuildWarnings []string `json:"-"`
	// LocalDAGs contains DAGs defined in the same file, keyed by DAG name
	LocalDAGs map[string]*DAG `json:"localDAGs,omitempty"`
	// YamlData contains the raw YAML data of the DAG.
	YamlData []byte `json:"yamlData,omitempty"`
	// BaseConfigData contains the raw base config YAML content.
	// This is used to propagate base config through distributed execution
	// and sub-DAG chains, so workers don't need local base config files.
	BaseConfigData []byte `json:"baseConfigData,omitempty"`
	// Container contains the container definition for the DAG.
	Container *Container `json:"container,omitempty"`
	// RunConfig contains configuration for controlling user interactions during DAG runs.
	RunConfig *RunConfig `json:"runConfig,omitempty"`
	// Resources contains CPU and memory limits requested for this DAG run.
	Resources *Resources `json:"resources,omitempty"`
	// Webhook contains DAG-level webhook trigger behavior configuration.
	Webhook *WebhookConfig `json:"webhook,omitempty"`
	// RegistryAuths maps registry hostnames to authentication configs.
	// Optional: If not specified, falls back to DOCKER_AUTH_CONFIG or docker config.
	// Credentials are evaluated at runtime. Excluded from JSON: may contain passwords.
	RegistryAuths map[string]*AuthConfig `json:"-"`
	// SSH contains the default SSH configuration for the DAG.
	// Excluded from JSON: may contain password.
	SSH *SSHConfig `json:"-"`
	// S3 contains the default S3 configuration for the DAG.
	// Excluded from JSON: may contain credentials.
	S3 *S3Config `json:"-"`
	// LLM contains the default LLM configuration for the DAG.
	// Steps with type: chat inherit this configuration if they don't specify their own llm field.
	LLM *LLMConfig `json:"llm,omitempty"`
	// Redis contains the default Redis configuration for the DAG.
	// Steps with type: redis inherit this configuration.
	// Excluded from JSON: may contain password.
	Redis *RedisConfig `json:"-"`
	// Harness contains the default harness executor configuration for the DAG.
	// Steps with type: harness inherit this configuration.
	// Excluded from JSON: may contain API key references or provider-specific secrets.
	Harness *HarnessConfig `json:"-"`
	// Harnesses contains reusable custom harness definitions available to harness steps.
	// Excluded from JSON: derived from DAG/base config and rebuilt from YAML when needed.
	Harnesses HarnessDefinitions `json:"-"`
	// Kubernetes contains the default Kubernetes executor configuration for the DAG.
	// Steps with type: k8s or type: kubernetes inherit this configuration.
	// Excluded from JSON: may contain secret references.
	Kubernetes KubernetesConfig `json:"-"`
	// Secrets contains references to external secrets to be resolved at runtime.
	Secrets []SecretRef `json:"secrets,omitempty"`
	// Tools declares external CLI tools that must be installed before the DAG runs.
	Tools *ToolConfig `json:"tools,omitempty"`
	// contains filtered or unexported fields
}

type DAGRetryPolicy struct {
	// Limit is the maximum number of retry attempts allowed.
	Limit int `json:"limit,omitempty"`
	// Interval is the base delay before retrying.
	Interval time.Duration `json:"interval,omitempty"`
	// IntervalSecStr preserves the original interval string representation.
	IntervalSecStr string `json:"intervalSecStr,omitempty"`
	// Backoff is the retry delay multiplier. Zero keeps a fixed interval.
	Backoff float64 `json:"backoff,omitempty"`
	// MaxInterval caps the computed retry delay.
	MaxInterval time.Duration `json:"maxInterval,omitempty"`
}

type ErrorList []error

type ExecutorCapabilities struct {
	// Command indicates whether the executor supports the command field.
	Command bool
	// MultipleCommands indicates whether the executor supports multiple commands.
	MultipleCommands bool
	// Script indicates whether the executor supports the script field.
	Script bool
	// Shell indicates whether the executor uses shell/shellArgs/shellPackages.
	Shell bool
	// Container indicates whether the executor supports step-level container config.
	Container bool
	// SubDAG indicates whether the executor can execute sub-DAGs.
	SubDAG bool
	// WorkerSelector indicates whether the executor supports worker selection.
	WorkerSelector bool
	// LLM indicates whether the executor supports the llm field.
	LLM bool
	// CommandContext returns command execution facts for command field resolution.
	CommandContext func(ctx context.Context, step Step) cmnvalue.CommandContext
	// ScriptContext returns command execution facts for script field resolution.
	ScriptContext func(ctx context.Context, step Step) cmnvalue.CommandContext
}

type ExecutorConfig struct {
	// Type represents one of the registered executors.
	// See `executor.Register` in `internal/executor/executor.go`.
	Type   string         `json:"type,omitempty"`
	Config map[string]any `json:"config,omitempty"` // Config contains executor-specific configuration.
	// Metadata contains additional metadata for the executor that is not passed to the executor itself.
	// This is used internally for optimization purposes.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ForeachConfig struct {
	// Items is the static list of items to iterate.
	Items []any `json:"items,omitempty"`

	// ItemsExpr is a value-resolved expression that must produce a JSON array.
	ItemsExpr string `json:"itemsExpr,omitempty"`

	// As is the item alias exposed under the foreach namespace.
	As string `json:"as,omitempty"`

	// Key is an optional item key expression.
	Key string `json:"key,omitempty"`

	// MaxConcurrent is the maximum number of item bodies running at once.
	MaxConcurrent int `json:"maxConcurrent,omitempty"`

	// Steps is the item body graph.
	Steps []Step `json:"steps,omitempty"`

	// Collect maps output names to value-resolved expressions.
	Collect map[string]string `json:"collect,omitempty"`
}

type HandlerOn struct {
	Init    *Step `json:"init,omitempty"`
	Failure *Step `json:"failure,omitempty"`
	Success *Step `json:"success,omitempty"`
	Abort   *Step `json:"abort,omitempty"`
	Exit    *Step `json:"exit,omitempty"`
	Wait    *Step `json:"wait,omitempty"`
}

type HandlerType string

type HarnessConfig struct {
	// Config contains the primary provider selection and CLI flags.
	Config map[string]any `json:"-"`
	// Fallback contains ordered alternative provider configs tried on failure.
	Fallback []map[string]any `json:"-"`
}

type HarnessDefinition struct {
	Binary         string                `json:"binary,omitempty"`
	PrefixArgs     []string              `json:"prefixArgs,omitempty"`
	PromptMode     HarnessPromptMode     `json:"promptMode,omitempty"`
	PromptFlag     string                `json:"promptFlag,omitempty"`
	PromptPosition HarnessPromptPosition `json:"promptPosition,omitempty"`
	FlagStyle      HarnessFlagStyle      `json:"flagStyle,omitempty"`
	OptionFlags    map[string]string     `json:"optionFlags,omitempty"`
}

type HarnessDefinitions map[string]*HarnessDefinition

type HarnessFlagStyle string

type HarnessPromptMode string

type HarnessPromptPosition string

type Healthcheck struct {
	// Test is the command to run to check health. Must start with:
	// - ["NONE"] - disable healthcheck
	// - ["CMD", "command", "arg1", ...] - run command directly
	// - ["CMD-SHELL", "command"] - run command in shell
	Test []string `yaml:"test,omitempty"`
	// Interval is the time between health checks (e.g., "5s", "1m").
	Interval time.Duration `yaml:"interval,omitempty"`
	// Timeout is how long to wait for the health check to complete (e.g., "3s").
	Timeout time.Duration `yaml:"timeout,omitempty"`
	// StartPeriod is the grace period for the container to initialize (e.g., "10s").
	StartPeriod time.Duration `yaml:"start_period,omitempty"`
	// Retries is the number of consecutive failures needed to consider unhealthy.
	Retries int `yaml:"retries,omitempty"`
}

type HumanTaskConfig struct {
	Prompt string          `json:"prompt,omitempty"`
	Form   json.RawMessage `json:"form,omitempty"`
}

type KubernetesConfig map[string]any

type LLMConfig struct {
	// Provider is the LLM provider (openai, anthropic, gemini, openrouter, local).
	// Used for single model config (backward compatible).
	Provider string `json:"provider,omitempty"`
	// Model is the model to use (e.g., gpt-4o, claude-sonnet-4-6).
	// Used for single model config (backward compatible).
	Model string `json:"model,omitempty"`
	// Models is an array of models for fallback support.
	// First model is primary, rest are tried in order if primary fails.
	// When set, Provider/Model fields are ignored.
	Models []ModelEntry `json:"models,omitempty"`
	// System is the default system prompt for sessions.
	System string `json:"system,omitempty"`
	// Temperature controls randomness (0.0-2.0).
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens *int `json:"maxTokens,omitempty"`
	// TopP is the nucleus sampling parameter.
	TopP *float64 `json:"topP,omitempty"`
	// BaseURL is a custom API endpoint.
	BaseURL string `json:"baseURL,omitempty"`
	// APIKeyName is the name of the environment variable containing the API key.
	// If not specified, the default environment variable for the provider is used.
	APIKeyName string `json:"apiKeyName,omitempty"`
	// Stream enables or disables streaming output.
	// Default is true.
	Stream *bool `json:"stream,omitempty"`
	// Thinking enables extended thinking/reasoning mode.
	// Provider-specific: Anthropic uses budget_tokens, OpenAI uses reasoning.effort,
	// Gemini uses thinkingLevel/thinkingBudget, OpenRouter normalizes across providers.
	Thinking *ThinkingConfig `json:"thinking,omitempty"`
	// Tools is a list of DAG names to use as callable tools.
	// Tool names, descriptions, and parameters are auto-discovered from DAG definitions.
	// Example: ["search-tool", "analyzer-tool"]
	Tools []string `json:"tools,omitempty"`
	// MaxToolIterations limits the number of tool calling rounds.
	// Default is 10 if not specified.
	MaxToolIterations *int `json:"maxToolIterations,omitempty"`
	// WebSearch configures provider-native web search.
	WebSearch *WebSearchConfig `json:"webSearch,omitempty"`
}

type LLMMessage struct {
	// Role is the message role (system, user, assistant, tool).
	Role LLMRole `json:"role,omitempty"`
	// Content is the message content. Supports variable substitution with ${VAR}.
	Content string `json:"content,omitempty"`
}

type LLMRole string

type Label struct {
	Key   string `json:"key"`
	Value string `json:"value,omitempty"`
}

type LabelFilter struct {
	Type  LabelFilterType
	Key   string
	Value string
}

type LabelFilterType int

type Labels []Label

type LogOutputMode string

type MailConfig struct {
	From       string   `json:"from,omitempty"`
	To         []string `json:"to,omitempty"`
	Prefix     string   `json:"prefix,omitempty"`
	AttachLogs bool     `json:"attachLogs,omitempty"`
}

type MailOn struct {
	Failure bool `json:"failure,omitempty"`
	Success bool `json:"success,omitempty"`
	Wait    bool `json:"wait,omitempty"`
}

type ModelEntry struct {
	// Provider is the LLM provider for this model.
	Provider string `json:"provider"`
	// Name is the model name (e.g., gpt-4o, claude-sonnet-4-6).
	Name string `json:"name"`
	// Temperature overrides the shared temperature for this model.
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens overrides the shared maxTokens for this model.
	MaxTokens *int `json:"maxTokens,omitempty"`
	// TopP overrides the shared topP for this model.
	TopP *float64 `json:"topP,omitempty"`
	// BaseURL is a custom API endpoint for this model.
	BaseURL string `json:"baseURL,omitempty"`
	// APIKeyName overrides the API key environment variable for this model.
	APIKeyName string `json:"apiKeyName,omitempty"`
}

type NodeStatus int

type OTelConfig struct {
	Enabled  bool              `json:"enabled,omitempty"`
	Endpoint string            `json:"endpoint,omitempty"`
	Headers  map[string]string `json:"headers,omitempty"`
	Insecure bool              `json:"insecure,omitempty"`
	Timeout  time.Duration     `json:"timeout,omitempty"`
	Resource map[string]any    `json:"resource,omitempty"`
}

type OverlapPolicy string

type ParallelConfig struct {
	// Variable is the name of a variable that contains the json array of items to process in parallel.
	Variable string `json:"variable,omitempty"`

	// Items is the array of items to process in parallel.
	// Can be a direct array or a reference to a variable containing an array.
	Items []ParallelItem `json:"items,omitempty"`

	// MaxConcurrent is the maximum number of parallel executions.
	// Default is 10 if not specified.
	MaxConcurrent int `json:"max_concurrent,omitempty"`
}

type ParallelItem struct {
	// Value is used for simple string items or variable references
	// E.g. "item1", "item2", "${ITEM_VAR}"
	Value string `json:"value,omitempty"`

	// Params is used for key-value pairs that will be passed as parameters
	// E.g. {"SOURCE": "s3://customers", "TYPE": "csv"}
	// Uses DeterministicMap to ensure consistent JSON marshaling for hashing
	Params collections.DeterministicMap `json:"params,omitempty"`
}

type ParamDef struct {
	Name        string   `json:"name,omitempty"`
	Type        string   `json:"type,omitempty"`
	Default     any      `json:"default,omitempty"`
	Description string   `json:"description,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Enum        []any    `json:"enum,omitempty"`
	Minimum     *float64 `json:"minimum,omitempty"`
	Maximum     *float64 `json:"maximum,omitempty"`
	MinLength   *int     `json:"minLength,omitempty"`
	MaxLength   *int     `json:"maxLength,omitempty"`
	Pattern     *string  `json:"pattern,omitempty"`
}

type ParamType int

type Params struct {
	// Simple params (backward compatible)
	Simple map[string]string `json:"simple,omitempty"`

	// Rich params with type preservation
	Rich map[string]any `json:"rich,omitempty"`

	// Raw params for lazy parsing
	Raw json.RawMessage `json:"raw,omitempty"`
}

type PullPolicy int

type RedisConfig struct {
	// URL is the Redis connection URL (redis://user:pass@host:port/db).
	URL string `json:"url,omitempty"`
	// Host is the Redis host (alternative to URL).
	Host string `json:"host,omitempty"`
	// Port is the Redis port (default: 6379).
	Port int `json:"port,omitempty"`
	// Password is the authentication password.
	Password string `json:"password,omitempty"`
	// Username is the ACL username (Redis 6+).
	Username string `json:"username,omitempty"`
	// DB is the database number (0-15).
	DB int `json:"db,omitempty"`
	// TLS enables TLS connection.
	TLS bool `json:"tls,omitempty"`
	// TLSSkipVerify skips TLS certificate verification.
	TLSSkipVerify bool `json:"tlsSkipVerify,omitempty"`
	// Mode is the connection mode (standalone, sentinel, cluster).
	Mode string `json:"mode,omitempty"`
	// SentinelMaster is the sentinel master name.
	SentinelMaster string `json:"sentinelMaster,omitempty"`
	// SentinelAddrs is the list of sentinel addresses.
	SentinelAddrs []string `json:"sentinelAddrs,omitempty"`
	// ClusterAddrs is the list of cluster node addresses.
	ClusterAddrs []string `json:"clusterAddrs,omitempty"`
	// MaxRetries is the maximum number of retries.
	MaxRetries int `json:"maxRetries,omitempty"`
}

type ReferenceField struct {
	Path  string
	Value string

	OwnerStepName string
	OwnerStepID   string
	// OwnerStepPath is the spec path of the owning step, such as "steps[0]" or
	// "handler_on.exit". It is empty for DAG-level fields.
	OwnerStepPath string
	Field         cmnvalue.Field
	// contains filtered or unexported fields
}

type RepeatMode string

type RepeatPolicy struct {
	// RepeatMode determines if and how the step should be repeated.
	// It can be 'while' or 'until'.
	RepeatMode RepeatMode `json:"repeatMode,omitempty"`
	// Interval is the time to wait between repeats.
	Interval time.Duration `json:"interval,omitempty"`
	// IntervalStr is the string representation of interval_sec for deferred evaluation.
	IntervalStr string `json:"intervalStr,omitempty"`
	// Limit is the maximum number of times to repeat the step.
	Limit int `json:"limit,omitempty"`
	// LimitStr is the string representation of the limit for deferred evaluation.
	LimitStr string `json:"limitStr,omitempty"`
	// Backoff is the exponential backoff multiplier (e.g., 2.0 for doubling).
	Backoff float64 `json:"backoff,omitempty"`
	// MaxInterval is the maximum interval cap for exponential backoff.
	MaxInterval time.Duration `json:"maxInterval,omitempty"`
	// MaxIntervalStr is the string representation of max_interval_sec for deferred evaluation.
	MaxIntervalStr string `json:"maxIntervalStr,omitempty"`
	// Condition is the condition object to be met for the repeat.
	Condition *Condition `json:"condition,omitempty"`
	// ExitCode is the list of exit codes that should trigger a repeat.
	ExitCode []int `json:"exitCode,omitempty"`
}

type ResourceLimits struct {
	CPU    string `json:"cpu,omitempty"`
	Memory string `json:"memory,omitempty"`

	CPUMillis   int64 `json:"-"`
	MemoryBytes int64 `json:"-"`
}

type Resources struct {
	Limits *ResourceLimits `json:"limits,omitempty"`
}

type RetryPolicy struct {
	// Limit is the number of retries allowed.
	Limit int `json:"limit,omitempty"`
	// Interval is the time to wait between retries.
	Interval time.Duration `json:"interval,omitempty"`
	// LimitStr is the string representation of the limit.
	LimitStr string `json:"limitStr,omitempty"`
	// IntervalSecStr is the string representation of the interval.
	IntervalSecStr string `json:"intervalSecStr,omitempty"`
	// ExitCodes is the list of exit codes that should trigger a retry.
	ExitCodes []int `json:"exitCode,omitempty"`
	// Backoff is the exponential backoff multiplier (e.g., 2.0 for doubling).
	Backoff float64 `json:"backoff,omitempty"`
	// MaxInterval is the maximum interval cap for exponential backoff.
	MaxInterval time.Duration `json:"maxInterval,omitempty"`
}

type RouteEntry struct {
	Pattern string   `json:"pattern"` // Match pattern (exact or "re:regex")
	Targets []string `json:"targets"` // Step names to route to when pattern matches
}

type RouterConfig struct {
	Value  string       `json:"value"`  // Value expression to evaluate (e.g., "${STATUS}")
	Routes []RouteEntry `json:"routes"` // Ordered list of pattern → targets
}

type RunConfig struct {
	// DisableParamEdit when set to true, prevents users from editing parameters when starting a DAG.
	DisableParamEdit bool `json:"disableParamEdit,omitempty"`
	// DisableRunIdEdit when set to true, prevents users from specifying custom run IDs.
	DisableRunIdEdit bool `json:"disableRunIdEdit,omitempty"`
}

type S3Config struct {
	// Region is the AWS region (e.g., us-east-1).
	Region string `json:"region,omitempty"`
	// Endpoint is a custom S3-compatible endpoint URL.
	// Use this for S3-compatible services like MinIO, LocalStack, etc.
	Endpoint string `json:"endpoint,omitempty"`
	// AccessKeyID is the AWS access key ID.
	AccessKeyID string `json:"accessKeyId,omitempty"`
	// SecretAccessKey is the AWS secret access key.
	SecretAccessKey string `json:"secretAccessKey,omitempty"`
	// SessionToken is the AWS session token (for temporary credentials).
	SessionToken string `json:"sessionToken,omitempty"`
	// Profile is the AWS credentials profile name.
	Profile string `json:"profile,omitempty"`
	// ForcePathStyle enables path-style addressing (required for S3-compatible services).
	ForcePathStyle bool `json:"forcePathStyle,omitempty"`
	// DisableSSL disables SSL for the connection (for local testing only).
	DisableSSL bool `json:"disableSSL,omitempty"`
	// Bucket is the default S3 bucket name.
	// Can be overridden at the step level.
	Bucket string `json:"bucket,omitempty"`
}

type SMTPConfig struct {
	Host     string `json:"host,omitempty"`
	Port     string `json:"port,omitempty"`
	Username string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`
}

type SSHConfig struct {
	// User is the SSH user.
	User string `json:"user,omitempty"`
	// Host is the SSH host.
	Host string `json:"host,omitempty"`
	// Port is the SSH port. Default is "22".
	Port string `json:"port,omitempty"`
	// Key is the path to the SSH private key.
	Key string `json:"key,omitempty"`
	// Password is the SSH password.
	Password string `json:"password,omitempty"`
	// StrictHostKey enables strict host key checking. Defaults to true.
	StrictHostKey bool `json:"strictHostKey,omitempty"`
	// KnownHostFile is the path to the known_hosts file. Defaults to ~/.ssh/known_hosts.
	KnownHostFile string `json:"knownHostFile,omitempty"`
	// Shell is the shell to use for remote command execution.
	// If not specified, commands are executed directly without shell wrapping.
	Shell string `json:"shell,omitempty"`
	// ShellArgs contains additional arguments that should be passed to the shell executable.
	ShellArgs []string `json:"shellArgs,omitempty"`
	// Timeout is the connection timeout duration (e.g., "30s", "1m"). Defaults to 30s.
	Timeout string `json:"timeout,omitempty"`
	// Bastion is the jump host / bastion server configuration for connecting to the target host.
	Bastion *BastionConfig `json:"bastion,omitempty"`
}

type Schedule struct {
	// Kind identifies the schedule type.
	Kind ScheduleKind `json:"kind,omitempty"`
	// Expression is the cron expression.
	Expression string `json:"expression,omitempty"`
	// At is the canonical RFC 3339 timestamp for one-off schedules.
	At string `json:"at,omitempty"`
	// Profile is the runtime profile name that activates this schedule.
	Profile string `json:"profile,omitempty"`
	// Parsed is the parsed cron schedule.
	Parsed cron.Schedule `json:"-"`
	// AtTime is the parsed one-off schedule time.
	AtTime time.Time `json:"-"`
	// Warnings contains non-fatal schedule warnings.
	Warnings []string `json:"warnings,omitempty"`
}

type ScheduleKind string

type ScheduleParseOptions struct {
	AllowAt bool
}

type SecretRef struct {
	// Name is the environment variable name to set (required).
	Name string `json:"name"`
	// Ref is the workspace-local registry reference for a team-managed secret.
	Ref string `json:"ref,omitempty"`
	// Provider specifies the secret backend (e.g., "env", "file", "vault", "kubernetes").
	Provider string `json:"provider,omitempty"`
	// Key is the provider-specific identifier for a direct provider reference.
	Key string `json:"key,omitempty"`
	// Options contains provider-specific configuration (optional).
	Options map[string]string `json:"options,omitempty"`
}

type StartParamInput struct {
	DashArgs  []string
	RawParams string
}

type Status int

type Step struct {
	// ID is the optional unique identifier for the step.
	ID string `json:"id,omitempty"`
	// Name is the name of the step.
	Name string `json:"name"`
	// Description is the description of the step. This is optional.
	Description string `json:"description,omitempty"`
	// Shell is the shell program to execute the command. This is optional.
	Shell string `json:"shell,omitempty"`
	// ShellPackages is the list of packages to install. This is used only when the shell is `nix-shell`.
	ShellPackages []string `json:"shellPackages,omitempty"`
	// ShellArgs is the list of arguments for the shell program.
	ShellArgs []string `json:"shellArgs,omitempty"`
	// Dir is the working directory for the step.
	Dir string `json:"dir,omitempty"`
	// ExecutorConfig contains the configuration for the executor.
	ExecutorConfig ExecutorConfig `json:"executorConfig,omitzero"`
	// CmdWithArgs is the command with arguments for display purposes.
	// Deprecated: Use Commands[0].CmdWithArgs instead. Kept for JSON backward compatibility.
	CmdWithArgs string `json:"cmdWithArgs,omitempty"`
	// CmdArgsSys is the command with arguments for the system.
	// Deprecated: Kept for JSON backward compatibility.
	CmdArgsSys string `json:"cmdArgsSys,omitempty"`
	// Command specifies only the command without arguments.
	// Deprecated: Use Commands field instead. Kept for JSON backward compatibility.
	Command string `json:"command,omitempty"`
	// ShellCmdArgs is the shell command with arguments.
	ShellCmdArgs string `json:"shellCmdArgs,omitempty"`
	// Script is the script to be executed.
	Script string `json:"script,omitempty"`
	// Args contains the arguments for the command.
	// Deprecated: Use Commands field instead. Kept for JSON backward compatibility.
	Args []string `json:"args,omitempty"`
	// Commands is the source of truth for commands to execute.
	// Each entry represents a command to be executed sequentially.
	// For single commands, this will contain exactly one entry.
	Commands []CommandEntry `json:"commands,omitempty"`
	// Stdout is the file to store the standard output.
	Stdout string `json:"stdout,omitempty"`
	// StdoutArtifact is the artifact-relative file path to store standard output.
	StdoutArtifact string `json:"stdoutArtifact,omitempty"`
	// StdoutOutputs maps standard output into the DAG/action outputs object.
	StdoutOutputs *StepOutputsConfig `json:"stdoutOutputs,omitempty"`
	// Stderr is the file to store the standard error.
	Stderr string `json:"stderr,omitempty"`
	// StderrArtifact is the artifact-relative file path to store standard error.
	StderrArtifact string `json:"stderrArtifact,omitempty"`
	// LogOutput specifies how stdout and stderr are handled in log files for this step.
	// Overrides the DAG-level LogOutput setting. Empty string means inherit from DAG.
	LogOutput LogOutputMode `json:"logOutput,omitempty"`
	// Output is the variable name to store captured stdout.
	Output string `json:"output,omitempty"`
	// StructuredOutput publishes post-processed step-scoped outputs for ${step.output.*} access.
	StructuredOutput map[string]StepOutputEntry `json:"structuredOutput,omitempty"`
	// OutputSchema validates stdout JSON before publishing step-scoped output.
	OutputSchema map[string]any `json:"outputSchema,omitzero"`
	// Outputs declares file-based step outputs published through DAGU_OUTPUT_FILE.
	Outputs []StepOutputDeclaration `json:"outputs,omitempty"`
	// Depends contains the list of step names to depend on.
	Depends []string `json:"depends,omitempty"`
	// ExplicitlyNoDeps indicates the depends field was explicitly set to empty
	ExplicitlyNoDeps bool `json:"-"`
	// ContinueOn contains the conditions to continue on failure or skipped.
	ContinueOn ContinueOn `json:"continueOn,omitzero"`
	// RetryPolicy contains the retry policy for the step.
	RetryPolicy RetryPolicy `json:"retryPolicy,omitzero"`
	// RepeatPolicy contains the repeat policy for the step.
	RepeatPolicy RepeatPolicy `json:"repeatPolicy,omitzero"`
	// MailOnError is the flag to send mail on error.
	MailOnError bool `json:"mailOnError,omitempty"`
	// Preconditions contains the conditions to be met before running the step.
	Preconditions []*Condition `json:"preconditions,omitempty"`
	// SignalOnStop is the signal to send on stop.
	SignalOnStop string `json:"signalOnStop,omitempty"`
	// SubDAG contains the information about a sub DAG to be executed.
	SubDAG *SubDAG `json:"childDag,omitempty"`
	// WorkerSelector specifies required worker labels for execution.
	WorkerSelector map[string]string `json:"workerSelector,omitempty"`
	// Parallel contains the configuration for parallel execution.
	Parallel *ParallelConfig `json:"parallel,omitempty"`
	// Foreach contains the configuration for inline item-body iteration.
	Foreach *ForeachConfig `json:"foreach,omitempty"`
	// Env contains environment variables for the step.
	Env []string `json:"env,omitempty"`
	// Params contains parameters/inputs for the step.
	Params Params `json:"params,omitzero"`
	// Timeout specifies the maximum execution time for the step.
	// If set, this timeout takes precedence over the DAG-level timeout for this step.
	Timeout time.Duration `json:"timeout,omitempty"`
	// Container specifies the container configuration for this step.
	// If set, the step runs in its own container instead of the DAG-level container.
	// This uses the same configuration format as the DAG-level container field.
	Container *Container `json:"container,omitempty"`
	// LLM contains the configuration for LLM-based executors.
	// Used with explicit type: chat.
	LLM *LLMConfig `json:"llm,omitempty"`
	// Messages contains the session messages for chat executor.
	// Only used when type is "chat".
	Messages []LLMMessage `json:"messages,omitempty"`
	// Router contains the routing configuration for router-type steps.
	// Only used when type is "router".
	Router *RouterConfig `json:"router,omitempty"`
	// Approval configures a human approval gate after step execution.
	// When set, the step pauses in Waiting state after execution completes.
	Approval *ApprovalConfig `json:"approval,omitempty"`
	// HumanTask configures a processless step completed by a local operator.
	HumanTask *HumanTaskConfig `json:"humanTask,omitempty"`
}

type StepOutputDeclaration struct {
	Name string `json:"name"`
	Type string `json:"type,omitempty"`
}

type StepOutputEntry struct {
	// HasValue distinguishes literal/null values from source-based outputs.
	HasValue bool `json:"hasValue,omitempty"`
	// Value is the literal value to publish when HasValue is true.
	Value any `json:"value"`
	// From selects a runtime source to read from: stdout, stderr, or file.
	From string `json:"from,omitempty"`
	// Path is the file path used when From is file.
	Path string `json:"path,omitempty"`
	// Decode controls how the source content is decoded before selection.
	Decode string `json:"decode,omitempty"`
	// Select is an optional jq/gojq path applied after decode.
	Select string `json:"select,omitempty"`
}

type StepOutputsConfig struct {
	// Field writes the decoded stdout value to a single outputs field.
	Field string `json:"field,omitempty"`
	// Decode controls how stdout is decoded before writing outputs.
	Decode string `json:"decode,omitempty"`
	// Select is an optional jq/gojq path applied after decode.
	Select string `json:"select,omitempty"`
	// Fields maps individual outputs fields from stdout or literal values.
	Fields map[string]StepOutputEntry `json:"fields,omitempty"`
}

type StepValidator func(step Step) error

type SubDAG struct {
	Name   string `json:"name,omitempty"`
	Params string `json:"params,omitempty"`
}

type ThinkingConfig struct {
	// Enabled activates thinking mode for supported models.
	Enabled bool `json:"enabled,omitempty"`
	// Effort controls reasoning depth: low, medium, high, xhigh.
	// Maps to provider-specific parameters.
	Effort ThinkingEffort `json:"effort,omitempty"`
	// BudgetTokens sets explicit token budget (provider-specific).
	// For Anthropic: minimum 1024, max 128K.
	// For Gemini 2.5: range 128-32768.
	BudgetTokens *int `json:"budgetTokens,omitempty"`
	// IncludeInOutput includes thinking blocks in stdout.
	// Default is false for consistency across providers.
	IncludeInOutput bool `json:"includeInOutput,omitempty"`
}

type ThinkingEffort string

type ToolCall struct {
	// ID is the unique identifier for this tool call.
	ID string `json:"id"`
	// Name is the name of the tool to invoke (matches DAG name field).
	Name string `json:"name"`
	// Arguments contains the tool arguments as key-value pairs.
	Arguments map[string]any `json:"arguments"`
}

type ToolConfig struct {
	Provider string        `json:"provider,omitempty"`
	Registry *ToolRegistry `json:"registry,omitempty"`
	Packages []ToolPackage `json:"packages,omitempty"`
}

type ToolPackage struct {
	Name     string   `json:"name,omitempty"`
	Package  string   `json:"package"`
	Version  string   `json:"version"`
	Commands []string `json:"commands,omitempty"`
	Registry string   `json:"registry,omitempty"`
}

type ToolRegistry struct {
	Name      string `json:"name,omitempty"`
	Type      string `json:"type,omitempty"`
	RepoOwner string `json:"repoOwner,omitempty"`
	RepoName  string `json:"repoName,omitempty"`
	Ref       string `json:"ref,omitempty"`
	Path      string `json:"path,omitempty"`
}

type ToolResult struct {
	// ToolCallID is the ID of the tool call this result corresponds to.
	ToolCallID string `json:"tool_call_id"`
	// Name is the name of the tool that was executed.
	Name string `json:"name"`
	// Content is the result content from the tool execution.
	Content string `json:"content"`
	// Error contains any error message if the tool execution failed.
	Error string `json:"error,omitempty"`
}

type TriggerType int

type ValidationError struct {
	Field string
	Value any
	Err   error
}

type WebSearchConfig struct {
	// Enabled activates provider-native web search.
	Enabled bool `json:"enabled,omitempty"`
	// MaxUses limits search invocations per request.
	MaxUses *int `json:"maxUses,omitempty"`
	// AllowedDomains restricts results to these domains (Anthropic only).
	AllowedDomains []string `json:"allowedDomains,omitempty"`
	// BlockedDomains excludes results from these domains (Anthropic only).
	BlockedDomains []string `json:"blockedDomains,omitempty"`
	// UserLocation localizes search results.
	UserLocation *WebSearchUserLocation `json:"userLocation,omitempty"`
}

type WebSearchUserLocation struct {
	City     string `json:"city,omitempty"`
	Region   string `json:"region,omitempty"`
	Country  string `json:"country,omitempty"`
	Timezone string `json:"timezone,omitempty"`
}

type WebhookConfig struct {
	// ForwardHeaders is the allowlist of request headers to expose to
	// webhook-triggered DAG runs via the WEBHOOK_HEADERS runtime variable.
	ForwardHeaders []string `json:"forwardHeaders,omitempty"`
}