config

package
v0.1.3 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package config owns the typed, provenance-preserving configuration used by the coding application.

Index

Constants

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

View Source
const DefaultThemeSelection = ThemeAuto

DefaultThemeSelection is the persisted/default TUI theme selection.

View Source
const ThemeAuto = "auto"

ThemeAuto selects the terminal-adaptive TUI theme.

Variables

View Source
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")
)
View Source
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
)
View Source
var ErrInvalid = errors.New("coding config: invalid configuration")

ErrInvalid means a configuration value or combination is invalid.

Functions

func IsOpenAIProtocol

func IsOpenAIProtocol(protocol Protocol) bool

IsOpenAIProtocol reports whether protocol uses an OpenAI wire surface.

func NormalizeThemeSelection

func NormalizeThemeSelection(value string) string

NormalizeThemeSelection returns the canonical persisted selection.

func ParseProvider

func ParseProvider(value string) (ai.Provider, error)

ParseProvider parses a stable provider identifier. Custom providers are allowed; protocol support is validated by modelcatalog after inheritance.

func ParseThemeSelection

func ParseThemeSelection(value string) (string, error)

ParseThemeSelection validates and normalizes one persisted TUI theme ID. Empty values are the compatibility spelling for the automatic selection.

func ParseVariant

func ParseVariant(value string) (string, error)

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

func SaveTheme(path, theme string) error

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

Clone returns a fully detached compatibility override.

func (CompatibilityConfig) Equal

Equal reports value equality without relying on pointer identity.

func (CompatibilityConfig) Resolve

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) Clone

func (c Config) Clone() Config

Clone returns a fully detached configuration snapshot.

func (Config) Equal

func (c Config) Equal(other Config) bool

Equal reports value equality without map or pointer identity.

func (Config) RestoreSourceFrom

func (c Config) RestoreSourceFrom(base Config, field Field) Config

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

func (c Config) Source(field Field) (Source, bool)

Source returns the winning source for field.

func (Config) ValidateRuntime

func (c Config) ValidateRuntime() error

ValidateRuntime verifies registry-independent fields required to resolve an executable runtime. modelcatalog performs endpoint/protocol resolution.

func (Config) WithSessionOverride

func (c Config) WithSessionOverride(field Field) Config

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.

func Fields

func Fields() []Field

Fields returns all selectable fields in display order.

type FileState

type FileState string

FileState describes whether a configuration file participated in loading.

const (
	FileStateAbsent FileState = "absent"
	FileStateLoaded FileState = "loaded"
)

Configuration file states.

type FileStatus

type FileStatus struct {
	Path  string
	State FileState
}

FileStatus describes one file layer without exposing file contents.

type LoadOptions

type LoadOptions struct {
	ConfigFile    string
	LookupEnv     LookupEnv
	FlagOverrides Patch
}

LoadOptions are all non-default inputs to one configuration snapshot.

type LookupEnv

type LookupEnv func(string) (string, bool)

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

type ModelRef struct {
	Provider ai.Provider
	Model    string
}

ModelRef is the canonical provider/model identity. Model may itself contain slashes; only the first slash is structural.

func ParseModelRef

func ParseModelRef(value string) (ModelRef, error)

ParseModelRef parses a canonical provider/model identity.

func (ModelRef) String

func (r ModelRef) String() string

String returns the 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

func ParseProtocol(value string) (Protocol, error)

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.

Jump to

Keyboard shortcuts

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