ir

type AgentInteraction struct {
	ID                      string                 `json:"id"`
	Kind                    AgentInteractionKind   `json:"kind"`
	Status                  AgentInteractionStatus `json:"status"`
	Permission              string                 `json:"permission,omitempty"`
	Patterns                []string               `json:"patterns,omitempty"`
	AllowForSessionPatterns []string               `json:"allowForSessionPatterns,omitempty"`
	Questions               []AgentQuestion        `json:"questions,omitempty"`
	Decision                string                 `json:"decision,omitempty"`
	Answers                 [][]string             `json:"answers,omitempty"`
	Applied                 bool                   `json:"applied,omitempty"`
	CreatedAt               string                 `json:"createdAt,omitempty"`
	ExpiresAt               string                 `json:"expiresAt,omitempty"`
	RespondedAt             string                 `json:"respondedAt,omitempty"`
	RespondedBy             string                 `json:"respondedBy,omitempty"`
	RespondedByID           string                 `json:"respondedById,omitempty"`
}

type AgentInteractionKind string

type AgentInteractionStatus string

type AgentPermissionGrant struct {
	Permission  string   `json:"permission"`
	Patterns    []string `json:"patterns"`
	GrantedAt   string   `json:"grantedAt,omitempty"`
	GrantedBy   string   `json:"grantedBy,omitempty"`
	GrantedByID string   `json:"grantedById,omitempty"`
}

type AgentQuestion struct {
	Header   string                `json:"header"`
	Question string                `json:"question"`
	Options  []AgentQuestionOption `json:"options,omitempty"`
	Multiple bool                  `json:"multiple,omitempty"`
	Custom   bool                  `json:"custom,omitempty"`
}

type AgentQuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

type AgentSession struct {
	Provider           string                 `json:"provider"`
	ProviderVersion    string                 `json:"providerVersion,omitempty"`
	SessionID          string                 `json:"sessionId,omitempty"`
	Generation         int                    `json:"generation,omitempty"`
	Agent              string                 `json:"agent,omitempty"`
	Model              string                 `json:"model,omitempty"`
	Variant            string                 `json:"variant,omitempty"`
	OwnerWorkerID      string                 `json:"ownerWorkerId,omitempty"`
	HostInstanceID     string                 `json:"hostInstanceId,omitempty"`
	Directory          string                 `json:"directory,omitempty"`
	State              AgentSessionState      `json:"state"`
	LastError          string                 `json:"lastError,omitempty"`
	PromptSent         bool                   `json:"promptSent,omitempty"`
	PromptMessageID    string                 `json:"promptMessageId,omitempty"`
	RestartPending     bool                   `json:"restartPending,omitempty"`
	SessionOwned       bool                   `json:"sessionOwned,omitempty"`
	DiscardedSessionID string                 `json:"discardedSessionId,omitempty"`
	DiscardedOwned     bool                   `json:"discardedOwned,omitempty"`
	PermissionGrants   []AgentPermissionGrant `json:"permissionGrants,omitempty"`
	Usage              AgentUsage             `json:"usage,omitzero"`
	Interactions       []AgentInteraction     `json:"interactions,omitempty"`
	Events             []AgentSessionEvent    `json:"events,omitempty"`
}

type AgentSessionEvent struct {
	Sequence  int64    `json:"sequence"`
	ID        string   `json:"id"`
	Type      string   `json:"type"`
	Timestamp string   `json:"timestamp,omitempty"`
	Role      string   `json:"role,omitempty"`
	Content   string   `json:"content,omitempty"`
	Name      string   `json:"name,omitempty"`
	Status    string   `json:"status,omitempty"`
	Files     []string `json:"files,omitempty"`
	// Position is the operation's place in with.do, from 1, as the run
	// log counts; 0 for an event that is not one operation.
	Position int `json:"position,omitempty"`
	// Via is how an operation ran: "element" when a recording was replayed
	// by the window's elements, "screen" when it was replayed by the
	// pixels of the screen, "model", or "exact" for a check that read the
	// window's elements without a model.
	Via string `json:"via,omitempty"`
	// DurationMs and Tokens are what the operation took.
	DurationMs int64 `json:"durationMs,omitempty"`
	Tokens     int64 `json:"tokens,omitempty"`
}

