config

package
v0.1.9 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source
const (
	ScreenFullscreen = "fullscreen"
	ScreenInline     = "inline"
)

Interactive screen layouts.

View Source
const (
	AltScreenAuto   = "auto"
	AltScreenAlways = "always"
	AltScreenNever  = "never"
)

Alternate-screen policies.

View Source
const (
	DefaultInteractiveScreen = ScreenFullscreen
	DefaultAltScreenPolicy   = AltScreenAuto
)

DefaultInteractiveScreen and DefaultAltScreenPolicy are the shipped defaults.

View Source
const (
	// ExitOutputTranscript writes the rendered conversation to the main screen
	// after the terminal is restored, because the alternate screen is discarded
	// on exit and would otherwise leave nothing to scroll.
	ExitOutputTranscript = "transcript"
	// ExitOutputResumeHint keeps only the resume hint and leaves the main screen
	// as the renderer restored it.
	ExitOutputResumeHint = "resume-hint"
)

Exit-output policies.

View Source
const (
	// LimitBehaviorQueue parks a spawn at the cap until a slot frees.
	LimitBehaviorQueue = "queue"
	// LimitBehaviorFail rejects a spawn at the cap.
	LimitBehaviorFail = "fail"
)

LimitBehavior values for SubagentConfig.LimitBehavior.

View Source
const (
	ModelEnv            = "PIPS_MODEL"
	VariantEnv          = "PIPS_VARIANT"
	ReasoningEnv        = "PIPS_REASONING"
	ToolSearchEnv       = "PIPS_TOOL_SEARCH"
	ToolSearchNameEnv   = "PIPS_TOOL_SEARCH_NAME"
	DynamicSubagentsEnv = "PIPS_DYNAMIC_SUBAGENTS"
	// ActiveAgentMessagesEnv opens the model-facing child messaging surface.
	ActiveAgentMessagesEnv = "PIPS_ACTIVE_AGENT_MESSAGES"
	// SubagentLimitBehaviorEnv overrides [subagents].limit_behavior. It is not
	// pinnable; an invalid value falls back to queue.
	SubagentLimitBehaviorEnv = "PIPS_SUBAGENT_LIMIT_BEHAVIOR"
	// SubagentAwaitBudgetEnv bounds a foreground queued spawn's wait in
	// milliseconds before it is handed off to the background.
	SubagentAwaitBudgetEnv = "PIPS_SUBAGENT_AWAIT_BUDGET_MS"
	ModeEnv                = "PIPS_MODE"
	SandboxEnv             = "PIPS_SANDBOX"
	ApprovalEnv            = "PIPS_APPROVAL"
)

Environment variable names understood by the configuration loader.

View Source
const DefaultCostCurrency = "USD"

DefaultCostCurrency is the currency a cost table without an explicit one reports.

View Source
const DefaultExitOutput = ExitOutputResumeHint

DefaultExitOutput ships the resume hint: a fullscreen session owns the conversation, and quitting leaves the terminal as the renderer restored it. The transcript handoff stays available as an explicit [tui] exit_output value.

View Source
const DefaultMouseReporting = true

DefaultMouseReporting enables mouse capture by default; the alternate screen has no terminal-native scrolling, so wheel support is part of the layout.

View Source
const DefaultShowThinkingBlocks = true

DefaultShowThinkingBlocks renders the model's visible reasoning as dimmed Thinking blocks, matching the reference agents. [tui] show_thinking_blocks = false hides them without disabling the Thinking… activity indicator.

View Source
const DefaultThemeSelection = ThemeAuto

DefaultThemeSelection is the persisted/default TUI theme selection.

View Source
const MCPReadOnlyWildcard = "*"

MCPReadOnlyWildcard marks every tool of one MCP server as read-only.

View Source
const SubagentRoleSourceInline = "config"

SubagentRoleSourceInline is the provenance string of a role or persona declared inside config.toml rather than in its own file.

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 (
	// ErrSelectionEditUnsupported means the active config's source shape cannot
	// be edited without risking an unrelated table or value.
	ErrSelectionEditUnsupported = errors.New("coding config: unsupported model selection edit shape")
	// ErrSelectionDurability means the replacement committed but the parent
	// directory could not be synchronized.
	ErrSelectionDurability = errors.New("coding config: model selection commit durability uncertain")
	// ErrSelectionConflict aliases the shared revision conflict for selection
	// callers.
	ErrSelectionConflict = ErrConflict
	// ErrSelectionUnsafe aliases the shared unsafe-target error for selection
	// callers.
	ErrSelectionUnsafe = ErrUnsafe
)
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 ParseAltScreenPolicy added in v0.1.6

