dsl

type Agent struct {
	Name        string `yaml:"name"`
	DisplayName string `yaml:"display_name"`
	Title       string `yaml:"title"`
	// Description is a short paragraph of body text describing the agent's
	// purpose, surfaced on agent cards and detail pages. Distinct from
	// `system` (which is the LLM-facing prompt) — intended for users.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Avatar      string `yaml:"avatar"`
	// Icon is a Lucide icon name (frontend uses lucide-react). Lets each
	// agent render with a distinctive glyph instead of an identical robot.
	Icon string `yaml:"icon,omitempty" json:"icon,omitempty"`
	// AvatarGradient is a 2-stop CSS color array (e.g. ["#EF4444", "#DC2626"])
	// used as the background gradient behind the icon/avatar.
	AvatarGradient []string `yaml:"avatar_gradient,omitempty" json:"avatar_gradient,omitempty"`
	Extends        string   `yaml:"extends"`
	Model          string   `yaml:"model"`
	FallbackModel  string   `yaml:"fallback_model"`
	// Models maps step-type tags (e.g. "classify", "code", "summarize") to
	// model IDs. Lookups that miss this map fall back to Model. Unset keys
	// are filled at validate time from Settings.DefaultModels.
	Models         map[string]string  `yaml:"models,omitempty"`
	System         string             `yaml:"system"`
	Temperature    *float64           `yaml:"temperature"`
	MaxTokens      int                `yaml:"max_tokens"`
	Effort         string             `yaml:"effort"` // "low" | "medium" | "high" | "xhigh" | "max"
	Budget         string             `yaml:"budget"` // e.g., "$0.50"
	Tools          []string           `yaml:"tools"`
	Knowledge      []string           `yaml:"knowledge"`
	Team           []string           `yaml:"team"`
	Supervision    *SupervisionDef    `yaml:"supervision"`
	Retry          *RetryDef          `yaml:"retry"`
	RateLimit      *RateLimitDef      `yaml:"rate_limit"`
	CircuitBreaker *CircuitBreakerDef `yaml:"circuit_breaker"`
	Skills         *SkillsDef         `yaml:"skills"`
	Delegation     *DelegationDef     `yaml:"delegation"`
	Memory         *MemoryDef         `yaml:"memory"`
	// Triggers declare the events this agent reacts to (reactive cognition).
	// See docs/reactive-agents-design.md §4.2.
	Triggers []TriggerDef `yaml:"triggers,omitempty" json:"triggers,omitempty"`

	// Norm is the name of a top-level `norms:` entry whose guidance is
	// composed into this agent's system prompt at spawn time. Empty
	// means no norm is applied. The parser validates that the name
	// resolves to a defined norm.
	Norm string `yaml:"norm,omitempty" json:"norm,omitempty"`

	// IsMeta marks an agent as a built-in meta-agent (e.g. orchestrator,
	// builder). Meta-agents are filtered out of "team" / "channel member"
	// listings and protected from runtime mutation. Set by Inject*-style
	// constructors; not parsed from YAML.
	IsMeta bool `yaml:"-" json:"-"`
}

type AgentTemplate struct {
	Version        string   `json:"version" yaml:"version"`
	Name           string   `json:"name" yaml:"name"`
	DisplayName    string   `json:"display_name,omitempty" yaml:"display_name,omitempty"`
	Title          string   `json:"title,omitempty" yaml:"title,omitempty"`
	Description    string   `json:"description,omitempty" yaml:"description,omitempty"`
	Avatar         string   `json:"avatar,omitempty" yaml:"avatar,omitempty"`
	Icon           string   `json:"icon,omitempty" yaml:"icon,omitempty"`
	AvatarGradient []string `json:"avatar_gradient,omitempty" yaml:"avatar_gradient,omitempty"`
	Model          string   `json:"model" yaml:"model"`
	System         string   `json:"system" yaml:"system"`
	Tools          []string `json:"tools,omitempty" yaml:"tools,omitempty"`
	Team           []string `json:"team,omitempty" yaml:"team,omitempty"`
	ExportedBy     string   `json:"exported_by,omitempty" yaml:"exported_by,omitempty"`
	ExportedAt     string   `json:"exported_at,omitempty" yaml:"exported_at,omitempty"`
}