type AgentSessionResource struct {
	Provider      string `json:"provider"`
	SessionID     string `json:"sessionId"`
	Directory     string `json:"directory,omitempty"`
	OwnerWorkerID string `json:"ownerWorkerId,omitempty"`
	StepName      string `json:"stepName,omitempty"`
	Generation    int    `json:"generation,omitempty"`
}

type AgentSessionState string

type AgentTask 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 AgentUsage struct {
	InputTokens     int64   `json:"inputTokens,omitempty"`
	OutputTokens    int64   `json:"outputTokens,omitempty"`
	ReasoningTokens int64   `json:"reasoningTokens,omitempty"`
	TotalTokens     int64   `json:"totalTokens,omitempty"`
	Cost            float64 `json:"cost,omitempty"`
}

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 BuildDecision string

type BuildExecution struct {
	Decision           BuildDecision `json:"decision"`
	Phase              BuildPhase    `json:"phase"`
	Reason             BuildReason   `json:"reason"`
	Detail             string        `json:"detail,omitempty"`
	Fingerprint        string        `json:"fingerprint,omitempty"`
	MaterializationKey string        `json:"materializationKey,omitempty"`
	ProducerRun        DAGRunRef     `json:"producerRun,omitzero"`
	ProducerAttemptID  string        `json:"producerAttemptId,omitempty"`
}

type BuildPhase string

type BuildReason string

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 `json:"condition,omitempty"` // Condition to evaluate
	Eval      string `json:"eval,omitempty"`      // Dynamic value to evaluate
	Expected  string `json:"expected,omitempty"`  // Expected value
	// ExpectedAny lists alternative expected values, of which any one matching
	// satisfies the condition. When set, it is used instead of Expected.
	ExpectedAny []string `json:"expectedAny,omitempty"`
	Negate      bool     `json:"negate,omitempty"` // Negate the condition result (run when condition does NOT match)
}

