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 ParseAltScreenPolicy(value string) (string, error)
- func ParseExitOutput(value string) (string, error)
- func ParseInteractiveScreen(value string) (string, error)
- func ParseLimitBehavior(value string) (string, bool)
- func ParseProvider(value string) (ai.Provider, error)
- func ParseThemeSelection(value string) (string, error)
- func ParseToolSearchName(value string) (string, error)
- func ParseVariant(value string) (string, error)
- func SaveSelectionWithOptions(path string, selection SelectionPreference, options TUIConfigSaveOptions) 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
- func TypeEnabled(toggle map[string]bool, name string) bool
- func ValidateSubagentPersona(name string, persona SubagentPersona) error
- func ValidateSubagentRole(name string, role SubagentRole) error
- type ApprovalMode
- type CompactionConfig
- type CompatibilityConfig
- type Config
- func (c Config) Clone() Config
- func (c Config) Equal(other Config) bool
- func (c Config) RestoreSourceFrom(base Config, field Field) Config
- func (c Config) Source(field Field) (Source, bool)
- func (c Config) ToolSearchNameFor(provider ai.Provider) string
- func (c Config) ValidateRuntime() error
- func (c Config) WithSessionOverride(field Field) Config
- type CostConfig
- type Field
- type FileState
- type FileStatus
- type LoadOptions
- type LookupEnv
- type MediaConfig
- type ModelConfig
- type ModelOptions
- type ModelPricing
- type ModelRef
- type OperatingMode
- type Patch
- type Protocol
- type ProviderConfig
- type ReasoningLevel
- type ReasoningMode
- type Result
- type SandboxMode
- type SandboxNetworkMode
- type SandboxWorkspaceWriteConfig
- type SelectionPreference
- type Source
- type SourceKind
- type SubagentConfig
- type SubagentIOField
- type SubagentPersona
- type SubagentRole
- type TUIConfig
- type TUIConfigSaveOptions
- type ThemeSaveOptions
- type ThemeStore
- type VariantConfig
Constants ¶
const ( ScreenFullscreen = "fullscreen" ScreenInline = "inline" )
Interactive screen layouts.
const ( AltScreenAuto = "auto" AltScreenAlways = "always" AltScreenNever = "never" )
Alternate-screen policies.
const ( DefaultInteractiveScreen = ScreenFullscreen DefaultAltScreenPolicy = AltScreenAuto )
DefaultInteractiveScreen and DefaultAltScreenPolicy are the shipped defaults.
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.
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.
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.
const DefaultCostCurrency = "USD"
DefaultCostCurrency is the currency a cost table without an explicit one reports.
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.
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.
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.
const DefaultThemeSelection = ThemeAuto
DefaultThemeSelection is the persisted/default TUI theme selection.
const MCPReadOnlyWildcard = "*"
MCPReadOnlyWildcard marks every tool of one MCP server as read-only.
const SubagentRoleSourceInline = "config"
SubagentRoleSourceInline is the provenance string of a role or persona declared inside config.toml rather than in its own file.
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 ( // 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 )
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 ParseAltScreenPolicy ¶ added in v0.1.6
ParseAltScreenPolicy validates one persisted alternate-screen policy.
func ParseExitOutput ¶ added in v0.1.6
ParseExitOutput validates one persisted exit-output policy.
func ParseInteractiveScreen ¶ added in v0.1.6
ParseInteractiveScreen validates one persisted interactive render layout.
func ParseLimitBehavior ¶ added in v0.1.9
ParseLimitBehavior accepts the two supported limit behaviors and reports false for anything else.
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 ParseToolSearchName ¶ added in v0.1.5
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 ¶
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 ¶
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
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 ¶
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
// 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) 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) ToolSearchNameFor ¶ added in v0.1.5
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 ¶
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 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.
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 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 ¶
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
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 ¶
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.