config

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 5, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package config loads and validates squad configuration settings.

Index

Constants

View Source
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

func AgentsCacheDir() (string, error)

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 CacheFile

func CacheFile(filename string) (string, error)

CacheFile returns the path for a cache file.

func ConfigFile

func ConfigFile(filename string) (string, error)

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

func ResolveValue(s string) (string, error)

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

func SetDefaults(v *viper.Viper)

SetDefaults registers all hardcoded default values on a Viper instance.

func SkillsCacheDir

func SkillsCacheDir() (string, error)

SkillsCacheDir returns the directory for caching cloned skill catalog repositories. Mirrors AgentsCacheDir so the two stay in lockstep.

func StateDir added in v0.2.0

func StateDir() string

StateDir returns the squad state directory (e.g., ~/.local/state/squad).

func StateFile added in v0.2.0

func StateFile(filename string) (string, error)

StateFile returns the path for a state file, creating directories as needed.

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.

func Load

func Load() (*Config, *viper.Viper, error)

Load loads config from standard locations with env and defaults. It returns the resolved Config and the Viper instance that produced it, so callers can bind additional flags without recreating the precedence chain.

func LoadFromPath

func LoadFromPath(path string) (*Config, *viper.Viper, error)

LoadFromPath loads config from an explicit path. It returns the resolved Config and the Viper instance that produced it.

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

func (r RepoSpec) IsPinned() bool

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

func (r RepoSpec) MarshalYAML() (any, error)

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

func (r *RepoSpec) UnmarshalYAML(node *yaml.Node) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL