agents

type Agent struct {
	// Metadata
	Name        string `yaml:"name"`
	Description string `yaml:"description"`

	// Model preferences (optional)
	Provider string `yaml:"provider,omitempty"`
	Model    string `yaml:"model,omitempty"`

	// Tool configuration
	Tools ToolsConfig `yaml:"tools,omitempty"`

	// Tool-specific settings
	Shell ShellConfig `yaml:"shell,omitempty"`
	Read  ReadConfig  `yaml:"read,omitempty"`
	Spawn SpawnConfig `yaml:"spawn,omitempty"`

	// Skills override for this agent.
	// Values: "" (use global config), "all"/"*" (enable all), "none" (disable),
	// or comma-separated skill names (e.g. "git,docker").
	// When set, overrides the global skills.enabled config for this agent.
	// CLI --skills flag takes precedence over this.
	Skills string `yaml:"skills,omitempty"`

	// Behavior
	MaxTurns int  `yaml:"max_turns,omitempty"`
	Search   bool `yaml:"search,omitempty"` // Enable web search tools

	// DefaultPrompt is used when agent is invoked without a message
	DefaultPrompt string `yaml:"default_prompt,omitempty"`

	// Output specifies where to write agent response (deprecated, use OutputTool + OnComplete)
	// Valid: "" (stdout), "commit_editmsg" (.git/COMMIT_EDITMSG)
	Output string `yaml:"output,omitempty"`

	// OutputTool configures a tool for capturing structured output.
	// When set, a tool with the configured name is dynamically created
	// and added to the agent's enabled tools.
	OutputTool OutputToolConfig `yaml:"output_tool,omitempty"`

	// OnComplete is a shell command to run with captured output piped to stdin.
	// Runs in the git repo root (if in a git repo) or cwd.
	// Replaces the hardcoded "output: commit_editmsg" approach.
	OnComplete string `yaml:"on_complete,omitempty"`

	// Include additional .md files in the system prompt
	// Files are loaded from the agent directory and appended after system.md
	Include []string `yaml:"include,omitempty"`

	// AgentsMd controls loading of AGENTS.md hierarchy into the system prompt.
	// Values: "auto" (default), "true", "false"
	// "auto" loads project instructions if the agent has coding tools (write_file, edit_file, shell)
	// "true" always loads, "false" never loads
	AgentsMd string `yaml:"agents_md,omitempty"`

	// Memory settings
	Memory MemoryConfig `yaml:"memory,omitempty"`

	// MCP servers to auto-connect
	MCP []MCPConfig `yaml:"mcp,omitempty"`

	// EnableHandover indicates the agent writes handover documents to the
	// XDG handover directory. On /handover the most recently modified .md
	// file in that directory is read as zero-cost context for the next agent.
	EnableHandover bool `yaml:"enable_handover,omitempty"`

	// HandoverMode controls how context is produced on /handover:
	//   "light"    - use last assistant message as handover context (zero cost)
	//   "file"     - read latest .md from the handover directory (zero cost, agent maintains it)
	//   "script"   - run handover_script command line (no shell expansion), use stdout (zero cost)
	//   "compress" - LLM-driven compression of full conversation
	//   ""         - auto: try file first, fall back to compress
	HandoverMode string `yaml:"handover_mode,omitempty"`

	// HandoverScript is a command line whose stdout becomes the handover context.
	// It is executed directly (without shell expansion). When the agent is the
	// handover target, the command runs only after explicit confirmation.
	HandoverScript string `yaml:"handover_script,omitempty"`

	// GistID for syncing with GitHub Gists (set on export/import)
	GistID string `yaml:"gist_id,omitempty"`

	// PlatformMessages holds developer messages injected at the start of each
	// new conversation session, keyed by platform.
	PlatformMessages PlatformMessagesConfig `yaml:"platform_messages,omitempty"`

	// System prompt (loaded from system.md + included files)
	SystemPrompt string `yaml:"-"`

	// Source info
	Source     AgentSource `yaml:"-"`
	SourcePath string      `yaml:"-"`
}

type AgentSource int

