Documentation
¶
Overview ¶
Package config loads and validates squad configuration settings.
Index ¶
- Constants
- func AgentsCacheDir() (string, error)
- func CacheDir() string
- func CacheFile(filename string) (string, error)
- func ConfigFile(filename string) (string, error)
- func DecodeHooks() viper.DecoderConfigOption
- func GetConfigDirs() []string
- func ResolveValue(s string) (string, error)
- func SetDefaults(v *viper.Viper)
- func SkillsCacheDir() (string, error)
- func StateDir() string
- func StateFile(filename string) (string, error)
- type AgentsConfig
- type Config
- type LogConfig
- type ModelConfig
- type OtelConfig
- type ProviderConfig
- type RepoSpec
- type RunConfig
- type SkillsConfig
Constants ¶
const ( // FilePermReadWrite is the file mode used for config files. FilePermReadWrite = 0o600 // DirPermReadWriteExec is the directory mode used for config folders. DirPermReadWriteExec = 0o700 )
Variables ¶
This section is empty.
Functions ¶
func AgentsCacheDir ¶
AgentsCacheDir returns the directory for caching cloned agent repositories.
func CacheDir ¶
func CacheDir() string
CacheDir returns the squad cache directory (e.g., ~/.cache/squad).
func ConfigFile ¶
ConfigFile returns the path for creating a new config file.
func DecodeHooks ¶
func DecodeHooks() viper.DecoderConfigOption
DecodeHooks returns the viper.DecoderConfigOption that registers every custom mapstructure hook the loader needs. The default viper hooks (StringToTimeDurationHookFunc, StringToSliceHookFunc) are re-installed alongside repoSpecDecodeHook so env-var slice expansion still works.
Callers that re-unmarshal viper state into a Config — typically to apply late CLI-flag overrides — must thread this option through their v.Unmarshal call, otherwise repository entries written as plain strings will fail to decode.
func GetConfigDirs ¶
func GetConfigDirs() []string
GetConfigDirs returns all config directories to search in priority order.
func ResolveValue ¶
ResolveValue performs variable and command substitution on a config string.
Supported patterns:
- $VAR or ${VAR} — replaced by the environment variable value
- $(command args) — replaced by the stdout of the command
Unset variables and failed commands return errors rather than empty strings, so misconfigurations are caught early.
func SetDefaults ¶
SetDefaults registers all hardcoded default values on a Viper instance.
func SkillsCacheDir ¶
SkillsCacheDir returns the directory for caching cloned skill catalog repositories. Mirrors AgentsCacheDir so the two stay in lockstep.
Types ¶
type AgentsConfig ¶
type AgentsConfig struct {
// CacheDir is where cloned git repositories are cached.
CacheDir string `mapstructure:"cache_dir" yaml:"cache_dir"`
// Repositories maps repository names to Git sources. Each entry is
// either a plain URL (the legacy form, tracks the default branch) or
// a {url, ref} mapping that pins the source to a specific commit,
// tag, or branch. See [RepoSpec].
// Example:
// repositories:
// official: https://github.com/cowdogmoo/squad-agents.git
// private:
// url: git@github.com:myorg/private-agents.git
// ref: v1.2.0
Repositories map[string]RepoSpec `mapstructure:"repositories" yaml:"repositories"`
// LocalPaths lists local directories to search for agents.
// Example:
// local_paths:
// - /opt/shared/agents
// - ~/dev/my-agents
LocalPaths []string `mapstructure:"local_paths" yaml:"local_paths"`
}
AgentsConfig holds agent source configuration.
type Config ¶
type Config struct {
Log LogConfig `mapstructure:"log" yaml:"log"`
Provider ProviderConfig `mapstructure:"provider" yaml:"provider"`
Model ModelConfig `mapstructure:"model" yaml:"model"`
Agents AgentsConfig `mapstructure:"agents" yaml:"agents"`
Skills SkillsConfig `mapstructure:"skills" yaml:"skills"`
Otel OtelConfig `mapstructure:"otel" yaml:"otel"`
Run RunConfig `mapstructure:"run" yaml:"run"`
}
Config represents the global squad configuration. Its zero value is not useful; use Defaults or Load to initialize it.
func Defaults ¶
func Defaults() *Config
Defaults returns a config populated with sensible defaults. All default values are defined once in SetDefaults; this function derives the struct from that single source of truth.
type LogConfig ¶
type LogConfig struct {
// Level is the minimum log level: debug, info, warn, or error.
Level string `mapstructure:"level" yaml:"level"`
// Format is the log output format: text or json.
Format string `mapstructure:"format" yaml:"format"`
}
LogConfig holds logging configuration.
type ModelConfig ¶
type ModelConfig struct {
// Default is the model identifier used when none is specified on the
// command line or in an agent manifest.
Default string `mapstructure:"default" yaml:"default"`
// Temperature controls sampling randomness (0.0 = deterministic).
Temperature float64 `mapstructure:"temperature" yaml:"temperature"`
// MaxTokens is the default output-token budget per request.
MaxTokens int `mapstructure:"max_tokens" yaml:"max_tokens"`
// ReasoningPrefixes lists model name prefixes that support extended
// reasoning; requests to these models use higher token budgets.
ReasoningPrefixes []string `mapstructure:"reasoning_prefixes" yaml:"reasoning_prefixes"`
// IterationFactor scales an agent's base iteration budget per model, to
// account for how efficiently a given model converges. Keyed by model
// name (e.g. "gpt-oss-120b": 3.0); a "default" key applies to any model
// without its own entry. Missing or non-positive values mean 1.0.
IterationFactor map[string]float64 `mapstructure:"iteration_factor" yaml:"iteration_factor"`
}
ModelConfig holds model defaults.
type OtelConfig ¶
type OtelConfig struct {
// Endpoint is the OTLP gRPC endpoint (e.g., "localhost:4317").
// An empty string disables telemetry export.
Endpoint string `mapstructure:"endpoint" yaml:"endpoint"`
}
OtelConfig holds OpenTelemetry configuration.
type ProviderConfig ¶
type ProviderConfig struct {
// Default is the provider name used when none is specified on the
// command line or in an agent manifest (e.g., "openai", "anthropic").
Default string `mapstructure:"default" yaml:"default"`
// BaseURL overrides the provider's default API endpoint URL.
BaseURL string `mapstructure:"base_url" yaml:"base_url"`
// Organization is the OpenAI organization ID, if required.
Organization string `mapstructure:"organization" yaml:"organization"`
// APIVersion is used by Azure OpenAI and other versioned APIs.
APIVersion string `mapstructure:"api_version" yaml:"api_version"`
// APIType selects the API variant (e.g., "azure" for Azure OpenAI).
APIType string `mapstructure:"api_type" yaml:"api_type"`
// OpenAICompatMaxTokens enforces max_tokens in OpenAI-compatible
// requests even when the provider does not strictly require it.
OpenAICompatMaxTokens bool `mapstructure:"openai_compat_max_tokens" yaml:"openai_compat_max_tokens"`
// Token is the API key or bearer token. It supports command
// substitution ($(cmd)) and env-var references ($VAR).
Token string `mapstructure:"token" yaml:"token"`
// NumCtx is the context window size for Ollama models.
NumCtx int `mapstructure:"num_ctx" yaml:"num_ctx"`
}
ProviderConfig holds provider defaults.
type RepoSpec ¶
type RepoSpec struct {
URL string `yaml:"url" mapstructure:"url"`
Ref string `yaml:"ref,omitempty" mapstructure:"ref"`
}
RepoSpec describes a git-hosted agent or skill repository. URL is required; Ref optionally pins the source to a commit SHA, tag, or branch so the same agent/skill resolves to the same content on every clone or update. An empty Ref tracks the default branch — the original pre-pinning behavior.
func (RepoSpec) IsPinned ¶
IsPinned reports whether the spec is locked to a specific ref. Pinned sources are skipped by `update` unless the caller forces a re-resolve.
func (RepoSpec) MarshalYAML ¶
MarshalYAML keeps the on-disk config compact: a spec with no Ref serializes back to a plain string, matching configs that pre-date the pinning feature. Specs with a Ref serialize as a mapping.
func (*RepoSpec) UnmarshalYAML ¶
UnmarshalYAML accepts both the legacy plain-string form (`official: https://...`) and the explicit struct form (`official: {url: ..., ref: v1.0.0}`). The string form is the historical configuration; the struct form is opt-in for pinning.
type RunConfig ¶
type RunConfig struct {
// Isolation is the default isolation mode when neither the CLI flag nor
// the agent manifest specifies one. Valid values: "" (none) or "worktree".
Isolation string `mapstructure:"isolation" yaml:"isolation"`
// MaxRetries is the number of additional attempts after a failed LLM
// call for transient errors (rate limits, 5xx, network blips). Total
// attempts = MaxRetries + 1. Zero or negative falls back to the
// package default in tools/retry.go.
MaxRetries int `mapstructure:"max_retries" yaml:"max_retries"`
}
RunConfig holds run-time defaults that apply to every agent invocation.
type SkillsConfig ¶
type SkillsConfig struct {
// CacheDir is where cloned skill catalog repositories are cached.
// Empty falls through to config.SkillsCacheDir().
CacheDir string `mapstructure:"cache_dir" yaml:"cache_dir"`
// Repositories maps a catalog alias to its Git source. Like
// [AgentsConfig.Repositories], entries accept either a plain URL
// string or a {url, ref} mapping that pins the catalog to a commit,
// tag, or branch.
Repositories map[string]RepoSpec `mapstructure:"repositories" yaml:"repositories"`
// LocalPaths lists additional directories to search for skill
// subdirectories. Each path is treated as a catalog root and its
// immediate subdirectories are scanned for SKILL.md files.
LocalPaths []string `mapstructure:"local_paths" yaml:"local_paths"`
}
SkillsConfig holds Agent Skills catalog configuration. The shape mirrors AgentsConfig so the same mental model applies: skills come from local directories you've registered, plus git repositories that squad clones into a local cache on demand. The per-repo and global scopes are not configured here — they live at well-known filesystem locations.