type ConditionResult struct {
	Condition
	Error string `json:"error,omitempty"`
}

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
	// EnvFile lists dotenv-syntax files to load into the container
	// environment. File variables have lower precedence than Env entries.
	// Serialized to JSON like Env for DAGDefinition persistence.
	EnvFile []string `yaml:"env_file,omitempty" json:"env_file,omitempty"`
	// 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 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 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. Default is graph.
	Type string `json:"type,omitempty"`
	// Tasks are the goals an agent DAG must satisfy before it concludes.
	// Only meaningful when Type is TypeAgent.
	Tasks []AgentTask `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:"-"`
	// RootEnvSpan locates the DAG's own root env entries in Env when loading
	// resolved them. Base-config entries come before it, and entries added for
	// a run, such as dotenv values, come after it.
	RootEnvSpan EnvSpan `json:"-"`
	// RuntimeResolved reports whether dotenv resolution is complete for Env.
	RuntimeResolved 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:"-"`
	// MailAccounts contains the mail accounts used by mail actions.
	// Excluded from JSON: may contain passwords and tokens.
	MailAccounts MailAccounts `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"`
	// BaseConfigWorkspace identifies the workspace supplying base configuration.
	// An empty name selects global configuration; nil denotes unknown provenance.
	BaseConfigWorkspace *string `json:"baseConfigWorkspace,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.Ref `json:"secrets,omitempty"`
	// Tools declares external CLI tools that must be installed before the DAG runs.
	Tools *ToolConfig `json:"tools,omitempty"`
}

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 DAGRunCondition struct {
	Type      string `json:"type"`
	Status    string `json:"status"`
	Reason    string `json:"reason"`
	Message   string `json:"message"`
	CheckedAt string `json:"checkedAt"`
}

type DAGRunOutputs struct {
	Metadata OutputsMetadata   `json:"metadata"`
	Outputs  map[string]string `json:"outputs"`
}

type DAGRunRef struct {
	Name string `json:"name,omitempty"`
	ID   string `json:"id,omitempty"`
}

type DAGRunStatus struct {
	Root         DAGRunRef         `json:"root,omitzero"`
	Parent       DAGRunRef         `json:"parent,omitzero"`
	Name         string            `json:"name"`
	DAGRunID     string            `json:"dagRunId"`
	AttemptID    string            `json:"attemptId"`
	AttemptKey   string            `json:"attemptKey,omitempty"` // Globally unique attempt identifier
	ClaimKey     string            `json:"claimKey,omitempty"`   // Worker claim that executes this attempt
	Status       Status            `json:"status"`
	Conditions   []DAGRunCondition `json:"conditions,omitempty"`
	TriggerType  TriggerType       `json:"triggerType,omitempty"`
	TriggerActor string            `json:"triggerActor,omitempty"`
	// Resume marks a queued checkpoint resume. Retry planning honors it only
	// while the attempt is queued, so retries of finished runs reset as usual.
	Resume         bool                   `json:"resume,omitempty"`
	WorkerID       string                 `json:"workerId,omitempty"`
	PID            PID                    `json:"pid,omitempty"`
	PIDStartedAt   int64                  `json:"pidStartedAt,omitempty"`
	Nodes          []*Node                `json:"nodes,omitempty"`
	AgentSessions  []AgentSessionResource `json:"agentSessions,omitempty"`
	OnInit         *Node                  `json:"onInit,omitempty"`
	OnExit         *Node                  `json:"onExit,omitempty"`
	OnSuccess      *Node                  `json:"onSuccess,omitempty"`
	OnFailure      *Node                  `json:"onFailure,omitempty"`
	OnAbort        *Node                  `json:"onAbort,omitempty"`
	OnWait         *Node                  `json:"onWait,omitempty"`
	CreatedAt      int64                  `json:"createdAt,omitempty"`
	QueuedAt       string                 `json:"queuedAt,omitempty"`
	ScheduleTime   string                 `json:"scheduleTime,omitempty"`
	StartedAt      string                 `json:"startedAt,omitempty"`
	FinishedAt     string                 `json:"finishedAt,omitempty"`
	AutoRetryCount int                    `json:"autoRetryCount,omitempty"`
	AutoRetryLimit int                    `json:"autoRetryLimit,omitempty"`
	// AutoRetryInterval is stored as a duration snapshot for retry scanner decisions.
	AutoRetryInterval time.Duration `json:"autoRetryInterval,omitempty"`
	AutoRetryBackoff  float64       `json:"autoRetryBackoff,omitempty"`
	// AutoRetryMaxInterval is stored as a duration snapshot for retry scanner decisions.
	AutoRetryMaxInterval time.Duration `json:"autoRetryMaxInterval,omitempty"`
	ProcGroup            string        `json:"procGroup,omitempty"`
	DefinitionID         string        `json:"definitionId,omitempty"`
	// SuspendFlagName is retained for histories written before DefinitionID was introduced.
	SuspendFlagName    string                `json:"suspendFlagName,omitempty"`
	Log                string                `json:"log,omitempty"`
	WorkingDir         string                `json:"workingDir,omitempty"`
	ArchiveDir         string                `json:"archiveDir,omitempty"`
	Error              string                `json:"error,omitempty"`
	Params             string                `json:"params,omitempty"`
	ParamsList         []string              `json:"paramsList,omitempty"`
	ParallelItem       string                `json:"parallelItem,omitempty"`
	ProfileName        string                `json:"profileName,omitempty"`
	ProfileResolvedAt  string                `json:"profileResolvedAt,omitempty"`
	ProfileEntries     []RuntimeProfileEntry `json:"profileEntries,omitempty"`
	NoReuse            bool                  `json:"noReuse,omitempty"`
	PendingStepRetries []PendingStepRetry    `json:"pendingStepRetries"`
	Preconditions      []ConditionResult     `json:"preconditions,omitempty"`
	Labels             []string              `json:"labels,omitempty"`
	LeaseAt            int64                 `json:"leaseAt,omitempty"` // Unix millis; stamped by coordinator on observed run liveness
}

type EnvSpan struct {
	Start int
	End   int
}

type ErrorList []error

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 ForeachBodyStepStatus struct {
	Name       string     `json:"name"`
	ID         string     `json:"id,omitempty"`
	Status     NodeStatus `json:"status"`
	Error      string     `json:"error,omitempty"`
	StartedAt  string     `json:"startedAt,omitempty"`
	FinishedAt string     `json:"finishedAt,omitempty"`
	RetryCount int        `json:"retryCount,omitempty"`
	Stdout     string     `json:"stdout,omitempty"`
	Stderr     string     `json:"stderr,omitempty"`
	// Foreach marks a body step that is itself a foreach, whose items live
	// in a nested directory.
	Foreach bool `json:"foreach,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 ForeachItemRef struct {
	Index int    `json:"index"`
	Key   string `json:"key"`
}