func ParseAltScreenPolicy(value string) (string, error)

ParseAltScreenPolicy validates one persisted alternate-screen policy.

func ParseExitOutput added in v0.1.6

func ParseExitOutput(value string) (string, error)

ParseExitOutput validates one persisted exit-output policy.

func ParseInteractiveScreen added in v0.1.6

func ParseInteractiveScreen(value string) (string, error)

ParseInteractiveScreen validates one persisted interactive render layout.

func ParseLimitBehavior added in v0.1.9

func ParseLimitBehavior(value string) (string, bool)

ParseLimitBehavior accepts the two supported limit behaviors and reports false for anything else.

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 ParseToolSearchName added in v0.1.5

func ParseToolSearchName(value string) (string, error)

ParseToolSearchName parses a portable deferred discovery tool name. Only the syntax is checked here; collisions with catalog tools surface when the Runtime constructs the interaction toolset.

func ParseVariant

func ParseVariant(value string) (string, error)

ParseVariant parses a named request preset.

func SaveSelectionWithOptions added in v0.1.9

func SaveSelectionWithOptions(path string, selection SelectionPreference, options TUIConfigSaveOptions) error

SaveSelectionWithOptions persists a complete model/variant/reasoning selection to the active config file. The selected model becomes the only model with default = true; variant and reasoning are written as top-level keys. Empty variant/reasoning values remove their keys.

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.

func TypeEnabled added in v0.1.9

func TypeEnabled(toggle map[string]bool, name string) bool

TypeEnabled reports whether one agent type may be dispatched from a per-type toggle table. An absent key means enabled, so an empty table disables nothing. The lookup is exact and case-sensitive.

func ValidateSubagentPersona added in v0.1.9

func ValidateSubagentPersona(name string, persona SubagentPersona) error

ValidateSubagentPersona checks the declaration-level shape of one persona.

func ValidateSubagentRole added in v0.1.9

func ValidateSubagentRole(name string, role SubagentRole) error

ValidateSubagentRole checks the declaration-level shape of one role. It does not validate the capability-mode spelling, which the agent profile layer owns.

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 is accepted for legacy configuration compatibility.
	// Full checkpoints do not retain a working tail.
	KeepRecentTokens int
	// SummaryMaxTokens is an optional override; zero inherits model policy.
	SummaryMaxTokens  int
	ThresholdPercent  int
	MinSummaryChars   int
	AttemptsPerStage  int
	RetryDelaySeconds int
	TimeoutSeconds    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 bounded single-pass product policy.

type CompatibilityConfig

