Documentation
¶
Overview ¶
Package config owns the typed, provenance-preserving configuration used by the coding application.
Index ¶
- Constants
- Variables
- func IsOpenAIProtocol(protocol Protocol) bool
- func NormalizeThemeSelection(value string) string
- func ParseProvider(value string) (ai.Provider, error)
- func ParseThemeSelection(value string) (string, error)
- func ParseVariant(value string) (string, error)
- func SaveStatusLine(path string, items []statusline.Item) error
- func SaveStatusLineWithOptions(path string, items []statusline.Item, options TUIConfigSaveOptions) error
- func SaveTheme(path, theme string) error
- func SaveThemeWithOptions(path, theme string, options TUIConfigSaveOptions) error
- type ApprovalMode
- type CompactionConfig
- type CompatibilityConfig
- type Config
- type Field
- type FileState
- type FileStatus
- type LoadOptions
- type LookupEnv
- type ModelConfig
- type ModelOptions
- type ModelRef
- type OperatingMode
- type Patch
- type Protocol
- type ProviderConfig
- type ReasoningLevel
- type ReasoningMode
- type Result
- type SandboxMode
- type SandboxNetworkMode
- type SandboxWorkspaceWriteConfig
- type Source
- type SourceKind
- type SubagentConfig
- type TUIConfig
- type TUIConfigSaveOptions
- type ThemeSaveOptions
- type ThemeStore
- type VariantConfig
Constants ¶
const ( ModelEnv = "PIPS_MODEL" VariantEnv = "PIPS_VARIANT" ReasoningEnv = "PIPS_REASONING" ToolSearchEnv = "PIPS_TOOL_SEARCH" DynamicSubagentsEnv = "PIPS_DYNAMIC_SUBAGENTS" ModeEnv = "PIPS_MODE" SandboxEnv = "PIPS_SANDBOX" ApprovalEnv = "PIPS_APPROVAL" )
Environment variable names understood by the configuration loader.
const DefaultThemeSelection = ThemeAuto
DefaultThemeSelection is the persisted/default TUI theme selection.
const ThemeAuto = "auto"
ThemeAuto selects the terminal-adaptive TUI theme.
Variables ¶
var ( // ErrFile means a configuration file could not be safely inspected or read. ErrFile = errors.New("coding config: file error") // ErrDecode means a configuration file is not valid for the strict schema. ErrDecode = errors.New("coding config: decode error") // ErrMigration means a removed configuration surface was detected. ErrMigration = errors.New("coding config: migration required") )
var ( // ErrConflict means an external change invalidated an expected config revision. ErrConflict = errors.New("coding config: revision conflict") // ErrUnsafe means a config target or parent does not satisfy the safe writer contract. ErrUnsafe = errors.New("coding config: unsafe filesystem object") // ErrTUIConfigEditUnsupported means the source is valid TOML but not safely // editable by the narrow single-field [tui] preference editor. ErrTUIConfigEditUnsupported = errors.New("coding config: unsupported TUI preference edit shape") // ErrThemeEditUnsupported retains the theme-specific source-shape sentinel // used by existing callers while remaining classifiable as a TUI edit error. ErrThemeEditUnsupported = errors.New("coding config: unsupported theme edit shape") // ErrStatusLineEditUnsupported identifies an unsafe status-line source shape. ErrStatusLineEditUnsupported = errors.New("coding config: unsupported status-line edit shape") // ErrThemeDurability retains the established theme error contract. The // target was replaced, but the parent directory could not be synchronized. ErrThemeDurability = errors.New("coding config: theme commit durability uncertain") // ErrStatusLineDurability identifies a committed status-line replacement // whose parent directory could not be synchronized. ErrStatusLineDurability = errors.New("coding config: status line commit durability uncertain") // ErrTUIConfigDurability is the generalized classification shared by both // field-specific durability errors. ErrTUIConfigDurability = errors.New("coding config: TUI preference commit durability uncertain") // ErrTUIConfigConflict aliases ErrConflict for TUI preference callers. ErrTUIConfigConflict = ErrConflict // ErrTUIConfigUnsafe aliases ErrUnsafe for TUI preference callers. ErrTUIConfigUnsafe = ErrUnsafe // ErrStatusLineConflict aliases ErrConflict for status-line callers. ErrStatusLineConflict = ErrConflict // ErrStatusLineUnsafe aliases ErrUnsafe for status-line callers. ErrStatusLineUnsafe = ErrUnsafe // ErrThemeConflict aliases ErrConflict for presentation-specific callers. ErrThemeConflict = ErrConflict // ErrThemeUnsafe aliases ErrUnsafe for presentation-specific callers. ErrThemeUnsafe = ErrUnsafe )
var ErrInvalid = errors.New("coding config: invalid configuration")
ErrInvalid means a configuration value or combination is invalid.
Functions ¶
func IsOpenAIProtocol ¶
IsOpenAIProtocol reports whether protocol uses an OpenAI wire surface.
func NormalizeThemeSelection ¶
NormalizeThemeSelection returns the canonical persisted selection.
func ParseProvider ¶
ParseProvider parses a stable provider identifier. Custom providers are allowed; protocol support is validated by modelcatalog after inheritance.
func ParseThemeSelection ¶
ParseThemeSelection validates and normalizes one persisted TUI theme ID. Empty values are the compatibility spelling for the automatic selection.
func ParseVariant ¶
ParseVariant parses a named request preset.
func SaveStatusLine ¶
func SaveStatusLine(path string, items []statusline.Item) error
SaveStatusLine persists status-line preferences to a default config target, allowing the target and its missing parent directories to be created.
func SaveStatusLineWithOptions ¶
func SaveStatusLineWithOptions(path string, items []statusline.Item, options TUIConfigSaveOptions) error
SaveStatusLineWithOptions persists only [tui].status_line with the same source-preserving and atomic replacement contract as SaveThemeWithOptions.
func SaveTheme ¶
SaveTheme persists theme to path. It permits creating a missing default config, while callers editing an explicit --config target should use SaveThemeWithOptions with AllowCreate=false.
func SaveThemeWithOptions ¶
func SaveThemeWithOptions(path, theme string, options TUIConfigSaveOptions) error
SaveThemeWithOptions persists theme with explicit missing-target behavior. If the returned error matches ErrThemeDurability or ErrTUIConfigDurability, the target replacement already committed and only directory-entry durability is uncertain.
Types ¶
type ApprovalMode ¶
type ApprovalMode string
ApprovalMode selects when operations require explicit approval.
const ( ApprovalOnRequest ApprovalMode = "on-request" ApprovalNever ApprovalMode = "never" )
Supported approval modes.
func ParseApprovalMode ¶
func ParseApprovalMode(value string) (ApprovalMode, error)
ParseApprovalMode parses a supported approval mode.
type CompactionConfig ¶
type CompactionConfig struct {
Enabled bool
ReserveTokens int
KeepRecentTokens int
SummaryMaxTokens int
}
CompactionConfig controls context compaction. Capacity comes from the selected model; these values only describe product policy and budgets.
func DefaultCompactionConfig ¶
func DefaultCompactionConfig() CompactionConfig
DefaultCompactionConfig returns the safe product defaults.
type CompatibilityConfig ¶
type CompatibilityConfig struct {
MaxTokensField *openai.MaxTokensField
StreamUsage *openai.StreamUsageMode
StructuredOutput *openai.StructuredOutputMode
ChatReasoning *openai.ChatReasoningFormat
ReasoningHistory *openai.ReasoningHistoryField
IncludeEncryptedReasoning *bool
}
CompatibilityConfig contains presence-aware OpenAI-compatible wire overrides. Nil means inherit the reviewed provider profile.
func (CompatibilityConfig) Clone ¶
func (c CompatibilityConfig) Clone() CompatibilityConfig
Clone returns a fully detached compatibility override.
func (CompatibilityConfig) Equal ¶
func (c CompatibilityConfig) Equal(other CompatibilityConfig) bool
Equal reports value equality without relying on pointer identity.
func (CompatibilityConfig) Resolve ¶
func (c CompatibilityConfig) Resolve(base openai.Compatibility) openai.Compatibility
Resolve applies this override to a base compatibility profile.
type Config ¶
type Config struct {
Model ModelRef
Variant string
Reasoning *ReasoningLevel
Providers map[ai.Provider]ProviderConfig
Models []ModelConfig
ToolSearch bool
// DynamicSubagents enables the Alpha custom Coding subagent dispatcher.
// It is intentionally disabled by default; profile discovery remains
// available for validation and inspection when this gate is off.
DynamicSubagents bool
Subagent SubagentConfig
Mode OperatingMode
TUI TUIConfig
Sandbox SandboxMode
SandboxWorkspaceWrite SandboxWorkspaceWriteConfig
Approval ApprovalMode
Compaction CompactionConfig
// contains filtered or unexported fields
}
Config is the final immutable-by-convention application configuration.
func Defaults ¶
func Defaults() Config
Defaults returns the built-in application settings. Model is intentionally unset so the application never hard-codes a time-sensitive model ID.
func (Config) RestoreSourceFrom ¶
RestoreSourceFrom returns a detached configuration with field provenance restored from the configured base. It changes source metadata only; the caller is responsible for setting the corresponding value first.
func (Config) ValidateRuntime ¶
ValidateRuntime verifies registry-independent fields required to resolve an executable runtime. modelcatalog performs endpoint/protocol resolution.
func (Config) WithSessionOverride ¶
WithSessionOverride returns a detached configuration whose field is marked as a process-local permission override. The source detail is intentionally fixed and cannot be supplied by callers.
type Field ¶
type Field string
Field identifies one selectable application setting for provenance queries.
const ( FieldModel Field = "model" FieldVariant Field = "variant" FieldReasoning Field = "reasoning" FieldToolSearch Field = "tool_search" FieldDynamicSubagents Field = "dynamic_subagents" FieldSubagentMaxDepth Field = "subagent.max_depth" FieldSubagentMaxConcurrent Field = "subagent.max_concurrent" FieldSubagentMaxSpawned Field = "subagent.max_spawned_per_root_interaction" FieldSubagentMaxFollowUps Field = "subagent.max_auto_follow_ups" FieldSubagentMaxTurns Field = "subagent.max_turns" FieldSubagentMaxTokens Field = "subagent.max_tokens" //nolint:gosec // Tokens are an execution budget, not credentials. FieldSubagentMaxToolCalls Field = "subagent.max_tool_calls" FieldSubagentMaxDuration Field = "subagent.max_duration_minutes" FieldMode Field = "mode" FieldTheme Field = "tui.theme" FieldStatusLine Field = "tui.status_line" FieldSandbox Field = "sandbox" FieldSandboxNetwork Field = "sandbox_workspace_write.network" FieldApproval Field = "approval" )
Configuration fields.
type FileState ¶
type FileState string
FileState describes whether a configuration file participated in loading.
type FileStatus ¶
FileStatus describes one file layer without exposing file contents.
type LoadOptions ¶
LoadOptions are all non-default inputs to one configuration snapshot.
type LookupEnv ¶
LookupEnv is an injected environment lookup. Load never reads the process environment implicitly.
type ModelConfig ¶
type ModelConfig struct {
Ref ModelRef
Protocol Protocol
ContextWindow int
ReasoningLevels []ReasoningLevel
DefaultReasoningLevel *ReasoningLevel
ReasoningBudgets map[ReasoningLevel]int
DefaultVariant string
Compatibility CompatibilityConfig
Capabilities ai.CapabilityOverride
Options ModelOptions
Variants map[string]VariantConfig
}
ModelConfig contains local metadata and request defaults for one model.
func (ModelConfig) Clone ¶
func (m ModelConfig) Clone() ModelConfig
Clone returns a fully detached model definition.
func (ModelConfig) Equal ¶
func (m ModelConfig) Equal(other ModelConfig) bool
Equal reports value equality without map or pointer identity.
type ModelOptions ¶
type ModelOptions struct {
MaxOutputTokens *int
Temperature *float64
TopP *float64
TopK *int
MinP *float64
Seed *int64
FrequencyPenalty *float64
PresencePenalty *float64
RepetitionPenalty *float64
Stop *[]string
LogProbs *bool
TopLogProbs *int
ReasoningMode *ReasoningMode
ReasoningBudget *int
IncludeReasoning *bool
ExtraBody map[string]any
}
ModelOptions are presence-aware per-request defaults. Context-window metadata lives on ModelConfig instead and is never sent to a provider.
func (ModelOptions) Clone ¶
func (o ModelOptions) Clone() ModelOptions
Clone returns a fully detached copy.
func (ModelOptions) Equal ¶
func (o ModelOptions) Equal(other ModelOptions) bool
Equal reports value equality without relying on pointer identity.
func (ModelOptions) Overlay ¶
func (o ModelOptions) Overlay(override ModelOptions) (ModelOptions, error)
Overlay returns o with every explicitly present typed value from override. Raw extension objects use recursive add-only semantics and reject collisions.
type ModelRef ¶
ModelRef is the canonical provider/model identity. Model may itself contain slashes; only the first slash is structural.
func ParseModelRef ¶
ParseModelRef parses a canonical provider/model identity.
type OperatingMode ¶
type OperatingMode string
OperatingMode selects the Coding Agent capability policy.
const ( ModeAgent OperatingMode = "agent" ModePlan OperatingMode = "plan" )
Supported Coding Agent operating modes.
func ParseOperatingMode ¶
func ParseOperatingMode(value string) (OperatingMode, error)
ParseOperatingMode parses a supported Coding Agent capability policy.
type Patch ¶
type Patch struct {
Model *ModelRef
Variant *string
Reasoning *ReasoningLevel
ToolSearch *bool
DynamicSubagents *bool
Mode *OperatingMode
Theme *string
Sandbox *SandboxMode
Approval *ApprovalMode
}
Patch represents explicitly set values in one selection/settings layer. Registry definitions are loaded from exactly one selected file and are not patched by environment variables or flags.
type Protocol ¶
type Protocol string
Protocol identifies the provider adapter and wire surface used by a model.
const ( ProtocolOpenAIAuto Protocol = "openai/auto" ProtocolOpenAIChatCompletions Protocol = "openai/chat_completions" ProtocolOpenAIResponses Protocol = "openai/responses" ProtocolAnthropicMessages Protocol = "anthropic/messages" ProtocolGeminiGenerateContent Protocol = "gemini/generate_content" )
Supported provider protocols.
func ParseProtocol ¶
ParseProtocol parses a supported provider protocol.
type ProviderConfig ¶
type ProviderConfig struct {
BaseURL string
Protocol Protocol
AllowHTTP bool
AllowPrivateIPs bool
Compatibility CompatibilityConfig
// Capabilities is the provider-wide capability declaration. Models inherit
// it field by field; see ModelConfig.Capabilities.
Capabilities ai.CapabilityOverride
}
ProviderConfig describes one reusable provider connection. Credentials are intentionally absent and are acquired from credential.Store at runtime.
func (ProviderConfig) Clone ¶
func (p ProviderConfig) Clone() ProviderConfig
Clone returns a fully detached provider definition.
func (ProviderConfig) Equal ¶
func (p ProviderConfig) Equal(other ProviderConfig) bool
Equal reports value equality without relying on pointer identity.
type ReasoningLevel ¶
type ReasoningLevel string
ReasoningLevel is a model-defined, ordered reasoning capability value.
func ParseReasoningLevel ¶
func ParseReasoningLevel(value string) (ReasoningLevel, error)
ParseReasoningLevel parses a model-defined reasoning selector.
type ReasoningMode ¶
type ReasoningMode string
ReasoningMode controls provider reasoning independently from its level.
const ( ReasoningAuto ReasoningMode = "auto" ReasoningEnabled ReasoningMode = "enabled" ReasoningAdaptive ReasoningMode = "adaptive" ReasoningDisabled ReasoningMode = "disabled" )
Portable reasoning modes.
type Result ¶
type Result struct {
Config Config
ConfigFile FileStatus
}
Result contains the effective configuration and diagnostic layer state.
func Load ¶
func Load(options LoadOptions) (Result, error)
Load resolves one configuration snapshot in increasing precedence order.
type SandboxMode ¶
type SandboxMode string
SandboxMode selects the application sandbox boundary.
const ( SandboxReadOnly SandboxMode = "read-only" SandboxWorkspaceWrite SandboxMode = "workspace-write" SandboxFullAccess SandboxMode = "full-access" )
Supported sandbox modes.
func ParseSandboxMode ¶
func ParseSandboxMode(value string) (SandboxMode, error)
ParseSandboxMode parses a supported sandbox mode.
type SandboxNetworkMode ¶
type SandboxNetworkMode string
SandboxNetworkMode controls child-process network authority in sandboxed profiles.
const ( SandboxNetworkDeny SandboxNetworkMode = "deny" SandboxNetworkOnRequest SandboxNetworkMode = "on-request" SandboxNetworkAllow SandboxNetworkMode = "allow" )
Supported sandboxed network modes.
func ParseSandboxNetworkMode ¶
func ParseSandboxNetworkMode(value string) (SandboxNetworkMode, error)
ParseSandboxNetworkMode parses a supported sandboxed network mode.
type SandboxWorkspaceWriteConfig ¶
type SandboxWorkspaceWriteConfig struct {
Network SandboxNetworkMode
}
SandboxWorkspaceWriteConfig retains the compatibility settings used by sandboxed profiles.
type Source ¶
type Source struct {
Kind SourceKind
Detail string
}
Source records the winning layer and its non-secret origin.
type SourceKind ¶
type SourceKind string
SourceKind identifies a configuration layer or process-local override.
const ( SourceDefault SourceKind = "default" SourceConfigFile SourceKind = "config_file" SourceEnvironment SourceKind = "environment" SourceFlag SourceKind = "flag" SourceSessionOverride SourceKind = "session_override" )
Configuration source kinds plus the process-local session override marker.
type SubagentConfig ¶
type SubagentConfig struct {
MaxDepth int
MaxConcurrent int
MaxSpawnedPerRootInteraction int
MaxAutoFollowUps int
MaxTurns int
MaxTokens int
MaxToolCalls int
MaxDurationMinutes int
}
SubagentConfig contains the user-configurable production admission and execution budgets. MaxDepth defaults to zero (recursive delegation off); zero is invalid for every other TOML field. The complete programmatic zero value remains a legacy embedding boundary and is normalized by Runtime.
func DefaultSubagentConfig ¶
func DefaultSubagentConfig() SubagentConfig
DefaultSubagentConfig returns the bounded production policy.
type TUIConfig ¶
type TUIConfig struct {
Theme string
StatusLine []statusline.Item
}
TUIConfig contains presentation-only configuration. It is intentionally not projected into Runtime, Session, or Coding event state.
type TUIConfigSaveOptions ¶
type TUIConfigSaveOptions struct {
AllowCreate bool
}
TUIConfigSaveOptions controls whether a missing target may be created. The default SaveTheme and SaveStatusLine helpers (where applicable) permit creation for the default config path; an explicit --config target should use AllowCreate=false.
type ThemeSaveOptions ¶
type ThemeSaveOptions = TUIConfigSaveOptions
ThemeSaveOptions is retained as a source-compatible name for theme callers.
type ThemeStore ¶
type ThemeStore struct {
// contains filtered or unexported fields
}
ThemeStore persists only the [tui].theme scalar in one active config file. It never marshals or reconstructs the complete Config value.
func NewThemeStore ¶
func NewThemeStore(path string) *ThemeStore
NewThemeStore returns a theme editor that may create a missing target.
func NewThemeStoreWithOptions ¶
func NewThemeStoreWithOptions(path string, options ThemeSaveOptions) *ThemeStore
NewThemeStoreWithOptions returns a theme editor with explicit target policy.
func (*ThemeStore) Save ¶
func (store *ThemeStore) Save(theme string) error
Save writes the requested theme selection while preserving all unrelated source bytes and validating the original and edited TOML documents.
type VariantConfig ¶
type VariantConfig struct {
ReasoningLevel *ReasoningLevel
Options ModelOptions
}
VariantConfig is a named request-option overlay.