Documentation
¶
Index ¶
- Constants
- Variables
- func ClaudeStatuslineEnabled(c ClaudeConfig) bool
- func CodexStatuslineEnabled(c CodexConfig) bool
- func ExpandPath(value string, repoRoot string) (string, error)
- func ExpandPathIfNeeded(raw string, value string, repoRoot string) (string, error)
- func ExtractEnvVarNames(input string) []string
- func FieldOptionValues(key string) []string
- func HasAgentSpecificKey(agentSpecific map[string]any, key string) bool
- func HasLegacyGeminiConfig(data []byte) bool
- func IsAgentEnabled(p *bool) bool
- func IsBuiltInEnvVar(name string) bool
- func LoadCommandsAllow(path string) ([]string, error)
- func LoadCommandsAllowFS(fsys fs.FS, root string, path string) ([]string, error)
- func LoadEnv(path string) (map[string]string, error)
- func LoadEnvFS(fsys fs.FS, root string, path string) (map[string]string, error)
- func RequiredEnvVarsForMCPServer(server MCPServer) []string
- func RequiredEnvVarsForMCPServers(servers []MCPServer) []string
- func SharedAgentSkillsEnabled(agents AgentsConfig) bool
- func ShouldExpandPath(value string) bool
- func SubstituteEnvVars(input string, env map[string]string) (string, error)
- func SubstituteEnvVarsWith(input string, env map[string]string, replacer EnvVarReplacer) (string, error)
- func WithBuiltInEnv(env map[string]string, repoRoot string) map[string]string
- type AgentConfig
- type AgentsConfig
- type AntigravityConfig
- type ApprovalsConfig
- type ClaudeConfig
- type CodexConfig
- type Config
- func LoadConfig(path string) (*Config, error)
- func LoadConfigFS(fsys fs.FS, root string, path string) (*Config, error)
- func LoadConfigLenient(path string) (*Config, error)
- func LoadTemplateConfig() (*Config, error)
- func ParseConfig(data []byte, source string) (*Config, error)
- func ParseConfigLenient(data []byte, source string) (*Config, error)
- type DispatchConfig
- type EnableOnlyConfig
- type EnvVarReplacer
- type FieldDef
- type FieldOption
- type FieldType
- type InstructionFile
- type LegacySkillProjection
- type MCPConfig
- type MCPServer
- type Paths
- type ProjectConfig
- type Skill
- type WarningsConfig
Constants ¶
const ( ApprovalModeAll = "all" ApprovalModeCommands = "commands" ApprovalModeMCP = "mcp" ApprovalModeNone = "none" ApprovalModeYOLO = "yolo" )
Approval mode constants.
const ( TransportHTTP = "http" TransportStdio = "stdio" )
MCP transport type constants.
const BuiltinRepoRootEnvVar = "AL_REPO_ROOT"
BuiltinRepoRootEnvVar is the built-in placeholder for the repo root path.
Variables ¶
var CodexReservedKeys = map[string]struct{}{
"approval_policy": {},
"mcp_servers": {},
"model": {},
"model_reasoning_effort": {},
"projects": {},
"sandbox_mode": {},
"web_search": {},
}
CodexReservedKeys are top-level keys in .codex/config.toml managed by Agent Layer.
var ErrConfigNeedsUpgrade = errors.New("config requires migration")
ErrConfigNeedsUpgrade is a sentinel wrapped alongside ErrConfigValidation when a config fails validation because it contains a legacy key that only `al upgrade` can migrate (e.g. a removed agent table). Repair tools such as the wizard cannot rewrite these keys in place, so they use errors.Is(err, ErrConfigNeedsUpgrade) to redirect the user to `al upgrade` instead of attempting a fix that would dead-end at sync.
var ErrConfigValidation = errors.New("config validation failed")
ErrConfigValidation is a sentinel that wraps config validation failures (as opposed to TOML syntax, filesystem, or other loading errors). Callers can use errors.Is(err, ErrConfigValidation) to distinguish validation problems from other LoadProjectConfig failure modes.
var LegacySkillProjections = []LegacySkillProjection{ {Dir: []string{".codex", "skills"}, Suffix: "SKILL.md"}, {Dir: []string{".agent", "skills"}, Suffix: "SKILL.md"}, {Dir: []string{".gemini", "skills"}, Suffix: "SKILL.md"}, {Dir: []string{".github", "skills"}, Suffix: "SKILL.md"}, {Dir: []string{".vscode", "prompts"}, Suffix: ".prompt.md"}, }
LegacySkillProjections is the canonical list of retired projection paths. It is the single source of truth consumed by both the sync cleanup helper and the upgrade-readiness check.
Functions ¶
func ClaudeStatuslineEnabled ¶ added in v0.11.0
func ClaudeStatuslineEnabled(c ClaudeConfig) bool
ClaudeStatuslineEnabled reports whether the Claude status line should be projected and wired. It is explicit opt-in: only true enables it.
func CodexStatuslineEnabled ¶ added in v0.11.0
func CodexStatuslineEnabled(c CodexConfig) bool
CodexStatuslineEnabled reports whether the Codex status line should be wired. It is explicit opt-in: only true enables it.
func ExpandPath ¶ added in v0.5.6
ExpandPath expands "~" and resolves relative paths against repoRoot. value is the resolved string (placeholders already substituted).
func ExpandPathIfNeeded ¶ added in v0.5.6
ExpandPathIfNeeded expands value when the raw input signals a path placeholder.
func ExtractEnvVarNames ¶
ExtractEnvVarNames returns env var names referenced by ${VAR} placeholders. input is a string that may contain placeholders; returns names in scan order.
func FieldOptionValues ¶ added in v0.8.2
FieldOptionValues returns the option values for a field as a plain string slice. Returns nil when the key is not in the catalog or has no options.
func HasAgentSpecificKey ¶ added in v0.8.5
HasAgentSpecificKey returns true when the agent-specific map defines a top-level key.
func HasLegacyGeminiConfig ¶ added in v0.11.0
HasLegacyGeminiConfig reports whether `data` contains a legacy `[agents.gemini]` table or any subkey under it. Parses the raw TOML map so whitespace, tabs, comments, and TOML inline-table forms are all handled correctly — the previous space-strip substring scan missed tab-indented and comment-style configs.
func IsAgentEnabled ¶ added in v0.9.2
IsAgentEnabled returns true if the agent-enabled pointer is non-nil and true.
func IsBuiltInEnvVar ¶ added in v0.5.6
IsBuiltInEnvVar reports whether name is reserved for built-in placeholders.
func LoadCommandsAllow ¶
LoadCommandsAllow reads .agent-layer/commands.allow into a slice of prefixes.
func LoadCommandsAllowFS ¶ added in v0.5.7
LoadCommandsAllowFS reads .agent-layer/commands.allow from fsys into a slice of prefixes. root is used for path resolution when path is absolute; path is used for error messages.
func LoadEnvFS ¶ added in v0.5.7
LoadEnvFS reads .agent-layer/.env from fsys into a key-value map. root is used for path resolution when path is absolute; path is used for error messages.
func RequiredEnvVarsForMCPServer ¶
RequiredEnvVarsForMCPServer returns required env var names for a single MCP server. server is the MCP server definition; returns a sorted list of unique names.
func RequiredEnvVarsForMCPServers ¶
RequiredEnvVarsForMCPServers returns required env var names across all MCP servers. servers is a list of MCP server definitions; returns a sorted list of unique names.
func SharedAgentSkillsEnabled ¶ added in v0.10.0
func SharedAgentSkillsEnabled(agents AgentsConfig) bool
SharedAgentSkillsEnabled reports whether any agent that consumes the shared `.agents/skills/` projection is enabled. Adding a new shared-skill consumer means updating this function in one place; sync writers and readiness checks both read from it.
func ShouldExpandPath ¶ added in v0.5.6
ShouldExpandPath reports whether value requests path expansion. Path expansion is enabled when the value starts with "~" or "${AL_REPO_ROOT}".
func SubstituteEnvVars ¶
SubstituteEnvVars replaces ${VAR} placeholders using env values.
func SubstituteEnvVarsWith ¶
func SubstituteEnvVarsWith(input string, env map[string]string, replacer EnvVarReplacer) (string, error)
SubstituteEnvVarsWith replaces ${VAR} placeholders using env values and a replacer.
Types ¶
type AgentConfig ¶
type AgentConfig struct {
Enabled *bool `toml:"enabled"`
Model string `toml:"model"`
ReasoningEffort string `toml:"reasoning_effort"`
}
AgentConfig is for agents that support enablement and model selection. ReasoningEffort is present so the TOML decoder accepts the key without raising an unknown-key error; the validator then provides a specific error message for agents that do not support reasoning effort.
type AgentsConfig ¶
type AgentsConfig struct {
Antigravity AntigravityConfig `toml:"antigravity"`
Claude ClaudeConfig `toml:"claude"`
ClaudeVSCode EnableOnlyConfig `toml:"claude_vscode"`
Codex CodexConfig `toml:"codex"`
VSCode EnableOnlyConfig `toml:"vscode"`
CopilotCLI AgentConfig `toml:"copilot_cli"`
}
AgentsConfig holds per-client enablement and model selection.
type AntigravityConfig ¶ added in v0.11.0
type AntigravityConfig struct {
Enabled *bool `toml:"enabled"`
Dispatch DispatchConfig `toml:"dispatch"`
AgentSpecific map[string]any `toml:"agent_specific"`
}
AntigravityConfig is for the Antigravity (`agy`) client, which supports enablement and agent-specific settings passthrough but not model/effort (the agy CLI does not accept those flags).
type ApprovalsConfig ¶
type ApprovalsConfig struct {
Mode string `toml:"mode"`
}
ApprovalsConfig controls auto-approval behavior per client.
type ClaudeConfig ¶ added in v0.8.5
type ClaudeConfig struct {
Enabled *bool `toml:"enabled"`
Model string `toml:"model"`
ReasoningEffort string `toml:"reasoning_effort"`
Dispatch DispatchConfig `toml:"dispatch"`
LocalConfigDir *bool `toml:"local_config_dir"`
// DisableQuestionTool, when true, blocks Claude Code's AskUserQuestion tool.
// Sync injects permissions.deny + a PreToolUse hook into .claude/settings.json
// (merged with any user agent_specific entries). nil/false leave it allowed.
DisableQuestionTool *bool `toml:"disable_question_tool"`
// Statusline controls whether Agent Layer projects the editable
// .agent-layer/claude-statusline.sh source into .claude/claude-statusline.sh
// and wires statusLine into .claude/settings.json on sync. It is explicit
// opt-in: only true enables it. Read via
// ClaudeStatuslineEnabled.
Statusline *bool `toml:"statusline"`
AgentSpecific map[string]any `toml:"agent_specific"`
}
ClaudeConfig extends AgentConfig with Claude-specific settings.
type CodexConfig ¶
type CodexConfig struct {
Enabled *bool `toml:"enabled"`
Model string `toml:"model"`
ReasoningEffort string `toml:"reasoning_effort"`
Dispatch DispatchConfig `toml:"dispatch"`
// Statusline controls whether Agent Layer reads the editable
// .agent-layer/codex-statusline.toml source and injects its native
// tui.status_line list into .codex/config.toml on sync. It is explicit
// opt-in: only true enables it. Read via
// CodexStatuslineEnabled.
Statusline *bool `toml:"statusline"`
AgentSpecific map[string]any `toml:"agent_specific"`
}
CodexConfig extends AgentConfig with Codex-specific settings.
type Config ¶
type Config struct {
Approvals ApprovalsConfig `toml:"approvals"`
Agents AgentsConfig `toml:"agents"`
MCP MCPConfig `toml:"mcp"`
Warnings WarningsConfig `toml:"warnings"`
}
Config is the root configuration loaded from .agent-layer/config.toml.
func LoadConfig ¶
LoadConfig reads .agent-layer/config.toml and validates it.
func LoadConfigFS ¶ added in v0.5.7
LoadConfigFS reads .agent-layer/config.toml from fsys and validates it. root is used for path resolution when path is absolute; path is used for error messages.
func LoadConfigLenient ¶ added in v0.8.2
LoadConfigLenient reads .agent-layer/config.toml without validation. Returns an error only on filesystem or TOML syntax errors.
func LoadTemplateConfig ¶
LoadTemplateConfig returns the embedded default config template as a validated Config.
func ParseConfig ¶
ParseConfig parses and validates config TOML data from a source identifier. data is the TOML content; source is used in error messages.
func ParseConfigLenient ¶ added in v0.8.2
ParseConfigLenient parses config TOML data without validation. Returns an error only on TOML syntax errors. Missing or invalid fields are not checked, making this suitable for repair tools (wizard, doctor) that need to read partially valid configs.
type DispatchConfig ¶ added in v0.11.0
type DispatchConfig struct {
DefaultAgent string `toml:"default_agent"`
}
DispatchConfig controls Agent Dispatch defaults for a caller agent.
type EnableOnlyConfig ¶ added in v0.8.5
type EnableOnlyConfig struct {
Enabled *bool `toml:"enabled"`
}
EnableOnlyConfig is for agents that support enablement but not model selection.
type EnvVarReplacer ¶
EnvVarReplacer returns a replacement string for a resolved env var.
type FieldDef ¶ added in v0.8.2
type FieldDef struct {
Key string
Type FieldType
Required bool
Options []FieldOption
AllowCustom bool // when true, enum fields also accept freetext values
}
FieldDef describes a single config field's type, constraints, and valid options.
func Fields ¶ added in v0.8.2
func Fields() []FieldDef
Fields returns a copy of all registered field definitions in catalog order.
func LookupField ¶ added in v0.8.2
LookupField returns the field definition for the given config key. Returns false when the key is not in the catalog.
type FieldOption ¶ added in v0.8.2
type FieldOption struct {
Value string
Description string // empty for options without descriptions
}
FieldOption describes a single selectable value for a field.
type FieldType ¶ added in v0.8.2
type FieldType string
FieldType classifies the kind of value a config field accepts.
const ( // FieldBool accepts true or false. FieldBool FieldType = "bool" // FieldEnum accepts one of a fixed set of options. FieldEnum FieldType = "enum" // FieldFreetext accepts arbitrary string input. FieldFreetext FieldType = "freetext" // FieldPositiveInt accepts a positive integer. FieldPositiveInt FieldType = "positive_int" )
type InstructionFile ¶
InstructionFile holds a single instruction fragment.
func LoadInstructions ¶
func LoadInstructions(dir string) ([]InstructionFile, error)
LoadInstructions reads .agent-layer/instructions/*.md in lexicographic order.
func LoadInstructionsFS ¶ added in v0.5.7
LoadInstructionsFS reads .agent-layer/instructions/*.md from fsys in lexicographic order. root is used for path resolution when dir is absolute; dir is used for error messages.
type LegacySkillProjection ¶ added in v0.10.0
LegacySkillProjection names a retired client-side directory that Agent Layer claims exclusive ownership of and removes during every sync. The Suffix is the file extension used to locate generated artifacts during readiness detection. See docs/SKILL-CLIENT-SPEC.md "Ownership of legacy projection paths" for the rationale.
type MCPConfig ¶
type MCPConfig struct {
Servers []MCPServer `toml:"servers"`
}
MCPConfig contains the external MCP servers configuration.
type MCPServer ¶
type MCPServer struct {
ID string `toml:"id"`
Enabled *bool `toml:"enabled"`
Clients []string `toml:"clients"`
Transport string `toml:"transport"`
HTTPTransport string `toml:"http_transport"`
URL string `toml:"url"`
Headers map[string]string `toml:"headers"`
Command string `toml:"command"`
Args []string `toml:"args"`
Env map[string]string `toml:"env"`
}
MCPServer defines a single MCP server entry.
func (MCPServer) AppliesToClient ¶
AppliesToClient reports whether the server is enabled for the given client.
type Paths ¶
type Paths struct {
Root string
ConfigPath string
EnvPath string
InstructionsDir string
SkillsDir string
CommandsAllow string
}
Paths holds resolved paths for config files and directories.
func DefaultPaths ¶
DefaultPaths returns the default config paths for a repo root.
type ProjectConfig ¶
type ProjectConfig struct {
Config Config
Env map[string]string
Instructions []InstructionFile
Skills []Skill
CommandsAllow []string
Root string
}
ProjectConfig is the fully loaded configuration state for sync and launch.
func LoadProjectConfig ¶
func LoadProjectConfig(root string) (*ProjectConfig, error)
LoadProjectConfig reads and validates the full Agent Layer config from disk.
func LoadProjectConfigFS ¶ added in v0.5.7
func LoadProjectConfigFS(fsys fs.FS, root string) (*ProjectConfig, error)
LoadProjectConfigFS reads and validates the full Agent Layer config from an fs.FS rooted at repo root. fsys is the filesystem to read from; root is used for error messages and built-in env values.
type Skill ¶ added in v0.9.0
type Skill struct {
Name string
Description string
License string
Compatibility string
Metadata map[string]string
AllowedTools string
Body string
SourcePath string
SourceDir string // Absolute path to the skill directory (parent of SKILL.md)
}
Skill represents a parsed skill with metadata and body.
func LoadSkills ¶ added in v0.9.0
LoadSkills reads .agent-layer/skills from disk. Supported source format: - .agent-layer/skills/<name>/SKILL.md (canonical; fallback to skill.md for compatibility) Flat-format .agent-layer/skills/<name>.md files are rejected with actionable errors. Directories without a supported skill file also fail loudly.
func LoadSkillsFS ¶ added in v0.9.0
LoadSkillsFS reads .agent-layer/skills from fsys. root is used for path resolution when dir is absolute; dir is used for error messages. Directories without a supported skill file fail loudly.
type WarningsConfig ¶
type WarningsConfig struct {
VersionUpdateOnSync *bool `toml:"version_update_on_sync"`
NoiseMode string `toml:"noise_mode"`
InstructionTokenThreshold *int `toml:"instruction_token_threshold"`
MCPServerThreshold *int `toml:"mcp_server_threshold"`
MCPToolsTotalThreshold *int `toml:"mcp_tools_total_threshold"`
MCPServerToolsThreshold *int `toml:"mcp_server_tools_threshold"`
MCPSchemaTokensTotalThreshold *int `toml:"mcp_schema_tokens_total_threshold"`
MCPSchemaTokensServerThreshold *int `toml:"mcp_schema_tokens_server_threshold"`
}
WarningsConfig configures optional warning thresholds. Nil fields disable their warnings.