type CompatibilityConfig struct {
	MaxTokensField            *openai.MaxTokensField
	StreamUsage               *openai.StreamUsageMode
	StructuredOutput          *openai.StructuredOutputMode
	ChatReasoning             *openai.ChatReasoningFormat
	ReasoningHistory          *openai.ReasoningHistoryField
	IncludeEncryptedReasoning *bool
	PromptCacheKey            *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
	// ToolSearchName is the deferred discovery tool name offered to the model.
	// It defaults to catalog.DefaultToolSearchName; a provider entry may
	// override it when a proxy reserves or rewrites the default name.
	ToolSearchName string
	// 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
	// ActiveAgentMessages enables the model-facing child messaging surface. It
	// is off by default: while the gate is closed no messaging Tool is offered
	// and every delivery is refused rather than dropped.
	ActiveAgentMessages bool
	// TodoGate enables the turn-end todo gate. It is off by default: the gate
	// spends an extra inference turn, so it is opt-in, matching the reference.
	TodoGate              bool
	Subagent              SubagentConfig
	Mode                  OperatingMode
	TUI                   TUIConfig
	Cost                  CostConfig
	Sandbox               SandboxMode
	SandboxWorkspaceWrite SandboxWorkspaceWriteConfig
	Approval              ApprovalMode
	Compaction            CompactionConfig
	Media                 MediaConfig
	// MCPReadOnlyTools marks MCP tools, keyed by server ID, as read-only so
	// they may run concurrently within one model response. Values are remote
	// tool names or "*" for every tool of the server. It affects execution
	// concurrency only; risk, approval, and visibility are unchanged. MCP
	// readOnlyHint annotations are never trusted for this decision.
	MCPReadOnlyTools map[string][]string
	// 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) ToolSearchNameFor added in v0.1.5

func (c Config) ToolSearchNameFor(provider ai.Provider) string

ToolSearchNameFor resolves the deferred discovery tool name for an interaction served by provider: the provider override when set, otherwise the global value, otherwise catalog.DefaultToolSearchName.

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 CostConfig added in v0.1.7

type CostConfig struct {
	Currency string
	Models   map[string]ModelPricing
}

CostConfig is the resolved [cost] price table the Usage page prices its rows with. It is input data for a number, not a layered setting, so it carries no Field or Source and is not shown on the panel's Config page.

func (CostConfig) Price added in v0.1.7

func (c CostConfig) Price(ref string) (ModelPricing, bool)

Price returns one model ref's prices and whether the ref has an entry at all. A ref with no entry is priced at zero and reported unpriced, so a caller can count what it could not price instead of presenting a partial sum as complete.

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"
	FieldToolSearchName Field = "tool_search_name"
	// FieldDynamicSubagents is the master subagent switch. It defaults to true.
	FieldDynamicSubagents Field = "dynamic_subagents"
	// FieldSubagentEnabled is the `[subagents]` spelling of the same master
	// switch as FieldDynamicSubagents. Both fields report one resolved value,
	// because the two spellings are one setting rather than two.
	FieldSubagentEnabled Field = "subagents.enabled"
	// FieldActiveAgentMessages enables model-authored messages to a live or
	// completed child. It defaults to false.
	FieldActiveAgentMessages Field = "active_agent_messages"
	// FieldTodoGate enables the turn-end todo gate: when a run ends on a
	// content-only assistant message with pending or in-progress plan items, the
	// runtime runs one more turn carrying the gate reminder. It defaults to
	// false, matching the reference's opt-in gate.
	FieldTodoGate              Field = "todo_gate"
	FieldSubagentMaxDepth      Field = "subagents.max_depth"
	FieldSubagentMaxConcurrent Field = "subagents.max_concurrent"
	// FieldSubagentStructuredResults restores the typed JSON result contract
	// for builtin agents. It defaults to false: a builtin agent returns its
	// final text.
	FieldSubagentStructuredResults Field = "subagents.structured_results"
	// FieldSubagentLimitBehavior selects what happens when the concurrent
	// subagent cap is reached: queue (default) or fail.
	FieldSubagentLimitBehavior Field = "subagents.limit_behavior"
	// FieldSubagentModels is the per-type model override table.
	FieldSubagentModels Field = "subagents.models"
	// FieldSubagentRoles is the inline role declaration table.
	FieldSubagentRoles Field = "subagents.roles"
	// FieldSubagentPersonas is the inline persona declaration table.
	FieldSubagentPersonas Field = "subagents.personas"
	// FieldSubagentToggle is the per-type enable/disable table. An absent key
	// means the type stays enabled.
	FieldSubagentToggle     Field = "subagents.toggle"
	FieldMode               Field = "mode"
	FieldTheme              Field = "tui.theme"
	FieldStatusLine         Field = "tui.status_line"
	FieldScreen             Field = "tui.screen"
	FieldAltScreen          Field = "tui.alt_screen"
	FieldMouse              Field = "tui.mouse"
	FieldExitOutput         Field = "tui.exit_output"
	FieldShowThinkingBlocks Field = "tui.show_thinking_blocks"
	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 MediaConfig added in v0.1.9

type MediaConfig struct {
	// MaxRequestBytes caps one provider request body after hydration. Zero
	// disables the budget check.
	MaxRequestBytes int
	// CleanupTTLDays removes idle session directories and prunes expired media
	// from live sessions. Zero disables automatic deletion.
	CleanupTTLDays int
	// GCGraceHours is the minimum media age before orphan collection removes it.
	GCGraceHours int
}

MediaConfig bounds persisted session media and one provider request body.

func DefaultMediaConfig added in v0.1.9

func DefaultMediaConfig() MediaConfig

DefaultMediaConfig returns the bounded product policy: a 30 MiB request budget, a 30-day idle TTL, and a 24-hour orphan grace period.

type ModelConfig

type ModelConfig struct {
	Ref           ModelRef
	Protocol      Protocol
	ContextWindow int
	// StreamContinuation opts this model into prefix continuation, keeping a
	// broken turn's partial answer instead of regenerating it. It stays a
	// per-model opt-in because a provider must be verified to honour a
	// trailing assistant message; the default regenerates.
	StreamContinuation bool
	// StreamIdleTimeout bounds the silence between reads on a streaming response
	// body, overriding the provider's value. It is the knob for a model that
	// legitimately pauses — a long reasoning block the endpoint does not stream
	// incrementally — and the retry window scales with it. Zero inherits the
	// provider's value, and then the transport default. Like ContextWindow it is
	// local metadata: it is never sent as a request option.
	StreamIdleTimeout     time.Duration
	ReasoningLevels       []ReasoningLevel
	DefaultReasoningLevel *ReasoningLevel
	ReasoningBudgets      map[ReasoningLevel]int
	DefaultVariant        string
	Compatibility         CompatibilityConfig
	Capabilities          ai.CapabilityOverride
	Options               ModelOptions
	Variants              map[string]VariantConfig
	// UserAgentEnabled declares whether this model's requests carry a
	// User-Agent header at all, overriding the provider's declaration. Nil
	// inherits it, and then the client's own default.
	UserAgentEnabled *bool
	// UserAgent replaces the User-Agent this model's requests carry, overriding
	// the provider's value. Nil inherits it, and then the client's own default.
	UserAgent *string
}

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 ModelPricing added in v0.1.7

type ModelPricing struct {
	InputPerMillionTokens       float64
	CachedInputPerMillionTokens float64
	CacheWritePerMillionTokens  float64
	OutputPerMillionTokens      float64
}

ModelPricing is one model's configured prices, each per million tokens. Every field is optional and an absent one counts zero.

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
	ToolSearchName   *string
	DynamicSubagents *bool
	// NoSubagents is the `--no-subagents` spelling of the master switch. Its
	// value is the flag's own value, so a passed `--no-subagents` is true and
	// an explicit `--no-subagents=false` is false. It is CLI-only; it exists so
	// the two flag spellings can be detected and a contradiction between them
	// reported instead of one silently winning.
	NoSubagents *bool
	// ActiveAgentMessages opens the child messaging gate. It is env-only and
	// file-only; no CLI flag selects it.
	ActiveAgentMessages *bool
	// TodoGate enables the turn-end todo gate. It is file-only; no CLI flag
	// selects it.
	TodoGate *bool
	// SubagentLimitBehavior overrides the concurrent-cap behavior. It is
	// env-only; an invalid value falls back to queue.
	SubagentLimitBehavior *string
	Mode                  *OperatingMode
	Theme                 *string
	Screen                *string
	AltScreen             *string
	Mouse                 *bool
	ExitOutput            *string
	ShowThinking          *bool
	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
	// ToolSearchName overrides Config.ToolSearchName for interactions served
	// by this provider. Empty inherits the global value; see ToolSearchNameFor.
	ToolSearchName string
	// StreamIdleTimeout bounds the silence between reads on a streaming response
	// body for this provider's endpoints, and is the default for its models; see
	// ModelConfig.StreamIdleTimeout. Zero inherits the transport default. It is
	// local transport policy: it is never sent as a request option.
	StreamIdleTimeout time.Duration
	// UserAgentEnabled declares whether this provider's requests carry a
	// User-Agent header at all. Nil sends the client's own default; a false
	// declaration sends no header.
	UserAgentEnabled *bool
	// UserAgent replaces the User-Agent this provider's requests carry, and is
	// the default for its models. Nil sends the client's own default, and the
	// value is trimmed. Like StreamIdleTimeout it is local transport policy: it
	// is never sent as a request option.
	UserAgent *string
}

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 SelectionPreference added in v0.1.9

