config

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: May 27, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Package config loads and validates AGH configuration.

Index

Constants

View Source
const (
	// DefaultCoordinatorAgentName is the bundled coordinator identity used when config is silent.
	DefaultCoordinatorAgentName = "coordinator"
	// DefaultCoordinatorTTL is the conservative coordinator session TTL used by autonomy defaults.
	DefaultCoordinatorTTL = 2 * time.Hour
	// MinCoordinatorTTL is the shortest coordinator TTL accepted by config validation.
	MinCoordinatorTTL = time.Minute
	// MaxCoordinatorTTL is the longest coordinator TTL accepted by config validation.
	MaxCoordinatorTTL = 24 * time.Hour
	// DefaultCoordinatorMaxChildren is the safe per-coordinator child-session cap.
	DefaultCoordinatorMaxChildren = 5
	// MaxCoordinatorChildren is the hard MVP cap for coordinator child sessions.
	MaxCoordinatorChildren = 5
	// DefaultCoordinatorMaxActivePerWorkspace preserves one active coordinator per workspace.
	DefaultCoordinatorMaxActivePerWorkspace = 1
)
View Source
const (
	// DirName is the AGH directory name used for both the global home and workspace overlays.
	DirName = ".agh"
	// ConfigName is the standard TOML configuration filename.
	ConfigName = "config.toml"
)
View Source
const (
	// DotEnvStatusMissing reports that no .env file exists at the requested path.
	DotEnvStatusMissing = "missing"
	// DotEnvStatusValid reports that the .env file is structured and needs no repair.
	DotEnvStatusValid = "valid"
	// DotEnvStatusRepairable reports that the .env file can be repaired explicitly.
	DotEnvStatusRepairable = "repairable"
	// DotEnvStatusRepaired reports that the .env file was safely rewritten.
	DotEnvStatusRepaired = "repaired"
	// DotEnvStatusUnsupported reports that AGH found content it will not rewrite.
	DotEnvStatusUnsupported = "unsupported"
)
View Source
const (
	// AgentsDirName is the directory used for persisted agent definitions.
	AgentsDirName = "agents"
	// SkillsDirName is the directory used for persisted user skills.
	SkillsDirName = "skills"
	// MemoryDirName is the directory used for persistent memory files.
	MemoryDirName = "memory"
	// SessionsDirName is the directory used for persisted session state.
	SessionsDirName = "sessions"
	// RestartsDirName is the directory used for persisted daemon restart operations.
	RestartsDirName = "restarts"
	// LogsDirName is the directory used for structured logs.
	LogsDirName = "logs"
	// DatabaseName is the global database filename.
	DatabaseName = "agh.db"
	// DaemonSocketName is the daemon UDS filename.
	DaemonSocketName = "daemon.sock"
	// DaemonLockName is the daemon file-lock name.
	DaemonLockName = "daemon.lock"
	// DaemonInfoName is the daemon metadata filename.
	DaemonInfoName = "daemon.json"
	// LogFileName is the structured daemon log filename.
	LogFileName = "agh.log"
	// NetworkAuditFileName is the append-only network audit filename.
	NetworkAuditFileName = "network.audit"
	// AgentDefinitionFileName is the canonical file name for persisted agent definitions.
	AgentDefinitionFileName = "AGENT.md"
)
View Source
const (
	// MaxTaskOrchestrationRuntime is the largest accepted runtime watchdog budget.
	MaxTaskOrchestrationRuntime = 24 * time.Hour

	TaskCoordinatorModeInherit = "inherit"
	TaskCoordinatorModeGuided  = "guided"
	TaskWorkerModeInherit      = "inherit"
	TaskSandboxModeInherit     = "inherit"
	TaskSandboxModeNone        = "none"
	TaskReviewPolicyNone       = "none"
	TaskReviewPolicyOnSuccess  = "on_success"
	TaskReviewPolicyOnFailure  = "on_failure"
	TaskReviewPolicyAlways     = "always"
	TaskReviewFailureBlockTask = "block_task"
	TaskReviewFailureFailTask  = "fail_task"
)
View Source
const (
	// DefaultToolsMaxResultBytes is the TechSpec default result budget for descriptors without one.
	DefaultToolsMaxResultBytes int64 = 256 << 10
	// MaxToolsMaxResultBytes bounds config-level default result budgets.
	MaxToolsMaxResultBytes int64 = 16 << 20

	// DefaultToolsApprovalTimeoutSeconds is the TechSpec default approval wait.
	DefaultToolsApprovalTimeoutSeconds = 120
	// MinToolsApprovalTimeoutSeconds is the smallest supported approval wait.
	MinToolsApprovalTimeoutSeconds = 1
	// MaxToolsApprovalTimeoutSeconds is the largest supported approval wait.
	MaxToolsApprovalTimeoutSeconds = 600

	// DefaultHostedMCPBindNonceTTLSeconds is the TechSpec default hosted MCP bind window.
	DefaultHostedMCPBindNonceTTLSeconds = 30
	// MinHostedMCPBindNonceTTLSeconds is the smallest supported hosted MCP bind window.
	MinHostedMCPBindNonceTTLSeconds = 1
	// MaxHostedMCPBindNonceTTLSeconds is the largest supported hosted MCP bind window.
	MaxHostedMCPBindNonceTTLSeconds = 300
)
View Source
const (
	// AgentResourceKind is the canonical desired-state resource kind for agent definitions.
	AgentResourceKind resources.ResourceKind = "agent"
)
View Source
const (
	// DefaultMemoryDreamAgentName is the bundled curator used for Memory v2 dreaming.
	DefaultMemoryDreamAgentName = "dreaming-curator"
)
View Source
const (
	// MCPJSONName is the supported JSON sidecar filename for MCP server declarations.
	MCPJSONName = "mcp.json"
)
View Source
const (
	// MCPServerResourceKind is the canonical desired-state resource kind for MCP server records.
	MCPServerResourceKind resources.ResourceKind = "mcp_server"
)
View Source
const (
	// OnboardingAgentName is the managed first-run onboarding agent definition name.
	OnboardingAgentName = "onboarding"
)

Variables

View Source
var (
	// ErrMissingAgentFrontmatter reports a missing YAML frontmatter block in AGENT.md content.
	ErrMissingAgentFrontmatter = errors.New("config: missing YAML frontmatter")
	// ErrUnterminatedAgentFrontmatter reports an unterminated YAML frontmatter block in AGENT.md content.
	ErrUnterminatedAgentFrontmatter = errors.New("config: unterminated YAML frontmatter")
	// ErrBOMAgentFrontmatter reports a UTF-8 BOM before the YAML frontmatter block.
	ErrBOMAgentFrontmatter = errors.New("config: UTF-8 BOM before YAML frontmatter")
	// ErrInvalidAgentFrontmatterKey reports an unsupported frontmatter key shape.
	ErrInvalidAgentFrontmatterKey = errors.New("config: invalid YAML frontmatter key")
)
View Source
var (
	// ErrInvalidAgentDefinition marks validation failures while authoring an AGENT.md file.
	ErrInvalidAgentDefinition = errors.New("config: invalid agent definition")
	// ErrAgentDefinitionExists marks a create request that would overwrite an existing AGENT.md file.
	ErrAgentDefinitionExists = errors.New("config: agent definition already exists")
)
View Source
var (
	// ErrDotEnvUnsupported reports that .env content could not be safely parsed
	// or repaired without risking user-owned intent.
	ErrDotEnvUnsupported = errors.New("config: unsupported .env content")
)
View Source
var ErrProviderUnavailable = errors.New("provider unavailable")

ErrProviderUnavailable reports that a requested provider cannot be resolved from the effective workspace/global config.

View Source
var (
	// ErrUnsupportedTOMLMutation reports a mutation that would require rewriting
	// unrelated TOML structure instead of editing the targeted document fragment.
	ErrUnsupportedTOMLMutation = errors.New("config: unsupported TOML mutation")
)

Functions

func AgentCapabilityCatalogDependencyPaths

func AgentCapabilityCatalogDependencyPaths(agentDir string) ([]string, error)

AgentCapabilityCatalogDependencyPaths returns the filesystem inputs that can affect LoadAgentCapabilities for one agent directory.

func ApplyConfigOverlayFile

func ApplyConfigOverlayFile(path string, dst *Config) error

ApplyConfigOverlayFile deep-merges an optional TOML config file into dst.

func BuiltinProviders

func BuiltinProviders() map[string]ProviderConfig

BuiltinProviders returns a deep copy of the built-in provider registry.

func CanonicalCapabilityDigest

func CanonicalCapabilityDigest(capability CapabilityDef) (string, error)

CanonicalCapabilityDigest computes the runtime-owned digest for one capability document after normalization.

func CanonicalProviderModelName

func CanonicalProviderModelName(providerName string, modelName string) string

CanonicalProviderModelName resolves small built-in provider-scoped model aliases.

func CanonicalProviderName

func CanonicalProviderName(name string) string

CanonicalProviderName resolves known builtin aliases to the stable provider id.

func EnsureBootstrapAgent

func EnsureBootstrapAgent(homePaths HomePaths) (string, bool, error)

EnsureBootstrapAgent creates the managed default agent definition if it does not already exist.

func EnsureHomeLayout

func EnsureHomeLayout(paths HomePaths) error

EnsureHomeLayout creates the directories required by the AGH home layout.

func EnsureOnboardingAgent

func EnsureOnboardingAgent(homePaths HomePaths) (string, bool, error)

EnsureOnboardingAgent creates the managed first-run onboarding agent if it does not already exist. This agent interviews the operator during the web onboarding wizard and provisions channels and agents through its bounded coordination + workspace toolsets.

func HookDeclarationOverlayValues

func HookDeclarationOverlayValues(decl hookspkg.HookDecl) map[string]any

HookDeclarationOverlayValues converts a hook declaration to TOML overlay values.

func HookDeclarations

func HookDeclarations(hooksCfg HooksConfig, agents []AgentDef) ([]hookspkg.HookDecl, error)

HookDeclarations returns normalized config and agent-definition hook declarations for registry consumption.

func IsInternalManagedAgentName

func IsInternalManagedAgentName(name string) bool

IsInternalManagedAgentName reports whether name is reserved for daemon-owned internal flows.

func IsPublicAgentDef

func IsPublicAgentDef(agent AgentDef) bool

IsPublicAgentDef reports whether an agent definition should appear on operator-visible surfaces.

func NewAgentResourceCodec

func NewAgentResourceCodec() (resources.KindCodec[AgentDef], error)

NewAgentResourceCodec builds the canonical agent resource codec.

func NewMCPServerResourceCodec

func NewMCPServerResourceCodec() (resources.KindCodec[MCPServer], error)

NewMCPServerResourceCodec builds the canonical MCP server resource codec.

func NormalizeAgentName

func NormalizeAgentName(name string) string

NormalizeAgentName returns the canonical in-memory agent identity.

func NormalizeToolConfigValue

func NormalizeToolConfigValue(kind ValueKind, value any) (any, error)

NormalizeToolConfigValue coerces a JSON-decoded tool value into a supported TOML value.

func OverlayHookDeclarations

func OverlayHookDeclarations(target WriteTarget) ([]hookspkg.HookDecl, error)

OverlayHookDeclarations returns config-backed hook declarations from one overlay target.

func ParseDottedConfigPath

func ParseDottedConfigPath(raw string) ([]string, error)

ParseDottedConfigPath parses a user-facing dotted config path.

func RedactStringMap

func RedactStringMap(values map[string]string) map[string]string

RedactStringMap returns the same keys with all values replaced by the shared redaction placeholder.

func RedactedConfigMap

func RedactedConfigMap(cfg *Config) map[string]any

RedactedConfigMap converts config to the same redacted map shape used by operator-facing CLI output.

func RedactedValue

func RedactedValue() string

RedactedValue is the placeholder used when a public surface needs to reveal that a secret-bearing value exists without exposing the value itself.

func ResolveAgentName

func ResolveAgentName(name string, defaults DefaultsConfig) (string, error)

ResolveAgentName resolves an explicit session agent name or falls back to config defaults.

func ResolveHomeDir

func ResolveHomeDir() (string, error)

ResolveHomeDir resolves the global AGH home directory, honoring AGH_HOME when present.

func ResolvePath

func ResolvePath(path string) (string, error)

ResolvePath expands `~`-prefixed paths and returns an absolute path.

func ValidateAgentName

func ValidateAgentName(name string) error

ValidateAgentName rejects names that could reshape the canonical agent path.

func ValidatePublicAgentName

func ValidatePublicAgentName(name string) error

ValidatePublicAgentName rejects internal managed names on public authoring surfaces.

func WorkspaceDotEnvFile

func WorkspaceDotEnvFile(workspaceRoot string) string

WorkspaceDotEnvFile returns the .env file path for a resolved workspace root.

Types

type AgentDef

type AgentDef struct {
	Name         string              `json:"name"                    yaml:"name"                    toml:"name"`
	Provider     string              `json:"provider,omitempty"      yaml:"provider"                toml:"provider"`
	Command      string              `json:"command,omitempty"       yaml:"command,omitempty"       toml:"command,omitempty"`
	Model        string              `json:"model,omitempty"         yaml:"model,omitempty"         toml:"model,omitempty"`
	Tools        []string            `json:"tools,omitempty"         yaml:"tools,omitempty"         toml:"tools,omitempty"`
	Toolsets     []string            `json:"toolsets,omitempty"      yaml:"toolsets,omitempty"      toml:"toolsets,omitempty"`
	DenyTools    []string            `json:"deny_tools,omitempty"    yaml:"deny_tools,omitempty"    toml:"deny_tools,omitempty"`
	Permissions  string              `json:"permissions,omitempty"   yaml:"permissions,omitempty"   toml:"permissions,omitempty"`
	Skills       AgentSkillsConfig   `json:"skills,omitzero"         yaml:"skills,omitempty"        toml:"skills,omitempty"`
	CategoryPath []string            `json:"category_path,omitempty" yaml:"category_path,omitempty" toml:"category_path,omitempty"`
	MCPServers   []MCPServer         `json:"mcp_servers,omitempty"   yaml:"mcp_servers,omitempty"   toml:"mcp_servers,omitempty"`
	Hooks        []hookspkg.HookDecl `json:"hooks,omitempty"         yaml:"hooks,omitempty"         toml:"hooks,omitempty"`
	Capabilities *CapabilityCatalog  `json:"capabilities,omitempty"  yaml:"-"                       toml:"-"`
	Prompt       string              `json:"prompt,omitempty"        yaml:"-"`
	SourcePath   string              `json:"-"                       yaml:"-"                       toml:"-"`
}

AgentDef is the parsed representation of an AGENT.md file.

func CloneAgentDef

func CloneAgentDef(agent AgentDef) AgentDef

CloneAgentDef returns a normalized deep copy of an agent definition.

func CreateAgentDefFile

func CreateAgentDefFile(path string, draft AgentDefinitionDraft, overwrite bool) (AgentDef, error)

CreateAgentDefFile renders, validates, and persists one AGENT.md definition.

func DefaultCoordinatorAgentDef

func DefaultCoordinatorAgentDef() AgentDef

DefaultCoordinatorAgentDef returns the bundled coordinator identity used when no workspace or global agent definition has been resolved yet.

func EditAgentDefFile

func EditAgentDefFile(path string, mutate func(*AgentDef) error) (AgentDef, error)

EditAgentDefFile rewrites one AGENT.md frontmatter block while preserving the prompt body.

func LoadAgentDef

func LoadAgentDef(name string, homePaths HomePaths) (AgentDef, error)

LoadAgentDef loads an AGENT.md file from the configured AGH home directory.

func LoadAgentDefFile

func LoadAgentDefFile(path string) (AgentDef, error)

LoadAgentDefFile loads and parses an AGENT.md file from an explicit path.

func LoadWorkspaceAgentDefs

func LoadWorkspaceAgentDefs(rootDir string, additionalDirs []string, homePaths HomePaths) ([]AgentDef, error)

LoadWorkspaceAgentDefs loads workspace-visible agents using root, additional, then global precedence.

func ParseAgentDef

func ParseAgentDef(content []byte) (AgentDef, error)

ParseAgentDef parses a Markdown file with YAML frontmatter into an AgentDef.

func RenderAgentDefinition

func RenderAgentDefinition(draft AgentDefinitionDraft) ([]byte, AgentDef, error)

RenderAgentDefinition renders a draft to AGENT.md bytes and validates by parsing the result.

func (AgentDef) Validate

func (a AgentDef) Validate() error

Validate ensures the parsed agent definition is usable.

type AgentDefinitionDraft

type AgentDefinitionDraft struct {
	Name         string
	Provider     string
	Command      string
	Model        string
	Tools        []string
	Toolsets     []string
	DenyTools    []string
	Permissions  string
	Skills       AgentSkillsConfig
	CategoryPath []string
	Prompt       string
}

AgentDefinitionDraft captures the simple AGENT.md fields supported by authoring surfaces.

type AgentSkillsConfig

type AgentSkillsConfig struct {
	Disabled []string `json:"disabled,omitempty" yaml:"disabled,omitempty" toml:"disabled,omitempty"`
}

AgentSkillsConfig captures agent-local skill policy stored in AGENT.md.

type AgentsConfig

type AgentsConfig struct {
	Soul      SoulConfig      `toml:"soul"`
	Heartbeat HeartbeatConfig `toml:"heartbeat"`
}

AgentsConfig holds authored agent context settings.

func (AgentsConfig) Validate

func (c AgentsConfig) Validate() error

Validate ensures authored agent context settings are internally consistent.

type AutomationConfig

type AutomationConfig struct {
	Enabled           bool                          `toml:"enabled"`
	Timezone          string                        `toml:"timezone,omitempty"`
	MaxConcurrentJobs int                           `toml:"max_concurrent_jobs"`
	DefaultFireLimit  automationpkg.FireLimitConfig `toml:"default_fire_limit"`
	Jobs              []AutomationJob               `toml:"jobs,omitempty"`
	Triggers          []AutomationTrigger           `toml:"triggers,omitempty"`
}

AutomationConfig holds TOML-defined automation defaults, jobs, and triggers.

func (AutomationConfig) Validate

func (c AutomationConfig) Validate() error

Validate ensures the automation config is internally consistent.

type AutomationJob

type AutomationJob struct {
	Scope     automationpkg.Scope           `toml:"scope"`
	Name      string                        `toml:"name"`
	AgentName string                        `toml:"agent"`
	Workspace string                        `toml:"workspace,omitempty"`
	Prompt    string                        `toml:"prompt"`
	Schedule  automationpkg.ScheduleSpec    `toml:"schedule"`
	Task      *automationpkg.JobTaskConfig  `toml:"task,omitempty"`
	Enabled   bool                          `toml:"enabled"`
	Retry     automationpkg.RetryConfig     `toml:"retry,omitempty"`
	FireLimit automationpkg.FireLimitConfig `toml:"fire_limit,omitempty"`
	Source    automationpkg.JobSource       `toml:"-"`
}

AutomationJob holds a config-defined scheduled job before workspace resolution.

func (AutomationJob) Validate

func (j AutomationJob) Validate(path string) error

Validate ensures the config-defined job is internally consistent before runtime resolution.

type AutomationTrigger

type AutomationTrigger struct {
	Scope            automationpkg.Scope           `toml:"scope"`
	Name             string                        `toml:"name"`
	AgentName        string                        `toml:"agent"`
	Workspace        string                        `toml:"workspace,omitempty"`
	Prompt           string                        `toml:"prompt"`
	Event            string                        `toml:"event"`
	Filter           map[string]string             `toml:"filter,omitempty"`
	Enabled          bool                          `toml:"enabled"`
	Retry            automationpkg.RetryConfig     `toml:"retry,omitempty"`
	FireLimit        automationpkg.FireLimitConfig `toml:"fire_limit,omitempty"`
	Source           automationpkg.JobSource       `toml:"-"`
	EndpointSlug     string                        `toml:"endpoint_slug,omitempty"`
	WebhookSecretRef string                        `toml:"webhook_secret_ref,omitempty"`
}

AutomationTrigger holds a config-defined trigger before workspace resolution.

func (AutomationTrigger) Validate

func (t AutomationTrigger) Validate(path string) error

Validate ensures the config-defined trigger is internally consistent before runtime resolution.

type AutonomyConfig

type AutonomyConfig struct {
	Coordinator CoordinatorConfig `toml:"coordinator"`
}

AutonomyConfig controls opt-in autonomy features.

func (AutonomyConfig) Validate

func (c AutonomyConfig) Validate(resolver providerResolver) error

Validate ensures autonomy config is internally consistent.

type CapabilityBrief

type CapabilityBrief struct {
	ID      string `json:"id"      toml:"id"`
	Summary string `json:"summary" toml:"summary"`
}

CapabilityBrief is the compact discovery projection for one capability.

type CapabilityCatalog

type CapabilityCatalog struct {
	Capabilities []CapabilityDef `json:"capabilities" toml:"capabilities"`
}

CapabilityCatalog is the normalized local catalog loaded from one agent directory.

func LoadAgentCapabilities

func LoadAgentCapabilities(agentDir string) (*CapabilityCatalog, error)

LoadAgentCapabilities loads the optional capability catalog for one agent directory. When no supported capability catalog exists, it returns nil without error.

func (*CapabilityCatalog) Clone

Clone returns a deep copy of the catalog.

type CapabilityDef

type CapabilityDef struct {
	ID                string   `json:"id"                     toml:"id"`
	Summary           string   `json:"summary"                toml:"summary"`
	Outcome           string   `json:"outcome"                toml:"outcome"`
	Version           string   `json:"version,omitempty"      toml:"version,omitempty"`
	ContextNeeded     []string `json:"context_needed"         toml:"context_needed"`
	ArtifactsExpected []string `json:"artifacts_expected"     toml:"artifacts_expected"`
	ExecutionOutline  []string `json:"execution_outline"      toml:"execution_outline"`
	Constraints       []string `json:"constraints"            toml:"constraints"`
	Examples          []string `json:"examples"               toml:"examples"`
	Requirements      []string `json:"requirements,omitempty" toml:"requirements,omitempty"`
	Digest            string   `json:"-"                      toml:"-"`
}

CapabilityDef is one normalized, outcome-oriented capability declaration for an agent.

type Config

