workflow

type AgentWorkflowBudgetConfig struct {
	// USD is the hard cap on cumulative cost across the workflow.
	// <= 0 means no cap.
	USD float64 `json:"usd,omitempty"`
	// WarnAt is a list of fractional thresholds (0.0–1.0). When the
	// cumulative spend first crosses each threshold, a single warning
	// is emitted to stdout and (when wired) the event bus.
	// Empty defaults to [0.50, 0.80].
	WarnAt []float64 `json:"warn_at,omitempty"`
	// OnExceed controls what happens when USD is reached.
	// "truncate" (default) sets the truncation flag so the run finishes
	// the current LLM response and stops gracefully. "stop" is reserved
	// for future hard-kill behavior; today it's treated like truncate.
	OnExceed string `json:"on_exceed,omitempty"`
}

type AgentWorkflowConfig struct {
	Description             string                            `json:"description,omitempty"`
	Initial                 *AgentWorkflowInitial             `json:"initial,omitempty"`
	Steps                   []AgentWorkflowStep               `json:"steps"`
	ContinueOnError         bool                              `json:"continue_on_error,omitempty"`
	PersistRuntimeOverrides *bool                             `json:"persist_runtime_overrides,omitempty"`
	Orchestration           *AgentWorkflowOrchestrationConfig `json:"orchestration,omitempty"`
	NoWebUI                 *bool                             `json:"no_web_ui,omitempty"`
	WebPort                 *int                              `json:"web_port,omitempty"`
	Daemon                  *bool                             `json:"daemon,omitempty"`
	Budget                  *AgentWorkflowBudgetConfig        `json:"budget,omitempty"`
	Progress                *AgentWorkflowProgressConfig      `json:"progress,omitempty"`

	// SubagentTimeoutSeconds overrides the per-run_subagent tool timeout
	// (default 1800 = 30 minutes). Set higher for very large refactors.
	SubagentTimeoutSeconds *int `json:"subagent_timeout_seconds,omitempty"`

	// RequiresApproval controls whether the run_automate agent tool must
	// surface an intent-confirmation prompt to the user before launching
	// this workflow. Pointer so we can distinguish "unset" (default: true)
	// from explicit false. Set to false for workflows that exist
	// specifically so an agent can invoke them mid-task — e.g. a
	// validation workflow referenced from AGENTS.md that the model must
	// run before considering work done. Anyone with workflow-file access
	// can flip this, so the security implication should be obvious to a
	// reader of the JSON.
	//
	// Only affects the agent tool path. The CLI (`sprout automate run`)
	// always prompts unless --yes is passed, because a human at the
	// keyboard might still fat-finger the wrong workflow.
	RequiresApproval *bool `json:"requires_approval,omitempty"`

	// Loop configures the workflow to iterate over a TODO file, processing
	// each unchecked item independently with a fresh agent context.
	// When Loop is set, Steps are ignored — the loop IS the execution plan.
	Loop *AgentWorkflowLoopConfig `json:"loop,omitempty"`

	// Continuation keeps a coordinator-style initial session going after
	// its final answer. Unlike Loop — which starts a fresh gate-driven
	// agent context per item — continuation re-invokes the same
	// coordinator turn with a short prompt, so the agent's own workflow
	// is preserved. After each turn the TODO file is re-read: while
	// runnable `[ ]` items remain AND the turn made progress (a new git
	// commit or a newly ticked item), another turn is issued. The loop
	// stops when nothing runnable is left or a turn makes no progress,
	// so permanently skipped items cannot spin forever.
	Continuation *AgentWorkflowContinuation `json:"continuation,omitempty"`

	// AllowedPaths declares the external directories the workflow needs
	// to read or write outside the workspace. Each entry is validated by
	// AllowedPath.Validate and pre-seeded into the running agent's
	// session allowlist (with mode) at run start so the workflow
	// doesn't re-prompt for every external access. See
	// `roadmap/SP-128-workflow-allowed-paths.md` for the full design.
	AllowedPaths []AllowedPath `json:"allowed_paths,omitempty"`
}