type ChannelBackend interface {
	CreateChannel(id, name, description, createdBy string, team []string, mode string) error
	GetChannelByName(name string) (*ChannelInfo, error)
	ListAllChannels() ([]ChannelInfo, error)
	ListChannelsForAgent(agent string) ([]ChannelInfo, error)
	FindChannelForAgents(agent1, agent2 string) (channelID string, channelName string, err error)
	InsertChannelMessage(channelID, agent, role, content string, threadID *int64, metadata, sender string, activities []vega.ToolActivity) (int64, error)
	RecentChannelMessages(channelID string, limit int) ([]ChannelMessage, error)
}

type ChannelDef struct {
	Description string   `yaml:"description"`
	Team        []string `yaml:"team"`
	Mode        string   `yaml:"mode"` // "" (default) or "social"
}

type ChannelInfo struct {
	ID   string
	Name string
	Team []string
}

type ChannelLifecycleCallback func(id, name, description, createdBy string, team []string, mode string)

type ChannelMessage struct {
	Agent   string
	Sender  string
	Content string
}

type ChannelPeerResolver func(callerAgent, targetAgent string) bool

type ChannelPostCallback func(channelName, agent, content string, msgID int64, threadID *int64)

type ChannelReactiveCallback func(channelName string, team []string, poster string, message string, depth int, triggerMsgID int64)

type CircuitBreakerDef struct {
	Threshold   int    `yaml:"threshold"`     // failures before opening
	ResetAfter  string `yaml:"reset_after"`   // e.g., "30s", "1m"
	HalfOpenMax int    `yaml:"half_open_max"` // probes allowed in half-open
}

type Company struct {
	ID          string           `yaml:"id" json:"id"`
	Name        string           `yaml:"name" json:"name"`
	Description string           `yaml:"description,omitempty" json:"description,omitempty"`
	Location    string           `yaml:"location,omitempty" json:"location,omitempty"`
	LogoURL     string           `yaml:"logo_url,omitempty" json:"logo_url,omitempty"`
	AccentColor string           `yaml:"accent_color,omitempty" json:"accent_color,omitempty"`
	Siblings    []CompanySibling `yaml:"siblings,omitempty" json:"siblings,omitempty"`
}

type CompanySibling struct {
	Name string `yaml:"name" json:"name"`
	URL  string `yaml:"url" json:"url"`
	Icon string `yaml:"icon,omitempty" json:"icon,omitempty"`
}

type DelegateToolOpts struct {
	SendFn              SendFunc
	TeamResolver        TeamResolver
	ChannelPeerResolver ChannelPeerResolver // optional — allows delegation to channel peers
}

type DelegationContext struct {
	CallerAgent string
	Messages    []llm.Message
}

type DelegationDef struct {
	ContextWindow int      `yaml:"context_window"` // number of recent messages to forward
	IncludeRoles  []string `yaml:"include_roles"`  // filter by role (user, assistant, system)
	Blackboard    bool     `yaml:"blackboard"`     // enable shared blackboard for team
}

type DelegationObserver func(ctx context.Context, fromAgent, toAgent, message, response string)

type Document struct {
	Name        string                 `yaml:"name"`
	Description string                 `yaml:"description"`
	Agents      map[string]*Agent      `yaml:"agents"`
	Channels    map[string]*ChannelDef `yaml:"channels"`
	Workflows   map[string]*Workflow   `yaml:"workflows"`
	Tools       map[string]*ToolDef    `yaml:"tools"`
	// Norms are named guidance blocks that can be appended to an agent's
	// system prompt at runtime. Use the interpreter's Norm() accessor to
	// look one up by name; the host application decides which norm (if
	// any) applies to a given session via the ExtraSystemProvider hook.
	Norms    map[string]*Norm `yaml:"norms,omitempty"`
	Settings *Settings        `yaml:"settings"`
	Company  *Company         `yaml:"company,omitempty"`
}

type ExecutionContext struct {
	// Inputs are the workflow input values
	Inputs map[string]any

	// Variables holds step outputs and set values
	Variables map[string]any

	// CurrentStep is the index of the executing step
	CurrentStep int

	// LoopState for loop iterations
	LoopState *LoopState

	// StartTime is when execution began
	StartTime time.Time

	// Timeout for the entire workflow
	Timeout time.Duration
}