type Config struct {
	Daemon        DaemonConfig              `toml:"daemon"`
	HTTP          HTTPConfig                `toml:"http"`
	Defaults      DefaultsConfig            `toml:"defaults"`
	Agents        AgentsConfig              `toml:"agents"`
	Limits        LimitsConfig              `toml:"limits"`
	Session       SessionConfig             `toml:"session"`
	Permissions   PermissionsConfig         `toml:"permissions"`
	MCPServers    []MCPServer               `toml:"mcp_servers,omitempty"`
	Providers     map[string]ProviderConfig `toml:"providers"`
	ModelCatalog  ModelCatalogConfig        `toml:"model_catalog"`
	Sandboxes     map[string]SandboxProfile `toml:"sandboxes"`
	Observability ObservabilityConfig       `toml:"observability"`
	Log           LogConfig                 `toml:"log"`
	Memory        MemoryConfig              `toml:"memory"`
	Skills        SkillsConfig              `toml:"skills"`
	Extensions    ExtensionsConfig          `toml:"extensions"`
	Tools         ToolsConfig               `toml:"tools"`
	Automation    AutomationConfig          `toml:"automation"`
	Task          TaskConfig                `toml:"task"`
	Hooks         HooksConfig               `toml:"hooks"`
	Network       NetworkConfig             `toml:"network"`
	Autonomy      AutonomyConfig            `toml:"autonomy"`
}

Config is the fully merged AGH configuration.

func DefaultWithHome

func DefaultWithHome(homePaths HomePaths) Config

DefaultWithHome returns the built-in default configuration for the supplied AGH home.

func DeleteMCPSidecarServer

func DeleteMCPSidecarServer(
	homePaths HomePaths,
	workspaceRoot string,
	target WriteTarget,
	name string,
) (Config, bool, error)

DeleteMCPSidecarServer removes one MCP server definition from the selected sidecar target when present and returns the merged effective config after validation.

func EditConfigOverlay

func EditConfigOverlay(
	homePaths HomePaths,
	workspaceRoot string,
	target WriteTarget,
	mutate func(*OverlayEditor) error,
) (Config, error)

EditConfigOverlay applies one validated mutation to a canonical TOML overlay target and returns the merged effective config after the write.

func Load

func Load(opts ...LoadOption) (Config, error)

Load reads the default config, the optional global config, and the optional workspace overlay. Workspace overlays are loaded only when WithWorkspaceRoot supplies an explicit root.

func LoadForHome

func LoadForHome(homePaths HomePaths, opts ...LoadOption) (Config, error)

LoadForHome reads the default config, the optional global config, and the optional workspace overlay using the supplied AGH home layout instead of the ambient process home.

func LoadGlobalConfig

func LoadGlobalConfig(homePaths HomePaths) (Config, error)

LoadGlobalConfig loads only the user-global AGH config from the resolved home.

func PutMCPSidecarServer

func PutMCPSidecarServer(
	homePaths HomePaths,
	workspaceRoot string,
	target WriteTarget,
	server MCPServer,
) (Config, error)

PutMCPSidecarServer upserts one MCP server definition in the selected sidecar target and returns the merged effective config after validation.

func SaveBootstrapConfig

func SaveBootstrapConfig(homePaths HomePaths, provider string, model string) (Config, error)

SaveBootstrapConfig writes the global bootstrap config managed by `agh install`.

func (*Config) ResolveAgent

func (c *Config) ResolveAgent(agent AgentDef) (ResolvedAgent, error)

ResolveAgent resolves a parsed agent definition against provider config and global defaults.

func (*Config) ResolveCoordinatorConfig

func (c *Config) ResolveCoordinatorConfig(fallback AgentDef) (CoordinatorConfig, error)

ResolveCoordinatorConfig resolves coordinator runtime policy using the precedence config overlay > fallback agent definition > provider defaults.

func (*Config) ResolveProvider

func (c *Config) ResolveProvider(name string) (ProviderConfig, error)

ResolveProvider resolves a provider using the built-in registry and config overrides.

func (*Config) ResolveSandbox

func (c *Config) ResolveSandbox(ref string) (sandbox.Resolved, error)

ResolveSandbox resolves a named sandbox profile into runtime policy.

func (*Config) ResolveSessionAgent

func (c *Config) ResolveSessionAgent(agent AgentDef, providerOverride string) (ResolvedAgent, error)

ResolveSessionAgent resolves a parsed agent definition for one session. When providerOverride is set, the selected provider becomes canonical and provider-owned runtime fields are re-resolved from that provider to avoid mixed runtimes from the original agent definition.

func (*Config) ResolveSessionAgentWithRuntime

func (c *Config) ResolveSessionAgentWithRuntime(
	agent AgentDef,
	providerOverride string,
	modelOverride string,
) (ResolvedAgent, error)

ResolveSessionAgentWithRuntime resolves one session agent with runtime-level provider/model overrides.

func (*Config) Validate

func (c *Config) Validate() error

Validate ensures the loaded configuration is internally consistent.

type CoordinatorConfig

type CoordinatorConfig struct {
	Enabled               bool          `toml:"enabled"`
	AgentName             string        `toml:"agent_name"`
	Provider              string        `toml:"provider,omitempty"`
	Model                 string        `toml:"model,omitempty"`
	DefaultTTL            time.Duration `toml:"default_ttl"`
	MaxChildren           int           `toml:"max_children"`
	MaxActivePerWorkspace int           `toml:"max_active_per_workspace"`
}

CoordinatorConfig defines the resolved coordinator policy.

func DefaultCoordinatorConfig

func DefaultCoordinatorConfig() CoordinatorConfig

DefaultCoordinatorConfig returns the built-in coordinator policy defaults.

func (CoordinatorConfig) Validate

func (c CoordinatorConfig) Validate(path string, resolver providerResolver) error

Validate ensures coordinator policy is safe to consume.

type DaemonConfig

type DaemonConfig struct {
	Socket         string                     `toml:"socket"`
	ReloadTimeouts DaemonReloadTimeoutsConfig `toml:"reload_timeouts"`
}

DaemonConfig controls daemon-local socket and hot-reload settings.

func (DaemonConfig) Validate

func (c DaemonConfig) Validate() error

Validate ensures the daemon config contains a socket path and reload timeouts.

type DaemonReloadTimeoutsConfig

type DaemonReloadTimeoutsConfig struct {
	Providers time.Duration `toml:"providers"`
	MCP       time.Duration `toml:"mcp"`
	Bridges   time.Duration `toml:"bridges"`
}

DaemonReloadTimeoutsConfig bounds subsystem reload attempts during config apply.

func DefaultDaemonReloadTimeoutsConfig

func DefaultDaemonReloadTimeoutsConfig() DaemonReloadTimeoutsConfig

DefaultDaemonReloadTimeoutsConfig returns daemon hot-reload timeout defaults.

func (DaemonReloadTimeoutsConfig) Validate

func (c DaemonReloadTimeoutsConfig) Validate() error

Validate ensures daemon reload timeout values stay within bounded retry budgets.

type DaytonaProfile

type DaytonaProfile struct {
	APIURL      string `toml:"api_url,omitempty"`
	Target      string `toml:"target,omitempty"`
	Image       string `toml:"image,omitempty"`
	Snapshot    string `toml:"snapshot,omitempty"`
	Class       string `toml:"class,omitempty"`
	AutoStop    string `toml:"auto_stop,omitempty"`
	AutoArchive string `toml:"auto_archive,omitempty"`
}

DaytonaProfile defines Daytona-specific execution sandbox settings.

func (DaytonaProfile) Resolve

func (p DaytonaProfile) Resolve() sandbox.DaytonaConfig

Resolve converts Daytona profile inputs into provider startup policy.

type DefaultsConfig

type DefaultsConfig struct {
	Agent    string `toml:"agent"`
	Provider string `toml:"provider,omitempty"`
	Sandbox  string `toml:"sandbox,omitempty"`
}

DefaultsConfig holds global runtime defaults.

func (DefaultsConfig) Validate

func (c DefaultsConfig) Validate() error

Validate ensures the default agent setting is present.

type DiffEntry

type DiffEntry struct {
	Path           string `json:"path"`
	Before         any    `json:"before,omitempty"`
	After          any    `json:"after,omitempty"`
	BeforeRedacted bool   `json:"before_redacted,omitempty"`
	AfterRedacted  bool   `json:"after_redacted,omitempty"`
}

DiffEntry describes one redacted effective config difference.

func DiffConfigEntries

func DiffConfigEntries(before []Entry, after []Entry) []DiffEntry

DiffConfigEntries returns sorted redacted differences between two effective entry sets.

type DotEnvDiagnostic

