config

type AgentConfig struct {
	// Name 必须和文件名一致。
	Name string `yaml:"name"`
	// Description 是 Agent 的用途说明。
	Description string `yaml:"description,omitempty"`
	// Instructions 是 Agent 的指令，不能为空。
	Instructions string `yaml:"instructions"`
	// Model 是 Agent 的主模型；省略时加载后取默认模型，模型目录为空时保持为 nil。
	Model *AgentModelConfig `yaml:"model,omitempty"`
	// CompactModel 是生成上下文摘要使用的模型；省略时使用 Model。
	CompactModel *AgentModelConfig `yaml:"compact_model,omitempty"`
	// Tools 是可用普通工具名，由使用方的工具目录解释；省略时可用全部普通工具。
	Tools []string `yaml:"tools,omitempty"`
	// Skills 是可用 skill 名，由使用方的 skill 目录解释；省略时可用全部 skill。
	Skills []string `yaml:"skills,omitempty"`
	// MCPServers 是可用的 MCP server id；省略时全部可用（包括客户端连接带来的 MCP server），[] 表示不用 MCP。
	MCPServers defs.OptionalStringList `yaml:"mcp_servers,omitempty"`
}

type AgentModelConfig struct {
	Provider string `yaml:"provider"`
	Model    string `yaml:"model,omitempty"`
}

type Config struct {
	Agents *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"agents" flag:"agents-dir"`
	} `mapstructure:"agents" yaml:"agents"`
	Models *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"models" flag:"models-dir"`
		// DefaultModel 是没写 model 的 Agent 使用的模型，格式 provider_id/model_id；为空时取模型目录里按 Provider id、模型 id 排序的第一个。
		DefaultModel string `mapstructure:"default_model" yaml:"default_model"`
		// Defaults 是模型配置省略字段时使用的值；default 标签就是系统内置默认值。
		Defaults *defs.ModelDefaults `mapstructure:"defaults" yaml:"defaults"`
	} `mapstructure:"models" yaml:"models"`
	Skills *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"skills"`
	} `mapstructure:"skills" yaml:"skills"`
	Executors *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"executors"`
	} `mapstructure:"executors" yaml:"executors"`
	MCPServers *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"mcp_servers"`
	} `mapstructure:"mcp_servers" yaml:"mcp_servers"`
	Hooks *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"hooks"`
	} `mapstructure:"hooks" yaml:"hooks"`
	Plugins *struct {
		Directory string `mapstructure:"directory" yaml:"directory" default:"plugins"`
		// Disabled 是不加载的插件名：它们的 skill、hook、MCP server 都没有；写了不存在的名字不报错。
		Disabled []string `mapstructure:"disabled" yaml:"disabled"`
	} `mapstructure:"plugins" yaml:"plugins"`
	Tools *struct {
		// MaxImageKB 是 read_file 交给模型的单张图片上限（KB），超过就压缩。
		MaxImageKB int `mapstructure:"max_image_kb" yaml:"max_image_kb" default:"500"`
	} `mapstructure:"tools" yaml:"tools"`
	Run *struct {
		AgentName string `mapstructure:"agent_name" yaml:"agent_name" default:"default" flag:"agent"`
	} `mapstructure:"run" yaml:"run"`
	Server *struct {
		// Listen 是 Runtime Server 的监听地址；局域网访问时设为 0.0.0.0:<port>。
		Listen string `mapstructure:"listen" yaml:"listen" default:"127.0.0.1:8790"`
		// Token 是 Runtime Server 的访问令牌，明文保存；为空时 serve 生成并复用 runtime-server.yaml 里的 token。
		Token string `mapstructure:"token" yaml:"token"`
		// WorkspaceDirectory 是新对话没指定目录时 local Executor 用的目录；为空时用 serve 的启动目录。支持 ~/ 开头。
		WorkspaceDirectory string `mapstructure:"workspace_directory" yaml:"workspace_directory"`
	} `mapstructure:"server" yaml:"server"`
	Client *struct {
		// URL 是客户端命令（TUI、acp、app-server、codex）连接的 Runtime Server；为空时用本机 serve，没在跑就拉起。
		URL string `mapstructure:"url" yaml:"url"`
		// Token 是连接 token；URL 自带 ?token= 时以 URL 为准。
		Token string `mapstructure:"token" yaml:"token"`
		// PathMappings 把客户端路径换成 serve 路径，ACP、app-server 收发时转换，TUI 只转换启动时的 cwd；只能在配置文件中设置。
		PathMappings PathMappings `mapstructure:"path_mappings" yaml:"path_mappings"`
	} `mapstructure:"client" yaml:"client"`
	Telemetry *struct {
		// LogLevel 是日志最低级别：debug、info、warn 或 error，同时作用于日志文件、stderr 与 OTLP。
		LogLevel string `mapstructure:"log_level" yaml:"log_level" default:"info"`
		// LogFile 是日志文件路径；为空时为 ~/.local/state/openvaala/openvaala.log，相对路径按配置文件所在目录展开。
		LogFile string `mapstructure:"log_file" yaml:"log_file"`
		// OTLPEndpoint 是 OTLP HTTP 的基础地址，例如 http://127.0.0.1:4318；各信号路径 /v1/traces、/v1/metrics、/v1/logs
		// 会自动追加在其后，不要自带信号路径；为空时不导出 trace、指标与日志。
		OTLPEndpoint string `mapstructure:"otlp_endpoint" yaml:"otlp_endpoint"`
		// OTLPHeaders 是导出时附带的请求头，例如鉴权；只能在配置文件中设置，键名会被统一转为小写。
		OTLPHeaders map[string]string `mapstructure:"otlp_headers" yaml:"otlp_headers"`
		// CaptureContent 是否把对话内容（系统指令、消息、模型输出、工具参数与结果）写入 trace？默认开启；只在配置了
		// otlp_endpoint 时随 trace 导出，日志与指标不含内容。开启时读到的敏感文件内容也可能经工具结果发往 OTLP 后端，不需要时设为 false。
		CaptureContent bool `mapstructure:"capture_content" yaml:"capture_content" default:"true"`
	} `mapstructure:"telemetry" yaml:"telemetry"`
	// contains filtered or unexported fields
}

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