type AgentWorkflowContinuation struct {
	// TodoFile is the markdown file scanned for runnable `[ ]` items.
	// Default: TODO.md.
	TodoFile string `json:"todo_file,omitempty"`
	// ContinueUntilDone enables the continuation loop. Pointer so an
	// explicit false disables it even when the block is present; nil
	// means enabled (a present block is intent to continue).
	ContinueUntilDone *bool `json:"continue_until_done,omitempty"`
	// MaxContinuations caps the number of continuation turns issued
	// after the initial turn, as a hard backstop. Default: 1000.
	MaxContinuations int `json:"max_continuations,omitempty"`
	// MaxIdleTurns is how many consecutive turns may end without progress
	// (no new commit, no newly ticked item) before the loop stops. A turn
	// can legitimately end idle, e.g. after re-verifying work a subagent
	// left uncommitted; the next turn gets DefaultContinuationIdlePrompt.
	// Default: DefaultMaxIdleTurns.
	MaxIdleTurns int `json:"max_idle_turns,omitempty"`
	// Prompt is the short prompt sent on each continuation turn.
	// Empty uses DefaultContinuationPrompt.
	Prompt string `json:"prompt,omitempty"`
}

type AgentWorkflowInitial struct {
	Prompt       string        `json:"prompt,omitempty"`
	PromptFile   string        `json:"prompt_file,omitempty"`
	AllowedPaths []AllowedPath `json:"allowed_paths,omitempty"`
	AgentWorkflowRuntime
}

type AgentWorkflowLoopConfig struct {
	// TodoFile is the markdown file to scan for [ ] items. Default: TODO.md.
	TodoFile string `json:"todo_file,omitempty"`
	// GatePromptFile is the system prompt for the gate LLM call that
	// parses each TODO section into a structured delegation prompt.
	// Required. The gate call uses the agent's existing client.
	GatePromptFile string `json:"gate_prompt_file,omitempty"`
	// MaxRetries is the number of retry attempts on build failure
	// before skipping an item. Default: 2.
	MaxRetries int `json:"max_retries,omitempty"`
	// MaxIterations caps the agent iterations per item. Default: 50.
	MaxIterations int `json:"max_iterations,omitempty"`
	// BuildCommand is run after each item to verify. Default: "go build ./...".
	BuildCommand string `json:"build_command,omitempty"`
}

type AgentWorkflowOrchestrationConfig struct {
	Enabled                bool   `json:"enabled,omitempty"`
	Resume                 *bool  `json:"resume,omitempty"`
	YieldOnProviderHandoff *bool  `json:"yield_on_provider_handoff,omitempty"`
	StateFile              string `json:"state_file,omitempty"`
	EventsFile             string `json:"events_file,omitempty"`
	ConversationSessionID  string `json:"conversation_session_id,omitempty"`
}

type AgentWorkflowProgressConfig struct {
	// HeartbeatSeconds is the interval at which the workflow prints a
	// progress line ([budget] $X of $Y · iter N · elapsed Tm).
	// <= 0 disables the heartbeat. Default 600 (10 min) when Budget is set.
	HeartbeatSeconds int `json:"heartbeat_seconds,omitempty"`
}