type DotEnvDiagnostic struct {
	Line    int    `json:"line,omitempty"`
	Key     string `json:"key,omitempty"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

DotEnvDiagnostic describes one .env parse or repair issue without exposing values.

type DotEnvRepairError

type DotEnvRepairError struct {
	Path        string
	Diagnostics []DotEnvDiagnostic
}

DotEnvRepairError carries structured diagnostics for unsupported .env content.

func (*DotEnvRepairError) Error

func (e *DotEnvRepairError) Error() string

Error returns a diagnostic summary without including .env values.

func (*DotEnvRepairError) Is

func (e *DotEnvRepairError) Is(target error) bool

Is matches the unsupported .env sentinel.

type DotEnvRepairReport

type DotEnvRepairReport struct {
	Path        string             `json:"path"`
	Status      string             `json:"status"`
	Repaired    bool               `json:"repaired"`
	Diagnostics []DotEnvDiagnostic `json:"diagnostics,omitempty"`
}

DotEnvRepairReport summarizes .env inspection or repair without including values.

func InspectDotEnvFile

func InspectDotEnvFile(path string) (DotEnvRepairReport, error)

InspectDotEnvFile parses one .env file and reports whether explicit repair is possible.

func RepairDotEnvFile

func RepairDotEnvFile(path string) (DotEnvRepairReport, error)

RepairDotEnvFile safely rewrites one .env file when every change is bounded and structured.

type DreamConfig

type DreamConfig struct {
	Enabled       bool                     `toml:"enabled"`
	Agent         string                   `toml:"agent"`
	MinHours      float64                  `toml:"min_hours"`
	MinSessions   int                      `toml:"min_sessions"`
	Debounce      time.Duration            `toml:"debounce"`
	PromptVersion string                   `toml:"prompt_version"`
	CheckInterval time.Duration            `toml:"check_interval"`
	Gates         MemoryDreamGatesConfig   `toml:"gates"`
	Scoring       MemoryDreamScoringConfig `toml:"scoring"`
}

DreamConfig controls background dream consolidation.

func (DreamConfig) Validate

func (c DreamConfig) Validate() error

Validate ensures the dream configuration is internally consistent.

type Entry

type Entry struct {
	Path     string `json:"path"`
	Value    any    `json:"value"`
	Redacted bool   `json:"redacted"`
}

Entry is one flattened, redacted effective config value.

func EntryByPath

func EntryByPath(entries []Entry, path string) (Entry, bool)

EntryByPath returns one flattened entry.

func FlattenConfigEntries

func FlattenConfigEntries(configMap map[string]any) []Entry

FlattenConfigEntries returns deterministic flattened config entries.

type ExtensionsConfig

type ExtensionsConfig struct {
	Marketplace ExtensionsMarketplaceConfig `toml:"marketplace,omitempty"`
	Resources   ExtensionsResourcesConfig   `toml:"resources,omitempty"`
}

ExtensionsConfig controls extension marketplace discovery and install behavior.

func (ExtensionsConfig) Validate

func (c ExtensionsConfig) Validate() error

Validate ensures the extension marketplace configuration is internally consistent.

type ExtensionsMarketplaceConfig

type ExtensionsMarketplaceConfig struct {
	Registry string `toml:"registry"`
	BaseURL  string `toml:"base_url,omitempty"`
}

ExtensionsMarketplaceConfig controls the external extension registry used by CLI extension commands.

func (ExtensionsMarketplaceConfig) Validate

func (c ExtensionsMarketplaceConfig) Validate() error

Validate ensures the extension marketplace configuration is internally consistent when configured.

type ExtensionsResourceRateLimitConfig

type ExtensionsResourceRateLimitConfig struct {
	Requests int           `toml:"requests"`
	Window   time.Duration `toml:"window"`
	Queue    int           `toml:"queue"`
}

ExtensionsResourceRateLimitConfig controls one resource publication rate-limit bucket.

func (ExtensionsResourceRateLimitConfig) Validate

Validate ensures one configured resource rate-limit bucket is internally consistent.

type ExtensionsResourcesConfig

type ExtensionsResourcesConfig struct {
	AllowedKinds           []resources.ResourceKind          `toml:"allowed_kinds,omitempty"`
	MaxScope               resources.ResourceScopeKind       `toml:"max_scope,omitempty"`
	SnapshotRateLimit      ExtensionsResourceRateLimitConfig `toml:"snapshot_rate_limit,omitempty"`
	OperatorWriteRateLimit ExtensionsResourceRateLimitConfig `toml:"operator_write_rate_limit,omitempty"`
}

ExtensionsResourcesConfig controls resource publication policy for extensions.

func (ExtensionsResourcesConfig) Validate

func (c ExtensionsResourcesConfig) Validate() error

Validate ensures the extension resource policy is internally consistent.

type FileError

type FileError struct {
	Op   string
	Path string
	Err  error
}

FileError preserves the source file for configuration read/decode failures.

func (FileError) Error

func (e FileError) Error() string

func (FileError) Unwrap

func (e FileError) Unwrap() error

type HTTPConfig

type HTTPConfig struct {
	Host string `toml:"host"`
	Port int    `toml:"port"`
}

HTTPConfig controls the HTTP server bind address.

func (HTTPConfig) Validate

func (c HTTPConfig) Validate() error

Validate ensures the HTTP bind settings are valid.

type HeartbeatConfig

type HeartbeatConfig struct {
	Enabled                      bool          `toml:"enabled"`
	MaxBodyBytes                 int64         `toml:"max_body_bytes"`
	ContextProjectionBytes       int64         `toml:"context_projection_bytes"`
	MinInterval                  time.Duration `toml:"min_interval"`
	DefaultInterval              time.Duration `toml:"default_interval"`
	WakeCooldown                 time.Duration `toml:"wake_cooldown"`
	MaxWakesPerCycle             int           `toml:"max_wakes_per_cycle"`
	ActiveSessionOnly            bool          `toml:"active_session_only"`
	AllowActiveHoursPreferences  bool          `toml:"allow_active_hours_preferences"`
	WakeEventRetention           time.Duration `toml:"wake_event_retention"`
	SessionHealthStaleAfter      time.Duration `toml:"session_health_stale_after"`
	SessionHealthHookMinInterval time.Duration `toml:"session_health_hook_min_interval"`
}

HeartbeatConfig controls optional HEARTBEAT.md wake-policy parsing and runtime bounds.

func DefaultHeartbeatConfig

func DefaultHeartbeatConfig() HeartbeatConfig

DefaultHeartbeatConfig returns built-in Agent Heartbeat wake-policy limits.

func (HeartbeatConfig) Validate

func (c HeartbeatConfig) Validate() error

Validate ensures HEARTBEAT.md limits and timing bounds are internally consistent.

type HomePaths

type HomePaths struct {
	HomeDir          string
	ConfigFile       string
	AgentsDir        string
	SkillsDir        string
	MemoryDir        string
	SessionsDir      string
	RestartsDir      string
	LogsDir          string
	LogFile          string
	NetworkAuditFile string
	DatabaseFile     string
	DaemonSocket     string
	DaemonLock       string
	DaemonInfo       string
}

HomePaths captures the filesystem layout for the AGH home directory.

func ResolveHomePaths

func ResolveHomePaths() (HomePaths, error)

ResolveHomePaths resolves the canonical AGH home layout.

func ResolveHomePathsForWorkspace

func ResolveHomePathsForWorkspace(workspaceRoot string) (HomePaths, error)

ResolveHomePathsForWorkspace resolves the canonical AGH home layout while honoring AGH_HOME from the supplied workspace .env when the process env omits it.

func ResolveHomePathsFrom

func ResolveHomePathsFrom(homeDir string) (HomePaths, error)

ResolveHomePathsFrom resolves the canonical AGH home layout from an explicit directory.

type HooksConfig

type HooksConfig struct {
	Declarations []hookspkg.HookDecl `toml:"declarations,omitempty"`
}

HooksConfig holds config-defined hook declarations.

func (HooksConfig) Validate

func (c HooksConfig) Validate() error

Validate ensures the hook declarations are internally consistent.

type LimitsConfig

type LimitsConfig struct {
	MaxConcurrentAgents int `toml:"max_concurrent_agents"`
}

LimitsConfig defines runtime safety bounds.

func (LimitsConfig) Validate

func (c LimitsConfig) Validate() error

Validate ensures the configured limits are positive.

type LoadOption

type LoadOption func(*loadOptions)

LoadOption customizes configuration loading.

func WithWorkspaceRoot

func WithWorkspaceRoot(root string) LoadOption

WithWorkspaceRoot loads the optional workspace overlay from `<root>/.agh/config.toml`. When omitted, Load applies only the built-in defaults and the global AGH home config.

type LogConfig

type LogConfig struct {
	Level           string `toml:"level"`
	MaxSizeMB       int    `toml:"max_size_mb"`
	MaxBackups      int    `toml:"max_backups"`
	MaxAgeDays      int    `toml:"max_age_days"`
	CompressBackups bool   `toml:"compress_backups"`
}

LogConfig controls structured logging.

func (LogConfig) Validate

func (c LogConfig) Validate() error

Validate ensures the log level is supported.

type MCPAuthConfig

type MCPAuthConfig struct {
	Type             MCPAuthType `json:"type,omitempty"              yaml:"type,omitempty"              toml:"type,omitempty"`
	IssuerURL        string      `json:"issuer_url,omitempty"        yaml:"issuer_url,omitempty"        toml:"issuer_url,omitempty"`
	MetadataURL      string      `json:"metadata_url,omitempty"      yaml:"metadata_url,omitempty"      toml:"metadata_url,omitempty"`
	AuthorizationURL string      `json:"authorization_url,omitempty" yaml:"authorization_url,omitempty" toml:"authorization_url,omitempty"`
	TokenURL         string      `json:"token_url,omitempty"         yaml:"token_url,omitempty"         toml:"token_url,omitempty"`
	RevocationURL    string      `json:"revocation_url,omitempty"    yaml:"revocation_url,omitempty"    toml:"revocation_url,omitempty"`
	ClientID         string      `json:"client_id,omitempty"         yaml:"client_id,omitempty"         toml:"client_id,omitempty"`
	ClientSecretRef  string      `json:"client_secret_ref,omitempty" yaml:"client_secret_ref,omitempty" toml:"client_secret_ref,omitempty"`
	Scopes           []string    `json:"scopes,omitempty"            yaml:"scopes,omitempty"            toml:"scopes,omitempty"`
}

MCPAuthConfig describes remote MCP OAuth configuration. It stores endpoint metadata and secret refs only; token material is persisted through the vault-backed auth token store.

func (MCPAuthConfig) Enabled

func (a MCPAuthConfig) Enabled() bool

Enabled reports whether auth is configured.

func (MCPAuthConfig) IsZero

func (a MCPAuthConfig) IsZero() bool

IsZero reports whether the auth config is empty.

func (MCPAuthConfig) Validate

func (a MCPAuthConfig) Validate(path string) error

Validate ensures remote MCP OAuth configuration has enough metadata to run the authorization-code flow without placing token material in config files.

type MCPAuthType

type MCPAuthType string

MCPAuthType identifies the remote MCP authentication mechanism.

const (
	// MCPAuthTypeOAuth2PKCE uses OAuth 2.1 authorization code with PKCE.
	MCPAuthTypeOAuth2PKCE MCPAuthType = "oauth2_pkce"
)

type MCPServer

type MCPServer struct {
	Name      string             `json:"name"                 yaml:"name"                 toml:"name"`
	Transport MCPServerTransport `json:"transport,omitempty"  yaml:"transport,omitempty"  toml:"transport,omitempty"`
	Command   string             `json:"command,omitempty"    yaml:"command,omitempty"    toml:"command,omitempty"`
	Args      []string           `json:"args,omitempty"       yaml:"args,omitempty"       toml:"args,omitempty"`
	Env       map[string]string  `json:"env,omitempty"        yaml:"env,omitempty"        toml:"env,omitempty"`
	SecretEnv map[string]string  `json:"secret_env,omitempty" yaml:"secret_env,omitempty" toml:"secret_env,omitempty"`
	URL       string             `json:"url,omitempty"        yaml:"url,omitempty"        toml:"url,omitempty"`
	Auth      MCPAuthConfig      `json:"auth"                 yaml:"auth,omitempty"       toml:"auth,omitempty"`
}

MCPServer describes an MCP server passed through to the agent runtime.

func LoadMCPServersJSONFile

func LoadMCPServersJSONFile(path string) ([]MCPServer, error)

LoadMCPServersJSONFile parses an optional `mcp.json` file from disk. Missing files are treated as absent rather than as errors.

func MergeMCPServers

func MergeMCPServers(base []MCPServer, overlay []MCPServer) []MCPServer

MergeMCPServers merges provider-level and agent-level MCP servers by name.

func OverrideMCPServers

func OverrideMCPServers(base []MCPServer, overlay []MCPServer) []MCPServer

OverrideMCPServers overlays MCP servers by name, replacing the full server object on collision instead of field-merging it.

func ParseMCPServersJSON

func ParseMCPServersJSON(content []byte, source string) ([]MCPServer, error)

ParseMCPServersJSON parses an MCP JSON document into canonical MCP server values. The document may use either `mcpServers` or `mcp_servers` as the top-level key.

func RedactedMCPServer

func RedactedMCPServer(server MCPServer) MCPServer

RedactedMCPServer returns a server copy suitable for public API and CLI rendering. It preserves non-secret endpoint metadata and redacts env values.

func (MCPServer) EffectiveTransport

func (s MCPServer) EffectiveTransport() MCPServerTransport

EffectiveTransport returns the explicit transport or the compatibility default. Local command servers remain stdio; servers with a URL default to streamable HTTP.

func (MCPServer) Validate

func (s MCPServer) Validate(path string) error

Validate ensures the MCP server entry is usable.

type MCPServerTransport

type MCPServerTransport string

MCPServerTransport identifies how AGH reaches an MCP server.

const (
	// MCPServerTransportStdio launches a local subprocess and talks MCP over stdio.
	MCPServerTransportStdio MCPServerTransport = "stdio"
	// MCPServerTransportHTTP talks to a remote streamable HTTP MCP endpoint.
	MCPServerTransportHTTP MCPServerTransport = "http"
	// MCPServerTransportSSE talks to a remote SSE MCP endpoint.
	MCPServerTransportSSE MCPServerTransport = "sse"
)

func (MCPServerTransport) Validate

func (t MCPServerTransport) Validate(path string) error

Validate reports whether the transport is supported.

type MarketplaceConfig

type MarketplaceConfig struct {
	Registry string `toml:"registry"`
	BaseURL  string `toml:"base_url,omitempty"`
}

MarketplaceConfig controls the external skill registry used by CLI skill commands.

func (MarketplaceConfig) Validate

func (c MarketplaceConfig) Validate() error

Validate ensures the marketplace configuration is internally consistent when configured.

type MemoryConfig

type MemoryConfig struct {
	Enabled    bool                   `toml:"enabled"`
	GlobalDir  string                 `toml:"global_dir,omitempty"`
	Controller MemoryControllerConfig `toml:"controller"`
	Recall     MemoryRecallConfig     `toml:"recall"`
	Decisions  MemoryDecisionsConfig  `toml:"decisions"`
	Extractor  MemoryExtractorConfig  `toml:"extractor"`
	Dream      DreamConfig            `toml:"dream"`
	Session    MemorySessionConfig    `toml:"session"`
	Daily      MemoryDailyConfig      `toml:"daily"`
	File       MemoryFileConfig       `toml:"file"`
	Provider   MemoryProviderConfig   `toml:"provider"`
	Workspace  MemoryWorkspaceConfig  `toml:"workspace"`
}

MemoryConfig controls persistent memory features.

func DefaultMemoryConfig

func DefaultMemoryConfig(homePaths HomePaths) MemoryConfig

DefaultMemoryConfig returns the approved Memory v2 Slice 1 defaults.

func (*MemoryConfig) Validate

func (c *MemoryConfig) Validate() error

Validate ensures the memory configuration is internally consistent.

type MemoryControllerConfig

type MemoryControllerConfig struct {
	Mode            string                       `toml:"mode"`
	MaxLatency      time.Duration                `toml:"max_latency"`
	DefaultOpOnFail string                       `toml:"default_op_on_fail"`
	LLM             MemoryControllerLLMConfig    `toml:"llm"`
	Policy          MemoryControllerPolicyConfig `toml:"policy"`
}

MemoryControllerConfig controls the durable write controller.

func (*MemoryControllerConfig) Validate

func (c *MemoryControllerConfig) Validate() error

Validate ensures the controller configuration is internally consistent.

type MemoryControllerLLMConfig

type MemoryControllerLLMConfig struct {
	Enabled       bool          `toml:"enabled"`
	Model         string        `toml:"model"`
	TopK          int           `toml:"top_k"`
	PromptVersion string        `toml:"prompt_version"`
	Timeout       time.Duration `toml:"timeout"`
	MaxTokensOut  int           `toml:"max_tokens_out"`
}

MemoryControllerLLMConfig controls the controller LLM tie-breaker.

func (MemoryControllerLLMConfig) Validate

func (c MemoryControllerLLMConfig) Validate() error

Validate ensures the controller LLM configuration is internally consistent.

type MemoryControllerPolicyConfig

type MemoryControllerPolicyConfig struct {
	MaxContentChars int      `toml:"max_content_chars"`
	MaxWritesPerMin int      `toml:"max_writes_per_min"`
	AllowOrigins    []string `toml:"allow_origins"`
}

MemoryControllerPolicyConfig controls controller safety limits.

func (*MemoryControllerPolicyConfig) Validate

func (c *MemoryControllerPolicyConfig) Validate() error

Validate ensures the controller policy configuration is internally consistent.

type MemoryDailyConfig

type MemoryDailyConfig struct {
	MaxBytes        int64  `toml:"max_bytes"`
	MaxLines        int    `toml:"max_lines"`
	RotateFormat    string `toml:"rotate_format"`
	DreamingWindow  int    `toml:"dreaming_window"`
	ColdArchiveDays int    `toml:"cold_archive_days"`
	HardDeleteDays  int    `toml:"hard_delete_days"`
	MaxArchiveBytes int64  `toml:"max_archive_bytes"`
	SweepHour       int    `toml:"sweep_hour"`
	ArchivePath     string `toml:"archive_path"`
}

MemoryDailyConfig controls daily note retention and rotation.

func (MemoryDailyConfig) Validate

func (c MemoryDailyConfig) Validate() error

Validate ensures daily note settings are usable.

type MemoryDecisionsConfig

type MemoryDecisionsConfig struct {
	PruneAfterAppliedDays int   `toml:"prune_after_applied_days"`
	KeepAuditSummary      bool  `toml:"keep_audit_summary"`
	MaxPostContentBytes   int64 `toml:"max_post_content_bytes"`
}

MemoryDecisionsConfig controls Decision WAL retention and content caps.

func (MemoryDecisionsConfig) Validate

func (c MemoryDecisionsConfig) Validate() error

Validate ensures Decision WAL retention settings are usable.

type MemoryDreamGatesConfig

type MemoryDreamGatesConfig struct {
	MinUnpromoted  int     `toml:"min_unpromoted"`
	MinRecallCount int     `toml:"min_recall_count"`
	MinScore       float64 `toml:"min_score"`
}

MemoryDreamGatesConfig controls promotion gates for dreaming candidates.

func (MemoryDreamGatesConfig) Validate

func (c MemoryDreamGatesConfig) Validate() error

Validate ensures dreaming promotion gates are usable.

type MemoryDreamScoringConfig

type MemoryDreamScoringConfig struct {
	RecencyHalfLifeDays int                             `toml:"recency_half_life_days"`
	Weights             MemoryDreamScoringWeightsConfig `toml:"weights"`
}

MemoryDreamScoringConfig controls dreaming candidate scoring.

func (MemoryDreamScoringConfig) Validate

func (c MemoryDreamScoringConfig) Validate() error

Validate ensures dreaming scoring settings are usable.

type MemoryDreamScoringWeightsConfig

type MemoryDreamScoringWeightsConfig struct {
	Frequency float64 `toml:"frequency"`
	Relevance float64 `toml:"relevance"`
	Recency   float64 `toml:"recency"`
	Freshness float64 `toml:"freshness"`
}

MemoryDreamScoringWeightsConfig controls dreaming score factors.

func (MemoryDreamScoringWeightsConfig) Validate

Validate ensures dreaming scoring weights are usable.

type MemoryExtractorConfig

type MemoryExtractorConfig struct {
	Enabled          bool                       `toml:"enabled"`
	Mode             string                     `toml:"mode"`
	ThrottleTurns    int                        `toml:"throttle_turns"`
	Deadline         time.Duration              `toml:"deadline"`
	SandboxInboxOnly bool                       `toml:"sandbox_inbox_only"`
	InboxPath        string                     `toml:"inbox_path"`
	DLQPath          string                     `toml:"dlq_path"`
	Model            string                     `toml:"model"`
	Queue            MemoryExtractorQueueConfig `toml:"queue"`
}

MemoryExtractorConfig controls the post-message extractor queue.

func (*MemoryExtractorConfig) Validate

func (c *MemoryExtractorConfig) Validate() error

Validate ensures extractor settings are internally consistent.

type MemoryExtractorQueueConfig

type MemoryExtractorQueueConfig struct {
	Capacity    int `toml:"capacity"`
	CoalesceMax int `toml:"coalesce_max"`
}

MemoryExtractorQueueConfig controls bounded extractor work.

func (MemoryExtractorQueueConfig) Validate

func (c MemoryExtractorQueueConfig) Validate() error

Validate ensures extractor queue settings are usable.

type MemoryFileConfig

type MemoryFileConfig struct {
	MaxLines int   `toml:"max_lines"`
	MaxBytes int64 `toml:"max_bytes"`
}

MemoryFileConfig controls individual memory file limits.

func (MemoryFileConfig) Validate

func (c MemoryFileConfig) Validate() error

Validate ensures memory file limits are usable.

type MemoryProviderConfig

type MemoryProviderConfig struct {
	Name             string        `toml:"name"`
	Timeout          time.Duration `toml:"timeout"`
	FailureThreshold int           `toml:"failure_threshold"`
	Cooldown         time.Duration `toml:"cooldown"`
}

MemoryProviderConfig controls the active memory provider registry entry.

func (MemoryProviderConfig) Validate

func (c MemoryProviderConfig) Validate() error

Validate ensures provider settings are usable.

type MemoryRecallConfig

type MemoryRecallConfig struct {
	TopK                   int                         `toml:"top_k"`
	RawCandidates          int                         `toml:"raw_candidates"`
	Fusion                 string                      `toml:"fusion"`
	IncludeAlreadySurfaced bool                        `toml:"include_already_surfaced"`
	IncludeSystem          bool                        `toml:"include_system"`
	Weights                MemoryRecallWeightsConfig   `toml:"weights"`
	Freshness              MemoryRecallFreshnessConfig `toml:"freshness"`
	Signals                MemoryRecallSignalsConfig   `toml:"signals"`
}

MemoryRecallConfig controls deterministic recall.

func (*MemoryRecallConfig) Validate

func (c *MemoryRecallConfig) Validate() error

Validate ensures the recall configuration is internally consistent.

type MemoryRecallFreshnessConfig

type MemoryRecallFreshnessConfig struct {
	BannerAfterDays int `toml:"banner_after_days"`
}

MemoryRecallFreshnessConfig controls recall freshness banners.

type MemoryRecallSignalsConfig

type MemoryRecallSignalsConfig struct {
	QueueCapacity  int  `toml:"queue_capacity"`
	WorkerRetryMax int  `toml:"worker_retry_max"`
	MetricsEnabled bool `toml:"metrics_enabled"`
}

MemoryRecallSignalsConfig controls recall signal recording.

func (MemoryRecallSignalsConfig) Validate

func (c MemoryRecallSignalsConfig) Validate() error

Validate ensures recall signal settings are usable.

type MemoryRecallWeightsConfig

type MemoryRecallWeightsConfig struct {
	BM25Unicode  float64 `toml:"bm25_unicode"`
	BM25Trigram  float64 `toml:"bm25_trigram"`
	Recency      float64 `toml:"recency"`
	RecallSignal float64 `toml:"recall_signal"`
}

MemoryRecallWeightsConfig controls deterministic recall scoring weights.

func (MemoryRecallWeightsConfig) Validate

func (c MemoryRecallWeightsConfig) Validate() error

Validate ensures recall weights are usable.

type MemorySessionConfig

type MemorySessionConfig struct {
	LedgerFormat     string        `toml:"ledger_format"`
	LedgerRoot       string        `toml:"ledger_root"`
	EventsPurgeGrace time.Duration `toml:"events_purge_grace"`
	ColdArchiveDays  int           `toml:"cold_archive_days"`
	HardDeleteDays   int           `toml:"hard_delete_days"`
	MaxArchiveBytes  int64         `toml:"max_archive_bytes"`
	UnboundPartition string        `toml:"unbound_partition"`
}

MemorySessionConfig controls forensic session ledger retention.

func (*MemorySessionConfig) Validate

func (c *MemorySessionConfig) Validate() error

Validate ensures session ledger settings are usable.

type MemoryWorkspaceConfig

type MemoryWorkspaceConfig struct {
	TOMLPath   string `toml:"toml_path"`
	AutoCreate bool   `toml:"auto_create"`
}

MemoryWorkspaceConfig controls workspace memory file lifecycle.

func (MemoryWorkspaceConfig) Validate

func (c MemoryWorkspaceConfig) Validate() error

Validate ensures workspace memory settings are usable.

type ModelCatalogConfig

type ModelCatalogConfig struct {
	Sources ModelCatalogSourcesConfig `toml:"sources,omitempty"`
}

ModelCatalogConfig controls daemon-owned model catalog sources.

func DefaultModelCatalogConfig

func DefaultModelCatalogConfig() ModelCatalogConfig

DefaultModelCatalogConfig returns the default model catalog source config.

func (ModelCatalogConfig) Validate

func (c ModelCatalogConfig) Validate() error

Validate reports whether model catalog config is usable.

type ModelCatalogSourcesConfig

type ModelCatalogSourcesConfig struct {
	ModelsDev ModelsDevSourceConfig `toml:"models_dev,omitempty"`
}

ModelCatalogSourcesConfig groups built-in model catalog sources.

type ModelsDevSourceConfig

type ModelsDevSourceConfig struct {
	Enabled  *bool  `toml:"enabled,omitempty"`
	Endpoint string `toml:"endpoint,omitempty"`
	TTL      string `toml:"ttl,omitempty"`
	Timeout  string `toml:"timeout,omitempty"`
}

ModelsDevSourceConfig controls the models.dev catalog source.

func (ModelsDevSourceConfig) EffectiveEnabled

func (c ModelsDevSourceConfig) EffectiveEnabled() bool

EffectiveEnabled reports whether the models.dev source should run.

func (ModelsDevSourceConfig) EffectiveEndpoint

func (c ModelsDevSourceConfig) EffectiveEndpoint() string

EffectiveEndpoint returns the configured endpoint or the default models.dev endpoint.

func (ModelsDevSourceConfig) EffectiveTTL

func (c ModelsDevSourceConfig) EffectiveTTL() string

EffectiveTTL returns the configured TTL or the default models.dev TTL.

func (ModelsDevSourceConfig) EffectiveTimeout

func (c ModelsDevSourceConfig) EffectiveTimeout() string

EffectiveTimeout returns the configured timeout or the default models.dev timeout.

func (ModelsDevSourceConfig) Validate

func (c ModelsDevSourceConfig) Validate(path string) error

Validate reports whether the models.dev source config is usable.

type NetworkConfig

type NetworkConfig struct {
	Enabled        bool   `toml:"enabled"`
	DefaultChannel string `toml:"default_channel"`
	Port           int    `toml:"port"`
	MaxPayload     int    `toml:"max_payload"`
	GreetInterval  int    `toml:"greet_interval"`
	MaxReplayAge   int    `toml:"max_replay_age"`
	MaxQueueDepth  int    `toml:"max_queue_depth"`
}

NetworkConfig controls the embedded AGH network runtime.

func (NetworkConfig) GreetIntervalDuration

func (c NetworkConfig) GreetIntervalDuration() time.Duration

GreetIntervalDuration returns the configured heartbeat interval as a duration.

func (NetworkConfig) MaxReplayAgeDuration

func (c NetworkConfig) MaxReplayAgeDuration() time.Duration

MaxReplayAgeDuration returns the configured replay age window as a duration.

func (NetworkConfig) Validate

func (c NetworkConfig) Validate() error

Validate ensures the network configuration is internally consistent.

type NetworkProfile

type NetworkProfile struct {
	AllowPublicIngress bool     `toml:"allow_public_ingress,omitempty"`
	AllowOutbound      bool     `toml:"allow_outbound,omitempty"`
	AllowList          []string `toml:"allow_list,omitempty"`
	DenyList           []string `toml:"deny_list,omitempty"`
	Required           bool     `toml:"required,omitempty"`
}

NetworkProfile defines provider-neutral network policy intent.

type ObservabilityConfig

type ObservabilityConfig struct {
	Enabled           bool                          `toml:"enabled"`
	RetentionDays     int                           `toml:"retention_days"`
	MaxGlobalBytes    int64                         `toml:"max_global_bytes"`
	AgentProbeTimeout time.Duration                 `toml:"agent_probe_timeout"`
	Transcripts       ObservabilityTranscriptConfig `toml:"transcripts"`
}

ObservabilityConfig controls global event retention settings.

func (ObservabilityConfig) AgentProbeTimeoutOrDefault

func (c ObservabilityConfig) AgentProbeTimeoutOrDefault() time.Duration

AgentProbeTimeoutOrDefault returns the configured agent probe timeout or the default.

func (ObservabilityConfig) Validate

func (c ObservabilityConfig) Validate() error

Validate ensures observability settings are sensible.

type ObservabilityTranscriptConfig

type ObservabilityTranscriptConfig struct {
	Enabled            bool  `toml:"enabled"`
	SegmentBytes       int   `toml:"segment_bytes"`
	MaxBytesPerSession int64 `toml:"max_bytes_per_session"`
}

ObservabilityTranscriptConfig configures transcript capture and retention.

func (ObservabilityTranscriptConfig) Validate

func (c ObservabilityTranscriptConfig) Validate() error

Validate ensures transcript retention settings are sensible.

type OverlayEditor

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

OverlayEditor applies safe, comment-preserving mutations to one TOML overlay document.

func (*OverlayEditor) Bytes

func (e *OverlayEditor) Bytes() ([]byte, error)

func (*OverlayEditor) Delete

func (e *OverlayEditor) Delete(path []string) error

Delete removes one TOML key path when present.

func (*OverlayEditor) DeleteArrayTableItem

func (e *OverlayEditor) DeleteArrayTableItem(path []string, nameField string, name string) (bool, error)

DeleteArrayTableItem removes one named entry from an array-of-tables.

func (*OverlayEditor) HasPath

func (e *OverlayEditor) HasPath(path []string) bool

HasPath reports whether the current document already contains the given path.

func (*OverlayEditor) SetTable

func (e *OverlayEditor) SetTable(path []string, values map[string]any) error

SetTable replaces or creates a TOML table at the provided path.

func (*OverlayEditor) SetValue

func (e *OverlayEditor) SetValue(path []string, value any) error

SetValue updates or creates one scalar or array value at the provided path.

func (*OverlayEditor) UpsertArrayTableItem

func (e *OverlayEditor) UpsertArrayTableItem(
	path []string,
	nameField string,
	name string,
	values map[string]any,
) error

UpsertArrayTableItem replaces or appends one named entry in an array-of-tables.

type PathDenial

type PathDenial string

PathDenial is the config package's path-policy decision.

const (
	ConfigPathAllowed         PathDenial = ""
	ConfigPathForbidden       PathDenial = "path_forbidden"
	ConfigPathSecretForbidden PathDenial = "secret_path_forbidden"
	ConfigPathTrustForbidden  PathDenial = "trust_root_forbidden"
)

type PathPolicy

type PathPolicy struct {
	Segments []string
	Kind     ValueKind
	Redacted bool
	Denial   PathDenial
}

PathPolicy captures the deterministic decision for an agent-facing config path.

func ClassifyToolConfigPath

func ClassifyToolConfigPath(path []string) (PathPolicy, error)

ClassifyToolConfigPath applies the agent-facing mutable config policy.

type PermissionMode

type PermissionMode string

PermissionMode is the static permission policy applied by the daemon.

const (
	// DefaultAgentName is the bootstrap agent name used across the system.
	DefaultAgentName                          = "general"
	PermissionModeDenyAll      PermissionMode = "deny-all"
	PermissionModeApproveReads PermissionMode = "approve-reads"
	PermissionModeApproveAll   PermissionMode = "approve-all"
	// DefaultObservabilityAgentProbeTimeout bounds daemon health probes for configured agents.
	DefaultObservabilityAgentProbeTimeout = 2 * time.Second
)

func (PermissionMode) Validate

func (m PermissionMode) Validate(path string) error

Validate ensures the permission mode is supported.

type PermissionsConfig

type PermissionsConfig struct {
	Mode PermissionMode `toml:"mode"`
}

PermissionsConfig defines the global default permission policy.

func (PermissionsConfig) Validate

func (c PermissionsConfig) Validate() error

Validate ensures the permission mode is supported.

type ProviderAuthMode

type ProviderAuthMode string

ProviderAuthMode identifies who owns launch-time provider authentication.

const (
	// ProviderAuthModeNativeCLI lets the provider CLI use its own login/session state.
	ProviderAuthModeNativeCLI ProviderAuthMode = "native_cli"
	// ProviderAuthModeBoundSecret injects explicitly configured credential slots at launch.
	ProviderAuthModeBoundSecret ProviderAuthMode = "bound_secret"
	// ProviderAuthModeNone launches the provider without AGH-managed credentials.
	ProviderAuthModeNone ProviderAuthMode = "none"
)

func (ProviderAuthMode) Validate

func (m ProviderAuthMode) Validate(path string) error

Validate reports whether the provider auth mode is supported.

type ProviderConfig

type ProviderConfig struct {
	Command         string                   `toml:"command"`
	DisplayName     string                   `toml:"display_name,omitempty"`
	Models          ProviderModelsConfig     `toml:"models,omitempty"`
	Harness         ProviderHarness          `toml:"harness,omitempty"`
	RuntimeProvider string                   `toml:"runtime_provider,omitempty"`
	Transport       string                   `toml:"transport,omitempty"`
	BaseURL         string                   `toml:"base_url,omitempty"`
	AuthMode        ProviderAuthMode         `toml:"auth_mode,omitempty"`
	EnvPolicy       ProviderEnvPolicy        `toml:"env_policy,omitempty"`
	HomePolicy      ProviderHomePolicy       `toml:"home_policy,omitempty"`
	NoneSecurity    ProviderNoneSecurity     `toml:"none_security,omitempty"`
	AuthStatusCmd   string                   `toml:"auth_status_command,omitempty"`
	AuthLoginCmd    string                   `toml:"auth_login_command,omitempty"`
	SessionMCP      *bool                    `toml:"session_mcp,omitempty"`
	CredentialSlots []ProviderCredentialSlot `toml:"credential_slots,omitempty"`
	MCPServers      []MCPServer              `toml:"mcp_servers,omitempty"`
}

ProviderConfig describes how to launch a provider in ACP mode.

func (ProviderConfig) EffectiveAuthMode

func (p ProviderConfig) EffectiveAuthMode() ProviderAuthMode

EffectiveAuthMode returns the configured auth owner or the slot-derived default.

func (ProviderConfig) EffectiveCredentialSlots

func (p ProviderConfig) EffectiveCredentialSlots() []ProviderCredentialSlot

EffectiveCredentialSlots returns explicit launch credential slots.

func (ProviderConfig) EffectiveEnvPolicy

func (p ProviderConfig) EffectiveEnvPolicy() ProviderEnvPolicy

EffectiveEnvPolicy returns the configured provider environment inheritance policy.

func (ProviderConfig) EffectiveHarness

func (p ProviderConfig) EffectiveHarness() ProviderHarness

EffectiveHarness returns the configured provider harness or the command-backed default.

func (ProviderConfig) EffectiveHomePolicy

func (p ProviderConfig) EffectiveHomePolicy() ProviderHomePolicy

EffectiveHomePolicy returns the configured provider home inheritance policy.

func (ProviderConfig) EffectiveNoneSecurity

func (p ProviderConfig) EffectiveNoneSecurity() ProviderNoneSecurity

EffectiveNoneSecurity returns the auth_mode=none safety rationale.

func (ProviderConfig) RequiresRuntimeModel

func (p ProviderConfig) RequiresRuntimeModel() bool

RequiresRuntimeModel reports whether AGH must provide a model to start this provider.

func (ProviderConfig) RuntimeProviderName

func (p ProviderConfig) RuntimeProviderName(providerName string) string

RuntimeProviderName returns the downstream runtime provider id for harnesses that need one.

func (ProviderConfig) SessionMCPEnabled

func (p ProviderConfig) SessionMCPEnabled() bool

SessionMCPEnabled reports whether AGH should pass per-session MCP servers to the provider.

type ProviderCredentialSlot

type ProviderCredentialSlot struct {
	Name      string `toml:"name"`
	TargetEnv string `toml:"target_env"`
	SecretRef string `toml:"secret_ref"`
	Kind      string `toml:"kind,omitempty"`
	Required  bool   `toml:"required"`
}

ProviderCredentialSlot describes one launch-time secret binding needed by a provider.

func (ProviderCredentialSlot) Validate

func (s ProviderCredentialSlot) Validate(path string) error

Validate reports whether the provider credential slot can be resolved at launch.

type ProviderEnvPolicy

type ProviderEnvPolicy string

ProviderEnvPolicy identifies which daemon environment is inherited by a provider process.

const (
	// ProviderEnvPolicyFiltered removes secret-shaped daemon variables but keeps operator context.
	ProviderEnvPolicyFiltered ProviderEnvPolicy = "filtered"
	// ProviderEnvPolicyIsolated keeps only a fixed operational allowlist.
	ProviderEnvPolicyIsolated ProviderEnvPolicy = "isolated"
)

func (ProviderEnvPolicy) Validate

func (p ProviderEnvPolicy) Validate(path string) error

Validate reports whether the provider env policy is supported.

type ProviderHarness

type ProviderHarness string

ProviderHarness identifies the runtime strategy used to launch a provider.

const (
	// ProviderHarnessACP launches the configured command directly as an ACP runtime.
	ProviderHarnessACP ProviderHarness = "acp"
	// ProviderHarnessPiACP launches pi through the pi-acp adapter and materializes provider settings.
	ProviderHarnessPiACP ProviderHarness = "pi_acp"
)

func (ProviderHarness) Validate

func (h ProviderHarness) Validate(path string) error

Validate reports whether the harness is supported.

type ProviderHomePolicy

type ProviderHomePolicy string

ProviderHomePolicy identifies whether provider CLI state comes from the operator home or an isolated home.

const (
	// ProviderHomePolicyOperator lets native CLIs read their existing operator login state.
	ProviderHomePolicyOperator ProviderHomePolicy = "operator"
	// ProviderHomePolicyIsolated points native CLIs at an AGH-owned provider home.
	ProviderHomePolicyIsolated ProviderHomePolicy = "isolated"
)

func (ProviderHomePolicy) Validate

func (p ProviderHomePolicy) Validate(path string) error

Validate reports whether the provider home policy is supported.

type ProviderModelConfig

type ProviderModelConfig struct {
	ID                     string   `toml:"id"`
	DisplayName            string   `toml:"display_name,omitempty"`
	ContextWindow          *int64   `toml:"context_window,omitempty"`
	MaxInputTokens         *int64   `toml:"max_input_tokens,omitempty"`
	MaxOutputTokens        *int64   `toml:"max_output_tokens,omitempty"`
	SupportsTools          *bool    `toml:"supports_tools,omitempty"`
	SupportsReasoning      *bool    `toml:"supports_reasoning,omitempty"`
	ReasoningEfforts       []string `toml:"reasoning_efforts,omitempty"`
	DefaultReasoningEffort string   `toml:"default_reasoning_effort,omitempty"`
	CostInputPerMillion    *float64 `toml:"cost_input_per_million,omitempty"`
	CostOutputPerMillion   *float64 `toml:"cost_output_per_million,omitempty"`
}

ProviderModelConfig describes one curated provider model entry.

type ProviderModelsConfig

type ProviderModelsConfig struct {
	Default   string                        `toml:"default,omitempty"`
	Curated   []ProviderModelConfig         `toml:"curated,omitempty"`
	Discovery ProviderModelsDiscoveryConfig `toml:"discovery,omitempty"`
}

ProviderModelsConfig describes provider-scoped model defaults and metadata.

func (ProviderModelsConfig) Validate

func (m ProviderModelsConfig) Validate(path string) error

Validate reports whether the provider model block is usable.

type ProviderModelsDiscoveryConfig

type ProviderModelsDiscoveryConfig struct {
	Enabled  *bool  `toml:"enabled,omitempty"`
	Command  string `toml:"command,omitempty"`
	Endpoint string `toml:"endpoint,omitempty"`
	Timeout  string `toml:"timeout,omitempty"`
}

ProviderModelsDiscoveryConfig describes optional side-effect-free model discovery.

func (ProviderModelsDiscoveryConfig) Validate

func (d ProviderModelsDiscoveryConfig) Validate(path string) error

Validate reports whether the discovery source config is usable.

type ProviderNoneSecurity

type ProviderNoneSecurity string

ProviderNoneSecurity identifies why auth_mode=none is safe for a provider.

const (
	// ProviderNoneSecurityLocalTransport limits unauthenticated providers to local transport.
	ProviderNoneSecurityLocalTransport ProviderNoneSecurity = "local_transport"
	// ProviderNoneSecurityExternalIdentity delegates authentication to the provider transport.
	ProviderNoneSecurityExternalIdentity ProviderNoneSecurity = "external_identity"
	// ProviderNoneSecurityPublicReadonly permits unauthenticated public read-only providers.
	ProviderNoneSecurityPublicReadonly ProviderNoneSecurity = "public_readonly"
)

func (ProviderNoneSecurity) Validate

func (s ProviderNoneSecurity) Validate(path string) error

Validate reports whether the auth_mode=none safety rationale is supported.

type ResolvedAgent

type ResolvedAgent struct {
	Name            string
	Provider        string
	Command         string
	DisplayName     string
	Model           string
	Tools           []string
	Toolsets        []string
	DenyTools       []string
	Permissions     string
	Harness         ProviderHarness
	RuntimeProvider string
	Transport       string
	BaseURL         string
	AuthMode        ProviderAuthMode
	EnvPolicy       ProviderEnvPolicy
	HomePolicy      ProviderHomePolicy
	NoneSecurity    ProviderNoneSecurity
	AuthStatusCmd   string
	AuthLoginCmd    string
	SessionMCP      bool
	CredentialSlots []ProviderCredentialSlot
	MCPServers      []MCPServer
	Prompt          string
}

ResolvedAgent is the effective runtime configuration for a parsed agent definition.

type SandboxProfile

type SandboxProfile struct {
	Backend     string            `toml:"backend"`
	SyncMode    string            `toml:"sync_mode,omitempty"`
	Persistence string            `toml:"persistence,omitempty"`
	RuntimeRoot string            `toml:"runtime_root,omitempty"`
	Env         map[string]string `toml:"env,omitempty"`
	SecretEnv   map[string]string `toml:"secret_env,omitempty"`
	Network     NetworkProfile    `toml:"network,omitempty"`
	Daytona     DaytonaProfile    `toml:"daytona,omitempty"`
}

SandboxProfile defines one reusable execution sandbox profile.

func (SandboxProfile) Resolve

func (p SandboxProfile) Resolve(profileName string) (sandbox.Resolved, error)

Resolve converts one validated config profile into runtime sandbox policy.

func (SandboxProfile) Validate

func (p SandboxProfile) Validate(path string) error

Validate ensures the sandbox profile is internally consistent.

type SessionBusyInputConfig

type SessionBusyInputConfig struct {
	DefaultMode  string `toml:"default_mode,omitempty"`
	QueueCap     int    `toml:"queue_cap,omitempty"`
	MaxTextBytes int    `toml:"max_text_bytes,omitempty"`
}

SessionBusyInputConfig controls operator input submitted while a turn is active.

func DefaultSessionBusyInputConfig

func DefaultSessionBusyInputConfig() SessionBusyInputConfig

DefaultSessionBusyInputConfig returns the default busy-input behavior.

func (SessionBusyInputConfig) Normalize

Normalize returns a config copy with implicit defaults applied.

func (SessionBusyInputConfig) Validate

func (c SessionBusyInputConfig) Validate() error

Validate ensures busy-input controls are internally consistent.

type SessionConfig

type SessionConfig struct {
	Limits      SessionLimitsConfig      `toml:"limits"`
	Supervision SessionSupervisionConfig `toml:"supervision"`
	BusyInput   SessionBusyInputConfig   `toml:"busy_input"`
}

SessionConfig defines session-scoped runtime controls.

func (SessionConfig) Validate

func (c SessionConfig) Validate() error

Validate ensures session-scoped controls are internally consistent.

type SessionLimitsConfig

type SessionLimitsConfig struct {
	Timeout time.Duration `toml:"timeout,omitempty"`
}

SessionLimitsConfig defines runtime limits applied to every session.

func (SessionLimitsConfig) Validate

func (c SessionLimitsConfig) Validate() error

Validate ensures session timeout settings are internally consistent.

type SessionSupervisionConfig

type SessionSupervisionConfig struct {
	ActivityHeartbeatInterval time.Duration `toml:"activity_heartbeat_interval,omitempty"`
	ProgressNotifyInterval    time.Duration `toml:"progress_notify_interval,omitempty"`
	PromptDeadline            time.Duration `toml:"prompt_deadline,omitempty"`
	InactivityWarningAfter    time.Duration `toml:"inactivity_warning_after,omitempty"`
	InactivityTimeout         time.Duration `toml:"inactivity_timeout,omitempty"`
	TimeoutCancelGrace        time.Duration `toml:"timeout_cancel_grace,omitempty"`
}

SessionSupervisionConfig defines runtime activity monitoring controls applied to sessions.

func DefaultSessionSupervisionConfig

func DefaultSessionSupervisionConfig() SessionSupervisionConfig

DefaultSessionSupervisionConfig returns the default runtime activity supervision settings.

func (SessionSupervisionConfig) Validate

func (c SessionSupervisionConfig) Validate() error

Validate ensures session supervision settings are internally consistent.

type SkillsConfig

type SkillsConfig struct {
	Enabled                 bool              `toml:"enabled"`
	DisabledSkills          []string          `toml:"disabled_skills,omitempty"`
	PollInterval            time.Duration     `toml:"poll_interval"`
	AllowedMarketplaceMCP   []string          `toml:"allowed_marketplace_mcp,omitempty"`
	AllowedMarketplaceHooks []string          `toml:"allowed_marketplace_hooks,omitempty"`
	Marketplace             MarketplaceConfig `toml:"marketplace,omitempty"`
}

SkillsConfig controls skill loading and discovery.

func (SkillsConfig) Validate

func (c SkillsConfig) Validate() error

Validate ensures the skills configuration is internally consistent.

type SoulConfig

type SoulConfig struct {
	Enabled                bool  `toml:"enabled"`
	MaxBodyBytes           int64 `toml:"max_body_bytes"`
	ContextProjectionBytes int64 `toml:"context_projection_bytes"`
}

SoulConfig controls optional SOUL.md parsing and projection limits.

func DefaultSoulConfig

func DefaultSoulConfig() SoulConfig

DefaultSoulConfig returns the built-in Agent Soul resolver limits.

func (SoulConfig) Validate

func (c SoulConfig) Validate() error

Validate ensures SOUL.md limits are internally consistent.

type TaskConfig

type TaskConfig struct {
	Orchestration TaskOrchestrationConfig `toml:"orchestration"`
	Recovery      TaskRecoveryConfig      `toml:"recovery"`
}

TaskConfig controls task runtime behavior.

func DefaultTaskConfig

func DefaultTaskConfig() TaskConfig

DefaultTaskConfig returns built-in task runtime defaults.

func (TaskConfig) Validate

func (c TaskConfig) Validate() error

Validate ensures task config is safe to consume.

type TaskOrchestrationConfig

type TaskOrchestrationConfig struct {
	SummaryMaxBytes           int                            `toml:"summary_max_bytes"`
	ContextBodyMaxBytes       int                            `toml:"context_body_max_bytes"`
	ContextPriorAttempts      int                            `toml:"context_prior_attempts"`
	ContextRecentEvents       int                            `toml:"context_recent_events"`
	SpawnFailureLimit         int                            `toml:"spawn_failure_limit"`
	SchedulerBadTickThreshold int                            `toml:"scheduler_bad_tick_threshold"`
	SchedulerBadTickCooldown  time.Duration                  `toml:"scheduler_bad_tick_cooldown"`
	DefaultMaxRuntime         time.Duration                  `toml:"default_max_runtime"`
	BridgeNotificationTimeout time.Duration                  `toml:"bridge_notification_timeout"`
	Profile                   TaskOrchestrationProfileConfig `toml:"profile"`
	Review                    TaskOrchestrationReviewConfig  `toml:"review"`
}

TaskOrchestrationConfig controls bounded task orchestration behavior.

func (TaskOrchestrationConfig) Validate

func (c TaskOrchestrationConfig) Validate(path string) error

Validate ensures task orchestration config is safe to consume.

type TaskOrchestrationProfileConfig

type TaskOrchestrationProfileConfig struct {
	DefaultCoordinatorMode    string `toml:"default_coordinator_mode"`
	DefaultWorkerMode         string `toml:"default_worker_mode"`
	DefaultSandboxMode        string `toml:"default_sandbox_mode"`
	AllowTaskProviderOverride bool   `toml:"allow_task_provider_override"`
	AllowTaskSandboxNone      bool   `toml:"allow_task_sandbox_none"`
}

TaskOrchestrationProfileConfig controls task execution profile defaults and gates.

func (TaskOrchestrationProfileConfig) Validate

func (c TaskOrchestrationProfileConfig) Validate(path string) error

Validate ensures task execution profile defaults are recognized.

type TaskOrchestrationReviewConfig

type TaskOrchestrationReviewConfig struct {
	DefaultPolicy             string        `toml:"default_policy"`
	MaxRounds                 int           `toml:"max_rounds"`
	MaxReviewAttempts         int           `toml:"max_review_attempts"`
	Timeout                   time.Duration `toml:"timeout"`
	RapidTerminalWindow       time.Duration `toml:"rapid_terminal_window"`
	RapidTerminalLimit        int           `toml:"rapid_terminal_limit"`
	MissingWorkMaxItems       int           `toml:"missing_work_max_items"`
	MissingWorkItemMaxBytes   int           `toml:"missing_work_item_max_bytes"`
	ReasonMaxBytes            int           `toml:"reason_max_bytes"`
	ReviewTextMaxBytes        int           `toml:"review_text_max_bytes"`
	NextRoundGuidanceMaxBytes int           `toml:"next_round_guidance_max_bytes"`
	FailurePolicy             string        `toml:"failure_policy"`
}

TaskOrchestrationReviewConfig controls task review gate defaults and bounds.

func (TaskOrchestrationReviewConfig) Validate

func (c TaskOrchestrationReviewConfig) Validate(path string) error

Validate ensures review gate defaults are bounded.

type TaskRecoveryConfig

type TaskRecoveryConfig struct {
	AllowAgentForce bool `toml:"allow_agent_force"`
}

TaskRecoveryConfig controls task-run recovery verbs.

type ToolsConfig

type ToolsConfig struct {
	Enabled               bool                 `toml:"enabled"`
	HostedMCPEnabled      bool                 `toml:"hosted_mcp_enabled"`
	DefaultMaxResultBytes int64                `toml:"default_max_result_bytes"`
	HostedMCP             ToolsHostedMCPConfig `toml:"hosted_mcp"`
	Policy                ToolsPolicyConfig    `toml:"policy"`
}

ToolsConfig controls registry, hosted MCP, and default tool-policy lifecycle settings.

func DefaultToolsConfig

func DefaultToolsConfig() ToolsConfig

DefaultToolsConfig returns the TechSpec defaults for tool registry configuration.

func (ToolsConfig) Validate

func (c ToolsConfig) Validate(mcpServers []MCPServer, providers map[string]ProviderConfig) error

Validate ensures tools lifecycle configuration is deterministic and safe to consume.

type ToolsExternalDefault

type ToolsExternalDefault string

ToolsExternalDefault controls default policy for external executable sources.

const (
	// ToolsExternalDefaultDisabled keeps external tools operator-visible but not session-callable by default.
	ToolsExternalDefaultDisabled ToolsExternalDefault = "disabled"
	// ToolsExternalDefaultAsk requires approval for external tools that otherwise pass policy.
	ToolsExternalDefaultAsk ToolsExternalDefault = "ask"
	// ToolsExternalDefaultEnabled allows external tools that otherwise pass policy.
	ToolsExternalDefaultEnabled ToolsExternalDefault = "enabled"
)

type ToolsHostedMCPConfig

type ToolsHostedMCPConfig struct {
	BindNonceTTLSeconds int `toml:"bind_nonce_ttl_seconds"`
}

ToolsHostedMCPConfig controls AGH-hosted MCP launch binding values.

func (ToolsHostedMCPConfig) BindNonceTTL

func (c ToolsHostedMCPConfig) BindNonceTTL() time.Duration

BindNonceTTL returns the configured hosted MCP nonce lifetime.

func (ToolsHostedMCPConfig) Validate

func (c ToolsHostedMCPConfig) Validate() error

Validate ensures hosted MCP lifecycle values are inside daemon bounds.

type ToolsPolicyConfig

type ToolsPolicyConfig struct {
	ExternalDefault        ToolsExternalDefault `toml:"external_default"`
	ApprovalTimeoutSeconds int                  `toml:"approval_timeout_seconds"`
	TrustedSources         []string             `toml:"trusted_sources,omitempty"`
}

ToolsPolicyConfig controls default registry policy values consumed by later policy evaluation.

func (ToolsPolicyConfig) ApprovalTimeout

func (c ToolsPolicyConfig) ApprovalTimeout() time.Duration

ApprovalTimeout returns the configured tool approval wait.

func (ToolsPolicyConfig) Validate

func (c ToolsPolicyConfig) Validate(knownMCPSourceOwners map[string]struct{}) error

Validate ensures policy defaults are inside the supported grammar.

type ValidationError

type ValidationError struct {
	Path    string
	Message string
}

ValidationError preserves the config path for agent-parseable validation failures.

func (ValidationError) Error

func (e ValidationError) Error() string

type ValueKind

type ValueKind uint8

ValueKind identifies the TOML scalar shape supported by tool writes.

const (
	ConfigValueString ValueKind = iota
	ConfigValueBool
	ConfigValueInt
	ConfigValueInt64
	ConfigValueFloat
	ConfigValueDuration
	ConfigValueStringSlice
)

type WorkspaceDiscoveryRoot

type WorkspaceDiscoveryRoot struct {
	Dir    string
	Source WorkspaceDiscoverySource
}

WorkspaceDiscoveryRoot describes a filesystem root participating in multi-root resource discovery.

func WorkspaceDiscoveryRoots

func WorkspaceDiscoveryRoots(rootDir string, additionalDirs []string, homePaths HomePaths) []WorkspaceDiscoveryRoot

WorkspaceDiscoveryRoots returns ordered discovery roots for workspace-scoped resources. Precedence is left to right: workspace root, additional roots, then the global AGH home.

func (WorkspaceDiscoveryRoot) AgentsDir

func (r WorkspaceDiscoveryRoot) AgentsDir() string

AgentsDir returns the agent-definition directory for this discovery root.

func (WorkspaceDiscoveryRoot) SkillsDir

func (r WorkspaceDiscoveryRoot) SkillsDir() string

SkillsDir returns the skill-definition directory for this discovery root.

type WorkspaceDiscoverySource

type WorkspaceDiscoverySource string

WorkspaceDiscoverySource identifies where a discovery root came from.

const (
	// WorkspaceDiscoverySourceWorkspace marks the primary workspace root.
	WorkspaceDiscoverySourceWorkspace WorkspaceDiscoverySource = "workspace"
	// WorkspaceDiscoverySourceAdditional marks an additional workspace root.
	WorkspaceDiscoverySourceAdditional WorkspaceDiscoverySource = "additional"
	// WorkspaceDiscoverySourceGlobal marks the global AGH home root.
	WorkspaceDiscoverySourceGlobal WorkspaceDiscoverySource = "global"
)

type WriteScope

type WriteScope string

WriteScope identifies the config scope a write should target.

const (
	// WriteScopeGlobal targets the global AGH home config.
	WriteScopeGlobal WriteScope = "global"
	// WriteScopeWorkspace targets a workspace-local AGH overlay.
	WriteScopeWorkspace WriteScope = "workspace"
)

func (WriteScope) Validate

func (s WriteScope) Validate() error

Validate ensures the write scope is supported.

type WriteTarget

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

WriteTarget captures a semantic destination while keeping the on-disk path internal to the config package.

func ResolveConfigWriteTarget

func ResolveConfigWriteTarget(homePaths HomePaths, workspaceRoot string, scope WriteScope) (WriteTarget, error)

ResolveConfigWriteTarget resolves the canonical config overlay destination for the requested scope.

func ResolveMCPSidecarWriteTarget

func ResolveMCPSidecarWriteTarget(homePaths HomePaths, workspaceRoot string, scope WriteScope) (WriteTarget, error)

ResolveMCPSidecarWriteTarget resolves the canonical MCP sidecar destination for the requested scope.

func (WriteTarget) Kind

func (t WriteTarget) Kind() WriteTargetKind

Kind returns the semantic destination identifier for the write target.

func (WriteTarget) Path

func (t WriteTarget) Path() string

Path returns the resolved filesystem path for operator-facing diagnostics and tools.

func (WriteTarget) Scope

func (t WriteTarget) Scope() WriteScope

Scope returns the write scope for the target.

type WriteTargetKind

type WriteTargetKind string

WriteTargetKind describes the canonical persistence destination without exposing filesystem paths to higher layers.

const (
	// WriteTargetGlobalConfig writes `~/.agh/config.toml`.
	WriteTargetGlobalConfig WriteTargetKind = "global-config"
	// WriteTargetWorkspaceConfig writes `<workspace>/.agh/config.toml`.
	WriteTargetWorkspaceConfig WriteTargetKind = "workspace-config"
	// WriteTargetGlobalMCPSidecar writes `~/.agh/mcp.json`.
	WriteTargetGlobalMCPSidecar WriteTargetKind = "global-mcp-sidecar"
	// WriteTargetWorkspaceMCPSidecar writes `<workspace>/.agh/mcp.json`.
	WriteTargetWorkspaceMCPSidecar WriteTargetKind = "workspace-mcp-sidecar"
)

Directories

Path Synopsis
Package lifecycle owns the config-apply lifecycle matrix shared by runtime, API, CLI, web, docs, and codegen checks.
Package lifecycle owns the config-apply lifecycle matrix shared by runtime, API, CLI, web, docs, and codegen checks.

Jump to

Keyboard shortcuts

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