type SelectionPreference struct {
	Model     ModelRef
	Variant   string
	Reasoning *ReasoningLevel
}

SelectionPreference is the durable form of a model-picker selection.

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
	// StructuredResults restores the typed JSON result contract for builtin
	// agents. The default is a free-text summary.
	StructuredResults bool
	// LimitBehavior selects what happens at the concurrent subagent cap:
	// "queue" parks the spawn until a slot frees, "fail" rejects it. The empty
	// value is the legacy embedding boundary and resolves to "queue".
	LimitBehavior string
	// Models overrides the model of one agent type by exact name. An
	// unresolvable reference falls back to the parent model.
	Models map[string]string
	// Toggle disables individual agent types by exact, case-sensitive name. An
	// absent key leaves the type enabled, so an empty table changes nothing.
	Toggle map[string]bool
	// Roles and Personas are inline declarations keyed by exact agent type
	// name. They take precedence over the same-named file declarations.
	Roles    map[string]SubagentRole
	Personas map[string]SubagentPersona
}

SubagentConfig contains the user-configurable production admission budgets, parsed from the `[subagents]` table. MaxDepth defaults to one: a child may not spawn another child. Zero is invalid for max_concurrent. A child's execution is unbounded by default — the reference has no per-child execution budget — and only a subagent definition's `limits` may cap it. The reference bounds no spawn count per root and no auto-follow-up count either, so neither is a configuration surface. The complete programmatic zero value remains a legacy embedding boundary and is normalized by Runtime.

func DefaultSubagentConfig

func DefaultSubagentConfig() SubagentConfig

DefaultSubagentConfig returns the bounded admission policy. A child's execution carries no default budget; only a definition's `limits` caps it.