type ForeachItemStatus struct {
	Index      int                     `json:"index"`
	Key        string                  `json:"key"`
	Status     NodeStatus              `json:"status"`
	Error      string                  `json:"error,omitempty"`
	StartedAt  string                  `json:"startedAt,omitempty"`
	FinishedAt string                  `json:"finishedAt,omitempty"`
	Steps      []ForeachBodyStepStatus `json:"steps"`
}

type ForeachItems struct {
	Total int              `json:"total"`
	Items []ForeachItemRef `json:"items"`
}

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 {
	Protocol          HarnessProtocol       `json:"protocol,omitempty"`
	Transport         HarnessTransport      `json:"transport,omitempty"`
	URL               string                `json:"url,omitempty"`
	CAFile            string                `json:"caFile,omitempty"`
	BearerSubprotocol bool                  `json:"bearerSubprotocol,omitempty"`
	Headers           map[string]string     `json:"headers,omitempty"`
	Cwd               string                `json:"cwd,omitempty"`
	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 HarnessProtocol string

type HarnessTransport 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"`
	Artifacts []string        `json:"artifacts,omitempty"`
	// PushBack lets the operator send the task back to an upstream step.
	// Nil means the task can only be completed.
	PushBack *HumanTaskPushBackConfig `json:"pushBack,omitempty"`
}

type HumanTaskPushBackConfig struct {
	// RewindTo is the name of the upstream step that runs again first.
	RewindTo string `json:"rewindTo"`
	// Form is the normalized feedback form. Empty means push-back accepts no
	// input.
	Form json.RawMessage `json:"form,omitempty"`
}

type InferredDependency struct {
	Step  string `json:"step"`
	Field string `json:"field,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"`
	// MaxContextTokens activates agent observation aging once a decision
	// prompt reaches this many tokens. Zero disables proactive aging.
	MaxContextTokens *int `json:"maxContextTokens,omitempty"`
	// ObservationMaxBytes limits the size of each agent observation. Zero
	// disables this limit.
	ObservationMaxBytes *int `json:"observationMaxBytes,omitempty"`
	// ObservationKeepRecent is the number of recent agent observations kept
	// in full after observation aging starts. Zero disables observation aging.
	ObservationKeepRecent *int `json:"observationKeepRecent,omitempty"`
	// WebSearch configures provider-native web search.
	WebSearch *WebSearchConfig `json:"webSearch,omitempty"`
}

type LLMMessage struct {
	Role       LLMRole             `json:"role"`
	Content    string              `json:"content"`
	ToolCallID string              `json:"tool_call_id,omitempty"`
	ToolCalls  []ToolCall          `json:"tool_calls,omitempty"`
	Metadata   *LLMMessageMetadata `json:"metadata,omitempty"`
}

