ast

type AgentDecl struct {
	Name              string
	Model             string // string literal, may contain ${...} env refs
	Backend           string // execution backend name (e.g. "claude_code"); when set, bypasses direct LLM API
	MCP               *MCPConfigDecl
	Input             string           // schema reference name
	Output            string           // schema reference name
	Publish           string           // persistent artifact name (empty if not set)
	System            string           // prompt reference name
	User              string           // prompt reference name
	Session           SessionMode      // defaults to SessionFresh
	Tools             []string         // tool capability names
	ToolPolicy        []string         // per-node tool policy patterns (nil = inherit workflow)
	ToolMaxSteps      int              // max tool-use iterations (0 = not set)
	MaxTokens         int              // max output tokens per LLM call (0 = inherit backend default)
	ReasoningEffort   string           // reasoning effort level: "low", "medium", "high", "xhigh", "max"
	Readonly          bool             // when true, node is not considered mutating for workspace safety
	Interaction       InteractionMode  // interaction handling (default none for agents)
	InteractionPrompt string           // prompt reference guiding LLM for llm_or_human decisions
	InteractionModel  string           // model for llm/llm_or_human modes (fallback to Model)
	Await             AwaitMode        // convergence strategy (none/wait_all/best_effort)
	Compaction        *CompactionBlock // per-node compaction overrides (nil = inherit workflow)
	Span              Span
}

type AwaitMode = types.AwaitMode

type BudgetBlock struct {
	MaxParallelBranches int     // 0 = not set
	MaxDuration         string  // e.g. "60m", empty = not set
	MaxCostUSD          float64 // 0 = not set
	MaxTokens           int     // 0 = not set
	MaxIterations       int     // 0 = not set
	Span                Span
}

type Comment struct {
	Text string
	Span Span
}

type CompactionBlock struct {
	Threshold      *float64 // ratio of model context window (0 < t <= 1); nil = inherit
	PreserveRecent *int     // recent messages kept verbatim (>= 1); nil = inherit
	Span           Span
}

type ComputeDecl struct {
	Name   string
	Input  string         // optional input schema reference name
	Output string         // schema reference name (defines the output fields)
	Expr   []*ComputeExpr // ordered list of field-name → expression-source pairs
	Await  AwaitMode      // convergence strategy (none/wait_all/best_effort)
	Span   Span
}

type ComputeExpr struct {
	Key  string
	Expr string // raw expression source (parsed at compile time)
	Span Span
}

type Edge struct {
	From string       // source node name
	To   string       // target node name (can be "done" or "fail")
	When *WhenClause  // optional condition
	Loop *LoopClause  // optional loop tracking
	With []*WithEntry // optional data mappings
	Span Span
}

type FieldType = types.FieldType

type File struct {
	Vars       *VarsBlock       // top-level vars (optional, at most one)
	MCPServers []*MCPServerDecl // top-level reusable MCP server declarations
	Prompts    []*PromptDecl    // prompt declarations
	Schemas    []*SchemaDecl    // schema declarations
	Agents     []*AgentDecl     // agent node declarations
	Judges     []*JudgeDecl     // judge node declarations
	Routers    []*RouterDecl    // router node declarations
	Humans     []*HumanDecl     // human node declarations
	Tools      []*ToolNodeDecl  // tool node declarations (direct execution, no LLM)
	Computes   []*ComputeDecl   // deterministic compute node declarations (no LLM, no shell)
	Workflows  []*WorkflowDecl  // workflow declarations
	Comments   []*Comment       // top-level comments (## ...)
	Span       Span
}

type HumanDecl struct {
	Name              string
	Input             string          // schema reference name
	Output            string          // schema reference name
	Publish           string          // persistent artifact name
	Instructions      string          // prompt reference name
	Interaction       InteractionMode // defaults to InteractionHuman (replaces Mode)
	InteractionPrompt string          // prompt reference guiding LLM for llm_or_human decisions
	InteractionModel  string          // model for llm/llm_or_human modes (fallback to Model)
	MinAnswers        int             // minimum human answers required
	Model             string          // model identifier (required for llm / llm_or_human)
	System            string          // prompt reference for LLM system prompt
	Await             AwaitMode       // convergence strategy (none/wait_all/best_effort)
	Span              Span
}

type InteractionMode = types.InteractionMode