type CustomToolDef struct {
	// Name is the tool name shown to the LLM. Must match ^[a-z][a-z0-9_]*$
	// and must not collide with any built-in tool name.
	Name string `yaml:"name"`

	// Description is the tool description passed to the LLM.
	Description string `yaml:"description"`

	// Script is the path to the script, relative to the agent directory.
	// Subdirectories are allowed (e.g. "scripts/job-status.sh").
	Script string `yaml:"script"`

	// Input is a JSON Schema (type: object) for the tool's input parameters.
	// If omitted, the tool accepts no parameters.
	Input map[string]interface{} `yaml:"input,omitempty"`

	// TimeoutSeconds is the execution timeout. Default 30, max 300.
	TimeoutSeconds int `yaml:"timeout_seconds,omitempty"`

	// Env is a map of additional environment variables to set when running the script.
	Env map[string]string `yaml:"env,omitempty"`

	// Call controls how arguments are passed to the script.
	//   ""       / "args"       — named flags: --key value (default)
	//   "positional"            — positional args in schema property order
	//   "json"                  — JSON object on stdin
	Call string `yaml:"call,omitempty"`
}

type IncludeOptions struct {
	// BaseDir is used to resolve relative include paths.
	BaseDir string
	// MaxDepth limits recursive include expansion.
	MaxDepth int
	// AllowAbsolute allows absolute include paths.
	AllowAbsolute bool
}

type MCPConfig struct {
	Name    string `yaml:"name"`
	Command string `yaml:"command,omitempty"`
}

type MemoryConfig struct {
	// InsightsExpansion appends behavioral insights to the resolved system
	// prompt for sessions started with this agent. Default false.
	InsightsExpansion bool `yaml:"insights_expansion,omitempty"`
	// InsightsMaxTokens caps the insight block token budget. Default: 500.
	InsightsMaxTokens int `yaml:"insights_max_tokens,omitempty"`
}

type OutputToolConfig struct {
	Name        string `yaml:"name"`        // Tool name (e.g., "set_commit_message")
	Param       string `yaml:"param"`       // Parameter to capture (default: "content")
	Description string `yaml:"description"` // Tool description
}

type PlatformMessagesConfig struct {
	Web      string `yaml:"web_developer_message,omitempty"`
	Telegram string `yaml:"telegram_developer_message,omitempty"`
	Chat     string `yaml:"chat_developer_message,omitempty"`
	Jobs     string `yaml:"jobs_developer_message,omitempty"`
}

type ReadConfig struct {
	Dirs []string `yaml:"dirs,omitempty"`
}

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

type RegistryConfig struct {
	UseBuiltin  bool
	SearchPaths []string
}

type ShellConfig struct {
	Allow   []string          `yaml:"allow,omitempty"`
	AutoRun bool              `yaml:"auto_run,omitempty"`
	Scripts map[string]string `yaml:"scripts,omitempty"` // Named scripts (auto-approved)
}

type SpawnConfig struct {
	MaxParallel    int      `yaml:"max_parallel,omitempty"`   // Max concurrent sub-agents (default 3)
	MaxDepth       int      `yaml:"max_depth,omitempty"`      // Max nesting level (default 2)
	DefaultTimeout int      `yaml:"timeout,omitempty"`        // Default timeout in seconds (default 300)
	AllowedAgents  []string `yaml:"allowed_agents,omitempty"` // Optional whitelist of allowed agents
}

type TemplateContext struct {
	// Time-related
	Date     string // YYYY-MM-DD
	DateTime string // YYYY-MM-DD HH:MM:SS
	Time     string // HH:MM
	Year     string // YYYY

	// Directory info
	Cwd     string // Full working directory
	CwdName string // Directory name only
	Home    string // Home directory
	User    string // Username

	// Git info (empty if not a git repo)
	GitBranch   string // Current branch
	GitRepo     string // Repository name
	GitDiffStat string // Output of git diff --stat (staged + unstaged)

	// File context (from -f flags)
	Files     string // Comma-separated file names
	FileCount string // Number of files

	// System
	OS string // Operating system

	// Runtime surface (chat, console, web, telegram, jobs)
	Platform string

	// Active LLM
	Provider      string // Current provider name/key
	Model         string // Current model name
	ProviderModel string // Combined provider:model string

	// Agent context
	ResourceDir  string // Directory containing agent resources (for builtin agents)
	HandoverDir  string // XDG handover directory for the current project
	HandoverPath string // Full handover file path (date + random slug)

	// Project agent instructions (dynamically discovered)
	// Searches in priority order: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md,
	// .cursor/rules, CONTRIBUTING.md - returns first found
	Agents string
}

type ToolsConfig struct {
	// Enabled is an explicit allow list of tools
	Enabled []string `yaml:"enabled,omitempty"`
	// Disabled is a deny list (all others enabled)
	Disabled []string `yaml:"disabled,omitempty"`
	// Custom is a list of script-backed custom tools declared in agent.yaml
	Custom []CustomToolDef `yaml:"custom,omitempty"`
}