workflow

type Budget struct {
	MaxTokens     int64    `json:"max_tokens,omitempty"`     // total tokens (input+output+cache write+cache read) across all steps
	MaxSeconds    int64    `json:"max_seconds,omitempty"`    // wall-clock seconds, accumulated across resumes
	MaxIterations int      `json:"max_iterations,omitempty"` // loop iterations (steps executed in the main chain)
	OnExceeded    *StepRef `json:"on_exceeded,omitempty"`    // step to route to when the budget trips (default: stop)
}

type Def struct {
	Name       string             `json:"name"`
	EntryPoint StepRef            `json:"entry_point"`
	Steps      map[string]StepDef `json:"steps"`
	Summary    string             `json:"summary,omitempty"`
	Budget     *Budget            `json:"budget,omitempty"` // optional run budget (tokens/seconds/iterations)
	// DisplayInTUI controls whether the workflow appears in the TUI's
	// workflow switcher (Shift+Tab) and slash menu. Default true; internal
	// workflows (e.g. the shipped heartbeat one) set false. It does not
	// affect runnability — jobs and explicit invocations still work by name.
	DisplayInTUI *bool `json:"display_in_tui,omitempty"`
}

type File struct {
	Workflows []Def `json:"workflows"`
}

type InputDef struct {
	Description string `json:"description"`
}

type StepDef struct {
	Type        string              `json:"type"`                   // "agent", "tool", "bash", or "if" (required)
	Effort      string              `json:"effort,omitempty"`       // "adaptive", "low", "medium", "high", "max"
	NextSteps   []StepRef           `json:"next_steps,omitempty"`   // next steps to execute (empty = end workflow)
	InputParams map[string]InputDef `json:"input_params,omitempty"` // declared input parameters for this step
	Tool        string              `json:"tool,omitempty"`         // tool name for type="tool"
	Agent       string              `json:"agent,omitempty"`        // agent name (loaded from .vix/agents/)
	ForkFrom    string              `json:"fork_from,omitempty"`    // fork from a prior step's agent
	Prompt      string              `json:"prompt,omitempty"`       // template, supports $() syntax
	Command     string              `json:"command,omitempty"`      // bash command for type="bash"
	Input       string              `json:"input,omitempty"`        // piped to stdin (supports $() expansion)
	Output      string              `json:"output,omitempty"`       // file path to write step text output
	DenyTools   []string            `json:"deny_tools,omitempty"`   // tools blocked from executing
	Stream      *bool               `json:"stream,omitempty"`       // nil defaults to true
	Silent      bool                `json:"silent,omitempty"`       // suppress all TUI events + vixd dispatch logs for this step
	JSONOutput  bool                `json:"json_output,omitempty"`  // parse LLM output as JSON for variable expansion
	DisplayKey  string              `json:"display_key,omitempty"`  // JSON key to extract as per-step display text
	Explanation string              `json:"explanation,omitempty"`  // user-facing explanation shown at step start
	Question    string              `json:"question,omitempty"`     // question text for tool steps
	Options     []StepOption        `json:"options,omitempty"`      // structured options for ask_question_to_user
	Category    string              `json:"category,omitempty"`     // tab/category label for ask_question_to_user
	TimeoutSec  *int                `json:"timeout_sec,omitempty"`  // per-step timeout (type="bash" only); pointer distinguishes absent from 0
	Signal      bool                `json:"signal,omitempty"`       // agent steps: expose the workflow_signal tool to the agent
	OnError     *StepRef            `json:"on_error,omitempty"`     // agent steps: route here instead of aborting when the step fails

	// if-step fields (type="if"): a bash condition selects a single edge.
	Condition string   `json:"condition,omitempty"` // bash test evaluated like execute_if (exit 0 = true)
	Then      *StepRef `json:"then,omitempty"`      // taken when the condition is true (required for type="if")
	Else      *StepRef `json:"else,omitempty"`      // taken when the condition is false (optional; absent = end)

	// fan_out fields (type="fan_out"): run one branch per element of a list.
	Over        string   `json:"over,omitempty"`         // $(...) reference to a typed list to iterate
	As          string   `json:"as,omitempty"`           // binding name: the per-element item (fan_out) or the collected results list (fan_in)
	BarrierID   string   `json:"barrier_id,omitempty"`   // correlates a fan_out with its fan_in
	MaxParallel int      `json:"max_parallel,omitempty"` // concurrency cap; 0/absent = min(N, GOMAXPROCS)
	Branch      *StepRef `json:"branch,omitempty"`       // per-element branch entry point (required for type="fan_out")

	// fan_in fields (type="fan_in"): join the barrier's branches into one list.
	OnBranchError string `json:"on_branch_error,omitempty"` // "abort" (default) or "collect" (drop failed branches)
}

type StepOption struct {
	Title        string    `json:"title"`
	Description  string    `json:"description"`
	Steps        []StepRef `json:"steps,omitempty"`
	HasUserInput bool      `json:"has_user_input,omitempty"`
}

type StepRef struct {
	ID        string            `json:"id"`
	Params    map[string]string `json:"params,omitempty"`
	ExecuteIf string            `json:"execute_if,omitempty"`
}