type JudgeDecl struct {
	Name              string
	Model             string
	Backend           string // execution backend name; when set, bypasses direct LLM API
	MCP               *MCPConfigDecl
	Input             string
	Output            string
	Publish           string
	System            string
	User              string
	Session           SessionMode
	Tools             []string // usually empty for judges, but allowed
	ToolPolicy        []string // per-node tool policy patterns (nil = inherit workflow)
	ToolMaxSteps      int
	MaxTokens         int              // max output tokens per LLM call (0 = inherit backend default)
	ReasoningEffort   string           // reasoning effort level: "low", "medium", "high", "xhigh", "max"
	Readonly          bool             // when true, node is not considered mutating for workspace safety
	Interaction       InteractionMode  // interaction handling (default none for judges)
	InteractionPrompt string           // prompt reference guiding LLM for llm_or_human decisions
	InteractionModel  string           // model for llm/llm_or_human modes (fallback to Model)
	Await             AwaitMode        // convergence strategy (none/wait_all/best_effort)
	Compaction        *CompactionBlock // per-node compaction overrides (nil = inherit workflow)
	Span              Span
}

type Literal struct {
	Kind     LiteralKind
	Raw      string  // raw text as written in source
	StrVal   string  // if LitString
	IntVal   int64   // if LitInt
	FloatVal float64 // if LitFloat
	BoolVal  bool    // if LitBool
}

type LiteralKind int

type LoopClause struct {
	Name          string // loop name (e.g. "refine_loop", "full_recipe_loop")
	MaxIterations int    // upper bound
	Span          Span
}

type MCPAuthDecl struct {
	Type      string
	AuthURL   string
	TokenURL  string
	RevokeURL string
	ClientID  string
	Scopes    []string
	Span      Span
}

type MCPConfigDecl struct {
	AutoloadProject *bool
	Inherit         *bool
	Servers         []string
	Disable         []string
	Span            Span
}

type MCPServerDecl struct {
	Name      string
	Transport MCPTransport
	Command   string
	Args      []string
	URL       string
	Auth      *MCPAuthDecl
	Span      Span
}

type MCPTransport = types.MCPTransport

type Pos struct {
	File   string // source file name
	Line   int    // 1-based line number
	Column int    // 1-based column number
}

type PromptDecl struct {
	Name string
	Body string // raw text, may contain {{...}} template expressions
	Span Span
}

type RouterDecl struct {
	Name            string
	Mode            RouterMode
	Model           string // only for mode: llm
	Backend         string // execution backend name, only for mode: llm
	System          string // prompt ref, only for mode: llm
	User            string // prompt ref, only for mode: llm
	Multi           bool   // multi-route selection, only for mode: llm
	ReasoningEffort string // reasoning effort level: "low", "medium", "high", "xhigh", "max" (only for mode: llm)
	Span            Span
}

type RouterMode = types.RouterMode

type SchemaDecl struct {
	Name   string
	Fields []*SchemaField
	Span   Span
}

type SchemaField struct {
	Name       string
	Type       FieldType
	EnumValues []string // non-nil only if enum constraint present
	Span       Span
}

type SessionMode = types.SessionMode

type Span struct {
	Start Pos
	End   Pos
}

type ToolNodeDecl struct {
	Name    string
	Command string    // command to execute, may contain ${...} env refs and {{...}} template refs
	Input   string    // optional input schema reference name
	Output  string    // schema reference name
	Await   AwaitMode // convergence strategy (none/wait_all/best_effort)
	Span    Span
}

type TypeExpr int

type VarField struct {
	Name    string
	Type    TypeExpr
	Default *Literal // nil if no default
	Span    Span
}

type VarsBlock struct {
	Fields []*VarField
	Span   Span
}

type WhenClause struct {
	Condition string // condition identifier (e.g. "approved"); empty when Expr set
	Negated   bool   // true if `when not <condition>`; ignored when Expr set
	Expr      string // raw expression source (e.g. "a && b == 1"); empty when using simple form
	Span      Span
}

type WithEntry struct {
	Key   string // target input field name
	Value string // template string, e.g. "{{outputs.context_builder}}"
	Span  Span
}

type WorkflowDecl struct {
	Name           string
	Vars           *VarsBlock       // workflow-level variable declarations
	Entry          string           // entry node name
	DefaultBackend string           // workflow-level default backend (empty = not set)
	ToolPolicy     []string         // workflow-level tool policy patterns (nil = open)
	MCP            *MCPConfigDecl   // workflow-level MCP activation/filtering
	Budget         *BudgetBlock     // execution limits (optional)
	Compaction     *CompactionBlock // session compaction defaults for all nodes (optional)
	Interaction    *InteractionMode // workflow-level default interaction mode (nil = not set)
	Worktree       string           // "auto" creates a per-run git worktree; "" or "none" runs in-place
	Edges          []*Edge          // directed edges between nodes
	Span           Span
}