type Error struct {
	Path   string
	Field  string
	Reason string
}

type ExecutorConfig struct {
	ID string `yaml:"id"`
	// Kind 是 local（本机进程内执行）、virtual（go-bash 内存虚拟环境）或 ssh（经 SSH 访问远端机器）。
	Kind defs.ExecutorKind `yaml:"kind"`
	// Description 是给模型看的说明，模型据此选 Executor。
	Description string `yaml:"description"`
	// WorkspaceDirectory 是内置工具的根目录：local 是本机目录，virtual 是虚拟文件系统里的路径，ssh 是远端绝对路径。
	WorkspaceDirectory string `yaml:"workspace_directory"`
	// SSH 是 kind 为 ssh 时的连接参数，其他 kind 不使用。
	SSH *SSHExecutorConfig `yaml:"ssh,omitempty"`
}

type HookFileConfig struct {
	Hooks map[string][]HookMatcherConfig `yaml:"hooks"`
}

type HookHandlerConfig struct {
	// Type 目前只支持 command。
	Type string `yaml:"type"`
	// Command 与 Script 必须且只能写一个：Command 在目标机器上原样执行，Script 是 serve 本机的脚本文件，运行前拷到目标机器。
	Command string `yaml:"command,omitempty"`
	Script  string `yaml:"script,omitempty"`
	// Args 只能和 Script 一起用，跟在脚本路径后面。
	Args []string `yaml:"args,omitempty"`
	// Timeout 是最多运行多少秒，省略时 60，写了必须为正数。
	Timeout *int `yaml:"timeout,omitempty"`
	// OnFailure 是出错时的处理：allow（默认）或 block；只能用于 PreToolUse 和 UserPromptSubmit。
	OnFailure string `yaml:"on_failure,omitempty"`
}

type HookMatcherConfig struct {
	// Matcher 按事件挑选命中的 hook；省略、空串或 * 表示全部匹配。
	Matcher string              `yaml:"matcher,omitempty"`
	Hooks   []HookHandlerConfig `yaml:"hooks"`
}