func (SubagentConfig) IsZero added in v0.1.9

func (c SubagentConfig) IsZero() bool

IsZero reports whether the config is the legacy programmatic zero value. Runtime normalizes that boundary; file loading always starts from DefaultSubagentConfig. It exists because the maps make the struct non-comparable.

func (SubagentConfig) TypeEnabled added in v0.1.9

func (c SubagentConfig) TypeEnabled(name string) bool

TypeEnabled reports whether this configuration allows one agent type.

type SubagentIOField added in v0.1.9

type SubagentIOField struct {
	// Name is the field identifier.
	Name string `toml:"name"`
	// Type is the field's declared shape. It defaults to "file".
	Type string `toml:"type"`
	// Required reports whether the field must be supplied.
	Required bool `toml:"required"`
	// Description explains the field.
	Description string `toml:"description"`
}

SubagentIOField is one declared persona input or output.

type SubagentPersona added in v0.1.9

type SubagentPersona struct {
	// Instructions is the inline behavioral text.
	Instructions string `toml:"instructions"`
	// Description is the optional human-readable summary.
	Description string `toml:"description"`
	// InstructionsFile is a file whose content is appended to Instructions.
	InstructionsFile string `toml:"instructions_file"`
	// Inputs and Outputs describe the persona's declared contract. pips parses
	// and validates them for configuration fidelity; nothing surfaces them to
	// the parent model yet.
	Inputs  []SubagentIOField `toml:"inputs"`
	Outputs []SubagentIOField `toml:"outputs"`
	// DefaultIsolation is the isolation mode requested for the type.
	DefaultIsolation string `toml:"default_isolation"`
	// Model is a configured model reference used when nothing above names one.
	Model string `toml:"model"`
	// ReasoningEffort is a portable reasoning level for the child model.
	ReasoningEffort string `toml:"reasoning_effort"`

	// Reminder is the resolved inline-plus-file instruction text.
	Reminder string `toml:"-"`
	// Source is the safe provenance string of the declaration.
	Source string `toml:"-"`
}

SubagentPersona is a named behavioral overlay. Its instructions are injected into the child's initial message list as a synthetic user item; a persona has no capability mode. It is selected by the agent type name and it is not a spawn argument.

type SubagentRole added in v0.1.9

type SubagentRole struct {
	// Description is the required human-readable summary of the role.
	Description string `toml:"description"`
	// DefaultCapabilityMode narrows the tool kinds of the type that names it.
	// The value is validated where the role is resolved, because the capability
	// vocabulary belongs to the agent profile layer.
	DefaultCapabilityMode string `toml:"default_capability_mode"`
	// Model is a configured model reference used when the spawn names none.
	Model string `toml:"model"`
	// ReasoningEffort is a portable reasoning level for the child model.
	ReasoningEffort string `toml:"reasoning_effort"`
	// PromptFile is a file rendered into the child system prompt inside a
	// <role-instructions> block. A file-based role resolves it inside its own
	// directory; an inline role resolves it inside the workspace.
	PromptFile string `toml:"prompt_file"`
	// DefaultIsolation is the isolation mode requested for the type.
	DefaultIsolation string `toml:"default_isolation"`

	// Prompt is the resolved PromptFile content. It is empty when no file is
	// configured or the file could not be read.
	Prompt string `toml:"-"`
	// Source is the safe provenance string of the declaration.
	Source string `toml:"-"`
}

SubagentRole is a named defaults preset for one subagent type. A role narrows the type's capability mode and supplies model, reasoning, prompt-file, and isolation defaults; it never defines a toolset. It is selected by the agent type name and it is not a spawn argument.

type TUIConfig

type TUIConfig struct {
	Theme      string
	StatusLine []statusline.Item
	// Screen selects the interactive render layout: ScreenFullscreen owns a
	// fixed-height layout and its own scrolling; ScreenInline keeps the
	// terminal's native history and a mutable tail.
	Screen string
	// AltScreen selects the terminal buffer independently of the layout, so a
	// fullscreen layout may still be drawn inline in the main buffer.
	AltScreen string
	// Mouse enables mouse capture. Cell-motion reporting is used under a
	// terminal multiplexer, all-motion elsewhere.
	Mouse bool
	// ExitOutput selects what a normal exit leaves on the terminal's main
	// screen: the whole conversation or only the resume hint.
	ExitOutput string
	// ShowThinkingBlocks renders visible model reasoning as dimmed Thinking
	// blocks in the fullscreen viewport. The provider's opaque reasoning
	// signature is never rendered either way.
	ShowThinkingBlocks bool
}

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