type GlobalSkillsDef struct {
	Directories []string `yaml:"directories"`
}

type GroupResolver func(ctx context.Context) *vega.ProcessGroup

type HeraCallbacks struct {
	OnAgentCreated func(agent *Agent) error
	OnAgentDeleted func(name string)
	// OnProvisioning fires at multiple phases during create_agent so the
	// server can stream SSE events to the FE (refs govega#56). The
	// callback runs synchronously inside the tool body — keep it cheap.
	OnProvisioning func(event ProvisioningEvent)
	ChannelBackend ChannelBackend // optional — auto-creates channels for team leads
}

type HeraConfig struct {
	Name                    string // lowercase slug (default: "hera")
	DisplayName             string // capitalized name (default: "Hera")
	Title                   string // role label shown on agent cards (default: "Agent Builder")
	OrchestratorName        string // companion orchestrator's slug (default: "iris")
	OrchestratorDisplayName string // companion orchestrator's display name (default: "Iris")
	ProductName             string // product/universe name (default: "Vega")
	SystemPrompt            string // optional prompt override
	Model                   string
	FallbackModel           string
	// Models is an optional per-step-type routing table — see
	// Agent.ModelFor. When nil, applyDefaults seeds it with Hera's
	// recommended defaults (classify on Haiku for first-turn intent).
	Models map[string]string
}

type InboxBackend interface {
	InsertInboxItem(fromAgent, subject, body, priority string) (int64, error)
	InsertResolvedInboxItem(fromAgent, subject, body, resolution string) (int64, error)
	ListInboxItems(status string, limit int) ([]InboxItem, error)
	ResolveInboxItem(id int64, resolution string) error
	DeleteInboxItem(id int64) error
	TriageInboxItems(ids []int64, threshold int) ([]int64, error)
}

type InboxItem struct {
	ID            int64      `json:"id"`
	FromAgent     string     `json:"from_agent"`
	Subject       string     `json:"subject"`
	Body          string     `json:"body,omitempty"`
	Priority      string     `json:"priority"`
	Status        string     `json:"status"`
	Resolution    string     `json:"resolution,omitempty"`
	CreatedAt     time.Time  `json:"created_at"`
	ResolvedAt    *time.Time `json:"resolved_at,omitempty"`
	TriageCount   int        `json:"triage_count"`
	LastTriagedAt *time.Time `json:"last_triaged_at,omitempty"`
}

type Input struct {
	Type        string   `yaml:"type"`
	Description string   `yaml:"description"`
	Required    bool     `yaml:"required"`
	Default     any      `yaml:"default"`
	Enum        []string `yaml:"enum"`
	Min         *float64 `yaml:"min"`
	Max         *float64 `yaml:"max"`
}

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

type InterpreterOption func(*Interpreter)

type IrisConfig struct {
	Name               string // lowercase slug for routing/registration (default: "iris")
	DisplayName        string // capitalized name shown in UI/prompt (default: "Iris")
	Title              string // role label shown on agent cards (default: "Orchestrator")
	BuilderName        string // companion builder's slug (default: "hera")
	BuilderDisplayName string // companion builder's display name (default: "Hera")
	ProductName        string // product/universe name (default: "Vega")
	SystemPrompt       string // optional prompt override; if empty the bundled template is used
	Model              string // optional model override
	FallbackModel      string // optional fallback model override
	// Models is an optional per-step-type routing table — see
	// Agent.ModelFor. When nil, applyDefaults seeds it with Iris's
	// recommended defaults (classify on Haiku for routing decisions).
	Models map[string]string
}

type LoggingDef struct {
	Level string `yaml:"level"` // debug, info, warn, error
	File  string `yaml:"file"`
}

type LoopState struct {
	Index int
	Count int
	Item  any
	First bool
	Last  bool
}

type MCPDef struct {
	Servers []MCPServerDef `yaml:"servers"`
}

