Documentation
¶
Overview ¶
Package config implements v0.1 of the `.agents/` discovery and loading rules from docs/config-layout-design.md.
Discovery ¶
The `.agents/` root is looked up in exactly one location per invocation — EXCLUSIVE, first match wins, no cross-location merging:
- $MAST_CONFIG_DIR — if set, it is the canonical location and nothing else is consulted. If it does not exist, that is a fatal error (we never silently fall through past an explicit override).
- ./.agents in the process working directory.
- <user config dir>/mast/agents (os.UserConfigDir; XDG-compliant on Linux, i.e. ~/.config/mast/agents).
- /etc/mast/agents (system-level).
Because selection is exclusive, an EXISTING-but-EMPTY higher-priority location shadows a populated lower-priority one. That is by design (deterministic, no merge-order bugs) but is a known operator footgun, so loading logs loudly: which root was selected, why, what was found in it, and which existing lower-priority locations it shadows.
File discovery within the root ¶
Per-directory scans are flat and non-recursive; nested subdirectories are ignored (operators may keep e.g. workloads/archive/):
- <root>/workloads/*.yaml (also *.yml) — parsed by pkg/workload.
- <root>/specialists/*.tmpl — parsed by pkg/specialists.
- <root>/a2a/*.yaml (also *.yml) — static A2A agent registrations, parsed by pkg/a2a (docs/a2a-design.md, "Static registration").
A missing subdirectory yields zero entries; it is not an error. Two files defining the same name in the same directory are a fatal load-time error (v0.1: fail fast, operator resolves). All load-time validation errors are fatal — mast refuses to start on invalid config. There is no hot-reload in v0.1; changes require restart.
Env-var overrides ¶
Scalar config values can be overridden by environment variables following the convention from config-layout-design.md: the config key path, uppercased, dots/nesting replaced with underscores, with the MAST_ prefix. For the workload budget block implemented in v0.1:
budget.max_cost_usd → MAST_BUDGET_MAX_COST_USD budget.max_wallclock_seconds → MAST_BUDGET_MAX_WALLCLOCK_SECONDS
Env overrides are process-wide: they apply to every workload bundle loaded in this invocation, and they override file values unconditionally. A set-but-unparseable override is a fatal load-time error.
Index ¶
Constants ¶
const ( EnvBudgetMaxCostUSD = "MAST_BUDGET_MAX_COST_USD" EnvBudgetMaxWallclockSeconds = "MAST_BUDGET_MAX_WALLCLOCK_SECONDS" )
Env var names for the v0.1 scalar workload-budget overrides. See the package documentation for the key→env mapping convention.
const EnvConfigDir = "MAST_CONFIG_DIR"
EnvConfigDir is the env var that, when set, exclusively selects the `.agents/` root.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Root is the selected root plus provenance.
Root Root
// Workloads maps workload name → loaded bundle
// (<root>/workloads/*.yaml, flat scan).
Workloads map[string]workload.Bundle
// Specialists maps specialist name → loaded spec
// (<root>/specialists/*.tmpl, flat scan).
Specialists map[string]specialists.Spec
// A2A maps remote-agent name → static A2A registration
// (<root>/a2a/*.yaml, flat scan). Consumed by a2a.NewAdapter for
// the federation registry's a2a:// scheme.
A2A map[string]a2a.AgentConfig
}
Config is the loaded contents of the selected `.agents/` root.
func Load ¶
Load discovers the `.agents/` root and loads it. Equivalent to Discover followed by LoadRoot.
func LoadRoot ¶
LoadRoot loads workloads and specialists from the given root, applies env-var budget overrides, and cross-validates workload specialist rosters against the loaded specialist set. All errors are fatal load-time errors per config-layout-design.md v0.1.
LoadRoot logs loudly — selected root, provenance, per-directory findings, shadowed lower-priority locations — because exclusive single-location discovery means an empty selected root silently shadows a populated one elsewhere.
func (*Config) A2AList ¶
func (c *Config) A2AList() []a2a.AgentConfig
A2AList returns the loaded A2A registrations in name order — the shape a2a.NewAdapter takes.
type Root ¶
type Root struct {
// Dir is the absolute path of the selected root directory.
Dir string
// Source records which discovery rule matched.
Source Source
// Shadowed lists existing lower-priority candidate locations that
// were NOT consulted because Dir won. Used for loud logging of the
// "empty project dir shadows populated user dir" footgun.
Shadowed []string
}
Root is the selected `.agents/` root plus provenance.
type Source ¶
type Source string
Source identifies which discovery rule selected the `.agents/` root.
const ( // SourceEnv — $MAST_CONFIG_DIR was set. SourceEnv Source = "env:MAST_CONFIG_DIR" // SourceProject — ./.agents in the process working directory. SourceProject Source = "project:./.agents" // SourceUser — <user config dir>/mast/agents. SourceUser Source = "user:config-dir" // SourceSystem — /etc/mast/agents. SourceSystem Source = "system:/etc/mast/agents" )
Source Files