type InstallPluginRequest struct {
	// Source 是 git 地址或已存在的本机目录；是本机目录时直接拷贝，不用 git。
	Source string
	// Path 是插件在仓库里的目录，必须是仓库内的相对路径；为空时是仓库根目录。
	Path string
	// Ref 是 git clone 的分支或 tag，只能用于 git 地址；为空时用默认分支。
	Ref string
}

type LoadConfigOpt struct {
	// Home 是用户主目录，为空时取系统用户目录。
	Home string
	// Path 是配置文件路径，为空时先看 OPENVAALA_CONFIG，再用 ~/.config/openvaala/config.yaml。
	Path string
	// Flags 是命令行 flag，显式设置的值覆盖文件和环境变量。
	Flags *pflag.FlagSet
}

type MCPServerConfig struct {
	ID      string            `yaml:"id"`
	Type    string            `yaml:"type"` // 传输类型：stdio、http 或 sse。
	Command string            `yaml:"command,omitempty"`
	Args    []string          `yaml:"args,omitempty"`
	Env     map[string]string `yaml:"env,omitempty"`
	URL     string            `yaml:"url,omitempty"`
	Headers map[string]string `yaml:"headers,omitempty"`
	// Executors 是在哪些 Executor 上运行；省略时为 [local]。
	Executors []string `yaml:"executors,omitempty"`
	// Tools 是提供给模型的工具原名名单；省略时全部提供。
	Tools []string `yaml:"tools,omitempty"`
	// Required 为 true 时连不上让这一轮报错；省略时连不上就跳过。
	Required bool `yaml:"required,omitempty"`
	// Disabled 为 true 时保留文件但不使用。
	Disabled bool `yaml:"disabled,omitempty"`
	// StartupTimeoutSeconds 是一次连接最多等多久，省略时 30。
	StartupTimeoutSeconds int `yaml:"startup_timeout_seconds,omitempty"`
	// ToolTimeoutSeconds 是一次工具调用最多等多久，省略时 300。
	ToolTimeoutSeconds int `yaml:"tool_timeout_seconds,omitempty"`
	// Plugin 是声明这个 server 的插件；mcp_servers/ 里的文件为 nil。
	Plugin *defs.Plugin `yaml:"-"`
}

type PathMapping struct {
	Client string `mapstructure:"client" yaml:"client"`
	Server string `mapstructure:"server" yaml:"server"`
}

type PathMappings []PathMapping

type PluginInstallRecord struct {
	Source      string    `yaml:"source"`           // git 地址或本机绝对路径
	Ref         string    `yaml:"ref,omitempty"`    // 空时用默认分支
	Path        string    `yaml:"path,omitempty"`   // 插件在仓库里的目录；根目录时为空
	Commit      string    `yaml:"commit,omitempty"` // git 来源安装时的 commit
	InstalledAt time.Time `yaml:"installed_at"`
}

type PluginListEntry struct {
	// Name 是 plugins 目录下的条目名；Version 取自 manifest，读不到 manifest 时为空。
	Name, Version string
	// IsDisabled 名字是否写在 plugins.disabled 里？
	IsDisabled bool
	// Record 是 plugin install 写的安装记录；手动放入的为 nil。
	Record *PluginInstallRecord
	// Error 是这一项不能当插件用的原因，例如没有 manifest。
	Error string
}

type PluginManifest struct {
	Name        string `yaml:"name"`
	Version     string `yaml:"version,omitempty"`
	Description string `yaml:"description,omitempty"`
	// Skills 是 skill 目录，相对插件根目录；省略时为 ./skills/，目录不存在就没有 skill。
	Skills     string                         `yaml:"skills,omitempty"`
	Hooks      map[string][]HookMatcherConfig `yaml:"hooks,omitempty"`
	MCPServers []*MCPServerConfig             `yaml:"mcp_servers,omitempty"`
}

type SSHExecutorConfig struct {
	// Address 是 [user@]host[:port]。
	Address string `yaml:"address"`
	// IdentityFile 是本机私钥路径，加载时展开 ~；为空时依次使用 ssh-agent 与默认私钥。
	IdentityFile string `yaml:"identity_file,omitempty"`
}