type MCPServerDef struct {
	Name         string            `yaml:"name"`
	Transport    string            `yaml:"transport"`
	Command      string            `yaml:"command"`
	Args         []string          `yaml:"args"`
	Env          map[string]string `yaml:"env"`
	URL          string            `yaml:"url"`
	Headers      map[string]string `yaml:"headers"`
	Timeout      string            `yaml:"timeout"`
	FromRegistry bool              `yaml:"-"` // resolved from registry, not serialized
}

type MemoryDef struct {
	// Reflect enables a small post-turn reflection inference that asks the
	// model what is worth remembering and writes typed memories on the
	// agent's behalf. Default false. The global VEGA_REFLECTION env var
	// can override (false=kill switch, true=on for every agent).
	Reflect bool `yaml:"reflect"`
}

type Norm struct {
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	System      string `yaml:"system" json:"system"`
}

type Parser struct {
	// BaseDir for resolving relative paths
	BaseDir string
}

type ProvisioningEvent struct {
	Phase    ProvisioningPhase
	Name     string
	Snapshot *Agent // non-nil from field_set onward
	Err      error  // set only when Phase == failed
}

type ProvisioningPhase string

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

type REPLOption func(*REPL)

type RateLimitDef struct {
	RequestsPerMinute int `yaml:"requests_per_minute"`
	TokensPerMinute   int `yaml:"tokens_per_minute"`
}

type Repeat struct {
	Steps []Step `yaml:"steps"`
	Until string `yaml:"until"`
	Max   int    `yaml:"max"`
}

type ReplyTarget interface {
	Reply(ctx context.Context, content string) error
}

type RetryDef struct {
	MaxAttempts int    `yaml:"max_attempts"`
	Backoff     string `yaml:"backoff"` // linear, exponential, constant
}

type ScheduledJob struct {
	Name      string `json:"name"`
	Cron      string `json:"cron"`    // standard 5-field cron expression
	AgentName string `json:"agent"`   // agent to message on schedule
	Message   string `json:"message"` // message to send
	Enabled   bool   `json:"enabled"`
	// InMemoryOnly skips the persist callback on AddJob. Used for jobs that
	// are derived from server config (e.g. the orchestrator heartbeat) and
	// must be re-created from config each boot — persisting them strands
	// stale rows after a rename (govega#101).
	InMemoryOnly bool `json:"-"`
}

type SchedulerBackend interface {
	AddJob(job ScheduledJob) error
	RemoveJob(name string) error
	ListJobs() []ScheduledJob
}

type SendFunc func(ctx context.Context, agent string, message string) (string, error)

type Settings struct {
	DefaultModel string `yaml:"default_model"`
	// DefaultModels is a document-wide step-type → model fallback table.
	// Each agent inherits any keys it hasn't set in its own Models map.
	DefaultModels      map[string]string `yaml:"default_models,omitempty"`
	DefaultTemperature *float64          `yaml:"default_temperature"`
	Sandbox            string            `yaml:"sandbox"`
	Budget             string            `yaml:"budget"`
	Supervision        *SupervisionDef   `yaml:"supervision"`
	RateLimit          *RateLimitDef     `yaml:"rate_limit"`
	Logging            *LoggingDef       `yaml:"logging"`
	Tracing            *TracingDef       `yaml:"tracing"`
	MCP                *MCPDef           `yaml:"mcp"`
	Skills             *GlobalSkillsDef  `yaml:"skills"`
}

type SkillsDef struct {
	Directories []string `yaml:"directories"`
	Include     []string `yaml:"include"`
	Exclude     []string `yaml:"exclude"`
	MaxActive   int      `yaml:"max_active"`
}

type Step struct {
	// Agent step fields
	Agent           string `yaml:"-"` // Extracted from key
	Action          string `yaml:"-"` // Extracted from key
	Send            string `yaml:"send"`
	Save            string `yaml:"save"`
	Timeout         string `yaml:"timeout"`
	Budget          string `yaml:"budget"`
	Retry           int    `yaml:"retry"`
	If              string `yaml:"if"`
	ContinueOnError bool   `yaml:"continue_on_error"`
	Format          string `yaml:"format"` // json, yaml, etc.

	// Control flow fields
	Condition string `yaml:"-"` // For if steps
	Then      []Step `yaml:"then"`
	Else      []Step `yaml:"else"`

	// Loop fields
	ForEach string  `yaml:"for"`   // "item in items"
	Steps   []Step  `yaml:"steps"` // for-each body
	Repeat  *Repeat `yaml:"repeat"`

	// Parallel fields
	Parallel []Step `yaml:"parallel"`

	// Sub-workflow fields
	Workflow string         `yaml:"workflow"`
	With     map[string]any `yaml:"with"`

	// Special fields
	Set    map[string]any `yaml:"set"`
	Return string         `yaml:"return"`
	Try    []Step         `yaml:"try"`
	Catch  []Step         `yaml:"catch"`

	// Raw for flexible parsing
	Raw map[string]any `yaml:"-"`
}