type LLMMessageMetadata struct {
	Provider         string  `json:"provider,omitempty"`
	Model            string  `json:"model,omitempty"`
	PromptTokens     int     `json:"promptTokens,omitempty"`
	CompletionTokens int     `json:"completionTokens,omitempty"`
	TotalTokens      int     `json:"totalTokens,omitempty"`
	Cost             float64 `json:"cost,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 MailAccount struct {
	Provider string
	IMAP     *MailServer
	SMTP     *MailServer
	// Username is the login name; the account's address when not configured.
	Username string
	Password string
	OAuth    *oauthconfig.Config
}

type MailAccounts map[string]*MailAccount

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 MailServer struct {
	Host          string
	Port          string
	Security      string
	SkipTLSVerify bool
}

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 Node struct {
	Step                Step                 `json:"step,omitzero"`
	PreconditionResults []ConditionResult    `json:"-"`
	Stdout              string               `json:"stdout"` // standard output log file path
	Stderr              string               `json:"stderr"` // standard error log file path
	WorkingDir          string               `json:"workingDir,omitempty"`
	StartedAt           string               `json:"startedAt"`
	FinishedAt          string               `json:"finishedAt"`
	Status              NodeStatus           `json:"status"`
	RetriedAt           string               `json:"retriedAt,omitempty"`
	RetryCount          int                  `json:"retryCount,omitempty"`
	DoneCount           int                  `json:"doneCount,omitempty"`
	Repeated            bool                 `json:"repeated,omitempty"` // indicates if the node has been repeated
	SkippedByRetry      bool                 `json:"skippedByRetry,omitempty"`
	Error               string               `json:"error,omitempty"`
	StatusDetails       []NodeStatusDetail   `json:"statusDetails,omitempty"`
	Build               *BuildExecution      `json:"build,omitempty"`
	SubRuns             []SubDAGRun          `json:"children,omitempty"`
	SubRunsRepeated     []SubDAGRun          `json:"childrenRepeated,omitempty"` // repeated sub DAG runs
	OutputVariables     *collections.SyncMap `json:"outputVariables,omitempty"`
	OutputValue         *string              `json:"outputValue,omitempty"`
	OutputsValue        *string              `json:"outputsValue,omitempty"`
	StepOutputsValue    *string              `json:"stepOutputsValue,omitempty"`
	HumanTaskInput      json.RawMessage      `json:"humanTaskInput,omitempty"`
	// AgentState stores the goal progress of an agent DAG's agent
	// step, so a suspended run resumes with its task list intact.
	AgentState json.RawMessage `json:"agentState,omitempty"`
	// HumanTaskCompletedBy records who completed this human task.
	HumanTaskCompletedBy string `json:"humanTaskCompletedBy,omitempty"`
	// HumanTaskCompletedByID records the subject ID that completed this human task.
	HumanTaskCompletedByID string `json:"humanTaskCompletedById,omitempty"`
	// ApprovedAt records when this wait step was approved
	ApprovedAt string `json:"approvedAt,omitempty"`
	// ApprovalInputs stores key-value parameters provided during approval
	ApprovalInputs map[string]string `json:"approvalInputs,omitempty"`
	// ApprovedBy records who approved this wait step (username)
	ApprovedBy string `json:"approvedBy,omitempty"`
	// ApprovedByID records the subject ID that approved this wait step.
	ApprovedByID string `json:"approvedById,omitempty"`
	// RejectedAt records when this wait step was rejected
	RejectedAt string `json:"rejectedAt,omitempty"`
	// RejectedBy records who rejected this wait step (username)
	RejectedBy string `json:"rejectedBy,omitempty"`
	// RejectedByID records the subject ID that rejected this wait step.
	RejectedByID string `json:"rejectedById,omitempty"`
	// RejectionReason stores the optional reason for rejection
	RejectionReason string `json:"rejectionReason,omitempty"`
	// ApprovalIteration tracks how many times this step has been pushed back.
	ApprovalIteration int `json:"approvalIteration,omitempty"`
	// PushBackInputs stores the inputs from the last push-back.
	// These are injected as environment variables when the step re-executes.
	PushBackInputs map[string]string `json:"pushBackInputs,omitempty"`
	// PushBackHistory stores the chronological push-back inputs for this step.
	PushBackHistory []PushBackEntry `json:"pushBackHistory,omitempty"`
	// PushBackPreviousStdout stores the stdout log path from the execution that
	// was reset by the latest push-back.
	PushBackPreviousStdout string `json:"pushBackPreviousStdout,omitempty"`
	// ChatMessages stores the session messages for chat/LLM steps.
	// This field is populated during execution and synced via status updates
	// from workers.
	ChatMessages []LLMMessage `json:"chatMessages,omitempty"`
	// ToolDefinitions stores the tool definitions that were available to the LLM.
	// This enables debugging visibility into what tools and schemas were sent.
	ToolDefinitions []ToolDefinition `json:"toolDefinitions,omitempty"`
	// AgentSession stores managed coding-agent state for display and durable resume.
	AgentSession *AgentSession `json:"agentSession,omitempty"`
	// contains filtered or unexported fields
}

type NodeStatus int

type NodeStatusDetail struct {
	Label  string     `json:"label"`
	Status NodeStatus `json:"status"`
}

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 OutputsMetadata struct {
	DAGName     string `json:"dagName"`
	DAGRunID    string `json:"dagRunId"`
	AttemptID   string `json:"attemptId"`
	Status      string `json:"status"`
	CompletedAt string `json:"completedAt"`
	Params      string `json:"params,omitempty"`
}

type OverlapPolicy string

type PID int

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"}
	Params map[string]string `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 PendingStepRetry struct {
	StepName string        `json:"stepName"`
	Interval time.Duration `json:"interval"`
}

type PromptMessage 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 PullPolicy int

type PushBackEntry struct {
	Iteration int               `json:"iteration"`
	By        string            `json:"by,omitempty"`
	ByID      string            `json:"byId,omitempty"`
	At        string            `json:"at,omitempty"`
	Inputs    map[string]string `json:"inputs,omitempty"`
	// Step names the step that requested the push-back.
	Step string `json:"step,omitempty"`
	// HumanTask reports that a human task requested the push-back. Its inputs
	// hold only declared feedback properties and reach every rewound step.
	HumanTask bool `json:"humanTask,omitempty"`
}

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 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 RunStatus struct {
	Name               string
	DAGRunID           string
	Params             string
	Outputs            map[string]string
	OutputValues       map[string]any
	Status             Status
	PreconditionNotMet bool `json:"-"`
	PendingStepRetries []PendingStepRetry
}

type RuntimeProfileEntry struct {
	Key  string `json:"key"`
	Kind string `json:"kind"`
}

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"`
	OAuth    *oauthconfig.Config `json:"oauth,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 Status int

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

type StatusOption func(*DAGRunStatus)

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"`
	// Stdin is the file whose contents are piped to the standard input.
	Stdin string `json:"stdin,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 named step outputs.
	Outputs []StepOutputDeclaration `json:"outputs,omitempty"`
	// Inputs declares named regular-file inputs for build execution.
	Inputs []StepInputDeclaration `json:"inputs,omitempty"`
	// Dependencies declares DAG-local files required by the step.
	Dependencies []string `json:"dependencies,omitempty"`
	// Depends contains the list of step names to depend on.
	Depends []string `json:"depends,omitempty"`
	// InferredDepends lists producers derived from step-output references.
	// Entries order execution like Depends but are reported separately.
	InferredDepends []InferredDependency `json:"inferredDepends,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 []PromptMessage `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 StepInputDeclaration struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

type StepOutputDeclaration struct {
	Name string `json:"name"`
	Type string `json:"type,omitempty"`
	Path string `json:"path,omitempty"`
	// Source names the channel that publishes the value. An empty source means
	// the step writes the value to DAGU_OUTPUT_FILE.
	Source string `json:"source,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 SubDAG struct {
	Name   string `json:"name,omitempty"`
	Params string `json:"params,omitempty"`
	// PassEnv selects parent environment values to hand to the child run.
	// Nil preserves the default of passing nothing beyond params.
	PassEnv *SubDAGPassEnv `json:"passEnv,omitempty"`
}

type SubDAGPassEnv struct {
	// All passes the parent run's own environment values.
	All bool `json:"all,omitempty"`
	// Names lists the parent environment variables to pass.
	Names []string `json:"names,omitempty"`
}

type SubDAGRun struct {
	DAGRunID     string `json:"dagRunId,omitempty"`
	Params       string `json:"params,omitempty"`
	ParallelItem string `json:"parallelItem,omitempty"`
	// DAGName is the name of the executed sub-DAG.
	// For chat tool calls, this is the tool DAG name.
	// This field enables UI drill-down when step.call is not set.
	DAGName string `json:"dagName,omitempty"`
}

type ThinkingConfig struct {
	// Enabled activates thinking mode for supported models.
	Enabled bool `json:"enabled,omitempty"`
	// Effort controls reasoning depth: none, minimal, low, medium, high,
	// xhigh, max. Each provider maps a level it lacks to its nearest one.
	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       string           `json:"id"`
	Type     string           `json:"type"`
	Function ToolCallFunction `json:"function"`
}

type ToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

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

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,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"`
	// Digest pins the sha256 of the downloaded artifact for the platform the
	// DAG runs on, in "sha256:<64 hex>" form. The install fails when the
	// artifact hash recorded for this package does not match.
	Digest string `json:"digest,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"`
}