type AgentWorkflowRuntime struct {
	SkipPrompt        *bool                     `json:"skip_prompt,omitempty"`
	Provider          string                    `json:"provider,omitempty"`
	Model             string                    `json:"model,omitempty"`
	Persona           string                    `json:"persona,omitempty"`
	DryRun            *bool                     `json:"dry_run,omitempty"`
	MaxIterations     *int                      `json:"max_iterations,omitempty"`
	NoStream          *bool                     `json:"no_stream,omitempty"`
	SystemPrompt      string                    `json:"system_prompt,omitempty"`
	SystemPromptFile  string                    `json:"system_prompt_file,omitempty"`
	Unsafe            *bool                     `json:"unsafe,omitempty"`
	NoSubagents       *bool                     `json:"no_subagents,omitempty"`
	ResourceDirectory string                    `json:"resource_directory,omitempty"`
	ReasoningEffort   string                    `json:"reasoning_effort,omitempty"`
	SubagentOverrides WorkflowSubagentOverrides `json:"subagent_overrides,omitempty"`
	// RiskProfile selects a named shell-command risk cascade preset
	// for this step / initial run (SP-058). One of: readonly,
	// cautious, default, permissive, unrestricted. Per-step values
	// override the workflow-level initial setting and the global
	// config. Unknown values fall through to the agent's default
	// resolution chain (override > config > "default").
	RiskProfile string `json:"risk_profile,omitempty"`
}

type AgentWorkflowStep struct {
	Name          string        `json:"name,omitempty"`
	Prompt        string        `json:"prompt,omitempty"`
	PromptFile    string        `json:"prompt_file,omitempty"`
	Command       string        `json:"command,omitempty"`
	CommandFile   string        `json:"command_file,omitempty"`
	When          string        `json:"when,omitempty"`
	FileExists    []string      `json:"file_exists,omitempty"`
	FileNotExists []string      `json:"file_not_exists,omitempty"`
	AllowedPaths  []AllowedPath `json:"allowed_paths,omitempty"`
	AgentWorkflowRuntime
}

type AllowedPath struct {
	// Path is the absolute path to the directory. Must be absolute,
	// free of `..` traversal after Clean(), and must not start with
	// `~` (refuse to expand; user must provide the canonical absolute
	// path).
	Path string `json:"path"`

	// Mode is one of {read_only, read_write}. The filesystem layer
	// enforces this: a write tool called against a read_only entry
	// gets a security error explaining the declared mode blocked it.
	Mode string `json:"mode"`

	// Reason is surfaced verbatim in the launch confirmation dialog
	// so the user understands why the workflow needs this path.
	// Strongly recommended; loader does not require it.
	Reason string `json:"reason,omitempty"`
}

type CLIOverrides struct {
	SetWebUI    func(disabled bool)
	SetWebPort  func(port int)
	SetDaemon   func(enabled bool)
	SetNoStream func(enabled bool)
	GetNoStream func() bool

	// Budget/heartbeat CLI overrides. Zero values mean "inherit JSON".
	BudgetUSD        float64
	BudgetWarn       string
	HeartbeatSeconds int
}

type ContinuationResult struct {
	// Continuations is the number of continuation turns issued after the
	// initial turn.
	Continuations int `json:"continuations"`
	// StopReason is the classified stop condition.
	StopReason ContinuationStopReason `json:"stop_reason"`
	// RunnableItems is the number of `[ ]` items observed when the loop
	// stopped (0 for a clean finish).
	RunnableItems int `json:"runnable_items"`
	// Err is set when StopReason is turn_error or context_cancelled.
	Err error `json:"-"`
}

type ContinuationStopReason string

type QueryExecutor func(ctx context.Context, chatAgent *agent.Agent, eventBus *events.EventBus, query string) error

type WorkflowExecutionState struct {
	Version            int    `json:"version"`
	InitialCompleted   bool   `json:"initial_completed"`
	NextStepIndex      int    `json:"next_step_index"`
	CurrentTodoLineNum int    `json:"current_todo_line_num,omitempty"`
	HasError           bool   `json:"has_error"`
	FirstError         string `json:"first_error,omitempty"`
	LastProvider       string `json:"last_provider,omitempty"`
	Complete           bool   `json:"complete"`
	UpdatedAt          string `json:"updated_at,omitempty"`
}

type WorkflowSubagentOverride struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
}

type WorkflowSubagentOverrides map[string]WorkflowSubagentOverride