type StepEvent struct {
	// Index is the step's position in the workflow's top-level steps.
	Index int `json:"index"`
	// Name labels the step: the agent name for agent steps, otherwise
	// the step kind (set, for, return, ...).
	Name string `json:"name"`
	// Status is one of the StepStatus* constants.
	Status string `json:"status"`
	// Error carries the failure message for StepStatusFailed.
	Error string `json:"error,omitempty"`
	// At is when the transition happened.
	At time.Time `json:"at"`
}

type StepObserver func(runID, workflow string, ev StepEvent)

type SupervisionDef struct {
	Strategy    string `yaml:"strategy"` // restart, stop, escalate
	MaxRestarts int    `yaml:"max_restarts"`
	Window      string `yaml:"window"` // e.g., "10m"
}

type Task struct {
	ID          string     `json:"id"`
	Title       string     `json:"title"`
	Description string     `json:"description"`
	Status      string     `json:"status"`
	Priority    string     `json:"priority"`
	Assignee    string     `json:"assignee"`
	Tags        string     `json:"tags"`
	CreatedBy   string     `json:"created_by"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	DueAt       *time.Time `json:"due_at,omitempty"`
}

type TaskBackend interface {
	InsertTask(t Task) error
	GetTask(id string) (*Task, error)
	ListMyTasks(assignee string, status []string, limit int) ([]Task, error)
	ListUnassignedTasks(limit int) ([]Task, error)
	UpdateTaskStatus(id, status string) error
	AssignTask(id, assignee string) error
	ClaimTask(id, assignee string) error // sets assignee=caller, status=doing
	AddTaskComment(taskID, author, content string) (int64, error)
	LinkTaskProcess(taskID, processID string) error
}

type TeamResolver func(ctx context.Context) []string

type ToolDef struct {
	Name           string      `yaml:"name"`
	Description    string      `yaml:"description"`
	Params         []ToolParam `yaml:"params"`
	Implementation *ToolImpl   `yaml:"implementation"`
	Include        []string    `yaml:"include"` // For loading from files
}

type ToolImpl struct {
	Type    string            `yaml:"type"` // http, exec, file_read, file_write, builtin
	Method  string            `yaml:"method"`
	URL     string            `yaml:"url"`
	Headers map[string]string `yaml:"headers"`
	Query   map[string]string `yaml:"query"`
	Body    any               `yaml:"body"`
	Command string            `yaml:"command"`
	Timeout string            `yaml:"timeout"`
}

type ToolParam struct {
	Name        string   `yaml:"name"`
	Type        string   `yaml:"type"`
	Description string   `yaml:"description"`
	Required    bool     `yaml:"required"`
	Default     any      `yaml:"default"`
	Enum        []string `yaml:"enum"`
}

type TracingDef struct {
	Enabled  bool   `yaml:"enabled"`
	Exporter string `yaml:"exporter"` // otlp, jaeger, json
	Endpoint string `yaml:"endpoint"`
}

type TriggerDef struct {
	On     string `yaml:"on" json:"on"`
	Where  string `yaml:"where,omitempty" json:"where,omitempty"`
	Gate   string `yaml:"gate,omitempty" json:"gate,omitempty"`
	Prompt string `yaml:"prompt" json:"prompt"`
}

type ValidationError struct {
	File    string
	Line    int
	Column  int
	Field   string
	Message string
	Hint    string
}

type Workflow struct {
	Description string            `yaml:"description"`
	Inputs      map[string]*Input `yaml:"inputs"`
	Steps       []Step            `yaml:"steps"`
	Output      any               `yaml:"output"` // string or map
}