config

package
v0.34.2 Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	PlanClarifyModeSmart = "smart"
	PlanClarifyModeAuto  = "auto"
	PlanClarifyModeAsk   = "ask"
)

Plan clarify mode constants — keep in sync with the values rendered by the Settings dropdown and the prompt branches in internal/prompt/builder.go.

View Source 
const (
	MCPTransportStdio          = "stdio"
	MCPTransportStreamableHTTP = "streamable_http"
	MCPTransportSSE            = "sse"
	MCPTransportWebSocket      = "websocket"
)
View Source 
const (
	MCPAuthModeNone   = "none"
	MCPAuthModeBearer = "bearer"
	MCPAuthModeOAuth  = "oauth"
)
View Source 
const DefaultConfigFilename = "config/default.yaml"

Variables

This section is empty.

Functions

func ActiveEnvOverrides added in v0.32.0 

func ActiveEnvOverrides() map[string]EnvOverrideMeta

func ConfigToMap added in v0.14.0 

func ConfigToMap(cfg Config) map[string]any

ConfigToMap converts a Config to a flat map keyed by YAML keys.

func DefaultWorkspaceDir added in v0.15.2 

func DefaultWorkspaceDir() string

DefaultWorkspaceDir returns the default workspace directory (~/.tars/workspace).

func FixedConfigPath added in v0.15.2 

func FixedConfigPath() string

FixedConfigPath returns the fixed config file path (~/.tars/config/config.yaml). This path is not user-overridable; all commands use it.

func FormatLegacyKeyWarnings added in v0.26.1 

func FormatLegacyKeyWarnings(warnings []LegacyKeyWarning) string

FormatLegacyKeyWarnings returns a human-readable summary of legacy key warnings suitable for CLI output.

func LoadRaw added in v0.14.0 

func LoadRaw(path string) ([]byte, error)

LoadRaw reads the raw content of the config file at the given path.

func MCPServerEnabled added in v0.11.0 

func MCPServerEnabled(server MCPServer) bool

func MCPServerIsRemote added in v0.11.0 

func MCPServerIsRemote(server MCPServer) bool

func NeedsSetup added in v0.31.129 

func NeedsSetup(cfg Config) bool

NeedsSetup returns true when the loaded config cannot start the LLM router. It is the single source of truth shared between the healthz handler, the setup status handler, and the boot path (see Phase 2).

Conditions (any one triggers needs_setup=true):

  • cfg.LLMProviders is empty
  • cfg.LLMTiers is missing any of: heavy, standard, light
  • any of those three tier bindings has empty (or whitespace-only) provider or model

This function does NOT validate that referenced provider aliases exist in cfg.LLMProviders — that check belongs to ResolveAllLLMTiers at boot time. Only structural completeness is checked here.

func PatchYAML added in v0.14.0 

func PatchYAML(path string, updates map[string]any) error

PatchYAML reads the YAML file at path, merges the given key-value updates, and writes the result back. Unknown keys are ignored.

func ResolveAllLLMTiers added in v0.25.0 

func ResolveAllLLMTiers(cfg *Config) (map[string]ResolvedLLMTier, error)

ResolveAllLLMTiers resolves every tier present in cfg.LLMTiers and returns them keyed by normalized tier name. It is the single entry point used by buildLLMRouter — callers should not iterate cfg.LLMTiers directly.

Returns the first resolution error encountered (fail loud).

Note: this function does NOT enforce that heavy/standard/light are all present. That check lives in the router construction path (llm.NewRouter) so that the error message can reference the tier interface rather than the config schema.

func ResolveConfigPath 

func ResolveConfigPath(raw string) string

func SaveRaw added in v0.14.0 

func SaveRaw(path string, content []byte) error

SaveRaw writes raw content to the config file at the given path. It validates that the content is valid YAML before writing.

func TarsHomeDir added in v0.15.2 

func TarsHomeDir() string

TarsHomeDir returns the base directory for TARS data (~/.tars).

Types

type APIConfig added in v0.6.0 

type APIConfig struct {
	APIAuthMode               string
	DashboardAuthMode         string
	APIAuthToken              string
	APIUserToken              string
	APIAdminToken             string
	APIAllowInsecureLocalAuth bool
	APIMaxInflightChat        int
	APIMaxInflightAgentRuns   int
}

type AgentRuntimeAgent added in v0.31.5 

type AgentRuntimeAgent struct {
	Name           string            `json:"name"`
	Description    string            `json:"description,omitempty"`
	Command        string            `json:"command"`
	Args           []string          `json:"args,omitempty"`
	Env            map[string]string `json:"env,omitempty"`
	WorkingDir     string            `json:"working_dir,omitempty"`
	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
	Enabled        bool              `json:"enabled,omitempty"`
}

type AgentRuntimeConfig added in v0.31.5 

type AgentRuntimeConfig struct {
	AgentRuntimeEnabled                       bool
	AgentRuntimeDefaultAgent                  string
	AgentRuntimeAgents                        []AgentRuntimeAgent
	AgentRuntimeTaskOverride                  AgentRuntimeTaskOverrideConfig
	AgentRuntimeAgentsWatch                   bool
	AgentRuntimeAgentsWatchDebounceMS         int
	AgentRuntimePersistenceEnabled            bool
	AgentRuntimeRunsPersistenceEnabled        bool
	AgentRuntimeChannelsPersistenceEnabled    bool
	AgentRuntimeRunsMaxRecords                int
	AgentRuntimeChannelsMaxMessagesPerChannel int
	AgentRuntimeSubagentsMaxThreads           int
	AgentRuntimeSubagentsMaxDepth             int
	AgentRuntimeConsensusEnabled              bool
	AgentRuntimeConsensusMaxFanout            int
	AgentRuntimeConsensusBudgetTokens         int
	AgentRuntimeConsensusBudgetUSD            float64
	AgentRuntimeConsensusTimeoutSeconds       int
	AgentRuntimeConsensusAllowedAliases       []string
	AgentRuntimeConsensusConcurrentRuns       int
	AgentRuntimePersistenceDir                string
	AgentRuntimeRestoreOnStartup              bool
	AgentRuntimeReportSummaryEnabled          bool
	AgentRuntimeArchiveEnabled                bool
	AgentRuntimeArchiveDir                    string
	AgentRuntimeArchiveRetentionDays          int
	AgentRuntimeArchiveMaxFileBytes           int
}

type AgentRuntimeTaskOverrideConfig added in v0.31.5 

type AgentRuntimeTaskOverrideConfig struct {
	Enabled        bool     `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	AllowedAliases []string `json:"allowed_aliases,omitempty" yaml:"allowed_aliases,omitempty"`
	AllowedModels  []string `json:"allowed_models,omitempty" yaml:"allowed_models,omitempty"`
}

type AssistantConfig added in v0.6.0 

type AssistantConfig struct {
	AssistantEnabled    bool
	AssistantHotkey     string
	AssistantWhisperBin string
	AssistantFFmpegBin  string
	AssistantTTSBin     string
}

type AutomationConfig added in v0.6.0 

type AutomationConfig struct {
	AgentMaxIterations  int
	CronRunHistoryLimit int
	NotifyCommand       string
	NotifyWhenNoClients bool
	ScheduleTimezone    string

	// Pulse is the system-surface watchdog. All fields default to
	// conservative values so it runs silently until signals appear.
	PulseEnabled                  bool
	PulseInterval                 string // duration string, e.g. "1m"
	PulseTimeout                  string // duration string, e.g. "2m"
	PulseActiveHours              string
	PulseTimezone                 string
	PulseMinSeverity              string
	PulseAllowedAutofixes         []string
	PulseNotifyTelegram           bool
	PulseNotifySessionEvents      bool
	PulseCronFailureThreshold     int
	PulseStuckRunMinutes          int
	PulseDiskWarnPercent          float64
	PulseDiskCriticalPercent      float64
	PulseDeliveryFailureThreshold int
	PulseDeliveryFailureWindow    string // duration string, e.g. "10m"
	// PulseReflectionFailureThreshold is the number of consecutive
	// reflection run failures that causes pulse to emit a reflection-
	// failure signal.
	PulseReflectionFailureThreshold int

	// Reflection is the nightly batch runner (memory + KB cleanup).
	ReflectionEnabled             bool
	ReflectionSleepWindow         string // "HH:MM-HH:MM" in ReflectionTimezone
	ReflectionTimezone            string
	ReflectionTickInterval        string // duration string, e.g. "5m"
	ReflectionEmptySessionAge     string // duration string, e.g. "24h"
	ReflectionMemoryLookbackHours int
	ReflectionMaxTurnsPerSession  int
}

type ChannelConfig added in v0.6.0 

type ChannelConfig struct {
	ChannelsLocalEnabled           bool
	ChannelsWebhookEnabled         bool
	ChannelsTelegramEnabled        bool
	ChannelsTelegramDMPolicy       string
	ChannelsTelegramPollingEnabled bool
	TelegramBotToken               string
}

type CompactionConfig added in v0.25.0 

type CompactionConfig struct {
	CompactionTriggerTokens      int
	CompactionKeepRecentTokens   int
	CompactionKeepRecentFraction float64
	CompactionLLMMode            string
	CompactionLLMTimeoutSeconds  int
}

type CompanionConfig added in v0.32.71 

type CompanionConfig struct {
	Enabled bool
	// contains filtered or unexported fields
}

type Config 

type Config struct {
	RuntimeConfig
	APIConfig
	RemoteAccessConfig
	LLMConfig
	MemoryConfig
	UsageConfig
	AutomationConfig
	AssistantConfig
	CompactionConfig
	ToolConfig
	AgentRuntimeConfig
	ChannelConfig
	Companion  CompanionConfig
	Embodiment EmbodimentConfig
	ExtensionConfig
}

Config holds top-level runtime settings grouped by concern.

func Default 

func Default() Config

Default returns safe baseline settings for local execution.

func Load 

func Load(path string) (Config, error)

Load resolves runtime settings with the following precedence: defaults < YAML file < environment variables.

func LoadFile added in v0.32.0 

func LoadFile(path string) (Config, error)

LoadFile resolves settings from defaults + YAML only, intentionally skipping environment overrides. Use this for editing the config file itself; Load is still the runtime path where env vars have highest precedence.

type EmbodimentConfig added in v0.32.68 

type EmbodimentConfig struct {
	Enabled   bool
	Providers []EmbodimentProviderConfig
}

type EmbodimentProviderConfig added in v0.32.68 

type EmbodimentProviderConfig struct {
	Name                  string   `json:"name" yaml:"name"`
	Enabled               bool     `json:"enabled" yaml:"enabled"`
	Transport             string   `json:"transport" yaml:"transport"`
	Endpoint              string   `json:"endpoint" yaml:"endpoint"`
	Capabilities          []string `json:"capabilities" yaml:"capabilities"`
	SessionID             string   `json:"session_id" yaml:"session_id"`
	Agent                 string   `json:"agent" yaml:"agent"`
	OwnerOnlyDirective    bool     `json:"owner_only_directive" yaml:"owner_only_directive"`
	SalienceMinSoundLevel float64  `json:"salience_min_sound_level" yaml:"salience_min_sound_level"`
	MinTriggerInterval    string   `json:"min_trigger_interval" yaml:"min_trigger_interval"`
	MaxTriggersPerHour    int      `json:"max_triggers_per_hour" yaml:"max_triggers_per_hour"`
	TriggerObservations   bool     `json:"trigger_observations" yaml:"trigger_observations"`
}

func NormalizeEmbodimentProviderForRuntime added in v0.32.68 

func NormalizeEmbodimentProviderForRuntime(provider EmbodimentProviderConfig) EmbodimentProviderConfig

type EnvOverrideMeta added in v0.32.0 

type EnvOverrideMeta struct {
	EnvKey string `json:"env_key"`
}

type ExtensionConfig added in v0.6.0 

type ExtensionConfig struct {
	SkillsEnabled          bool
	SkillsWatch            bool
	SkillsWatchDebounceMS  int
	SkillsExtraDirs        []string
	SkillsBundledDir       string
	PluginsEnabled         bool
	PluginsWatch           bool
	PluginsWatchDebounceMS int
	PluginsExtraDirs       []string
	PluginsBundledDir      string
	PluginsAllowMCPServers bool
	MCPServers             []MCPServer
	MCPCommandAllowlist    []string
}

type FieldMeta added in v0.14.0 

type FieldMeta struct {
	Key             string   `json:"key"`
	Path            string   `json:"path"`
	Section         string   `json:"section"`
	Type            string   `json:"type"` // "string", "int", "float", "bool", "json"
	Label           string   `json:"label"`
	Description     string   `json:"description"`
	Impact          []string `json:"impact,omitempty"`
	DefaultValue    any      `json:"default_value,omitempty"`
	RequiresRestart bool     `json:"requires_restart"`
	Sensitive       bool     `json:"sensitive,omitempty"`
	Options         []string `json:"options,omitempty"`
}

FieldMeta describes a single configuration field for UI rendering.

func Schema added in v0.14.0 

func Schema() []FieldMeta

Schema returns metadata for all configuration fields, grouped for UI display.

type LLMConfig added in v0.6.0 

type LLMConfig struct {
	// LLMProviders is the named provider pool. Each entry describes
	// "where to call + how to authenticate" — credentials, base URL,
	// auth mode. It does NOT carry a model; models are bound at the
	// tier level via LLMTierBinding. One provider can therefore serve
	// multiple models by being referenced from multiple tiers.
	LLMProviders map[string]LLMProviderSettings

	// LLMTiers binds each tier name (typically "heavy"/"standard"/"light")
	// to a provider alias (key in LLMProviders) + a concrete model + the
	// optional per-call knobs. A tier's binding.Provider must exist in
	// LLMProviders or resolution errors.
	LLMTiers map[string]LLMTierBinding

	// LLMDefaultTier is the tier used when a role has no explicit
	// mapping in LLMRoleDefaults. Must be a key in LLMTiers.
	LLMDefaultTier string

	// LLMRoleDefaults maps a canonical role name (e.g. "chat_main",
	// "pulse_decider") to a tier name ("heavy"|"standard"|"light"). Roles
	// absent from the map fall back to LLMDefaultTier. Role names are
	// validated at router build time via llm.ParseRole — this package
	// does not import internal/llm.
	LLMRoleDefaults map[string]string

	// ClaudeCodeCLIPermissionMode selects the value passed to
	// `claude -p --permission-mode` when the active tier uses the
	// claude-code-cli provider. Allowed values: "auto" (default),
	// "acceptEdits", "plan", "bypassPermissions". Empty/unknown values
	// degrade to "auto" inside the provider. Other providers ignore this.
	ClaudeCodeCLIPermissionMode string
}

LLMConfig holds the named provider pool + tier bindings that together describe every LLM endpoint TARS will call. See docs/plans/llm-provider-pool.md for the schema rationale.

Legacy flat fields (LLMProvider, LLMAuthMode, ..., LLMTierHeavy/Standard/ Light) were removed in the cutover commit — user configs must migrate to llm_providers + llm_tiers.

type LLMProviderSettings added in v0.25.0 

type LLMProviderSettings struct {
	Kind     string `json:"kind"      yaml:"kind"`
	AuthMode string `json:"auth_mode" yaml:"auth_mode"`
	BaseURL  string `json:"base_url"  yaml:"base_url"`
	APIKey   string `json:"api_key"   yaml:"api_key"`
}

LLMProviderSettings is one entry in the named provider pool. It holds "where to call + how to authenticate" but NOT "what model to call". Models are bound at the tier level (LLMTierBinding.Model) so that one provider can serve multiple models.

Kind identifies the provider type ("anthropic", "openai", "openai-codex", "gemini", "gemini-native", "kimi", "claude-code-cli") and maps to the value passed to llm.NewProvider.Provider. The config package does not validate Kind against a closed list — llm.NewProvider returns a clear error for unknown kinds, keeping the config package free of an internal/llm import.

OAuth token source (formerly the user-facing oauth_provider field) is derived internally from Kind via llmdefaults.OAuthProvider — there is no per-config override. ServiceTier is set per tier binding only (LLMTierBinding.ServiceTier) — there is no provider-level default.

type LLMTierBinding added in v0.25.0 

type LLMTierBinding struct {
	Provider        string `json:"provider"         yaml:"provider"`
	Model           string `json:"model"            yaml:"model"`
	ReasoningEffort string `json:"reasoning_effort" yaml:"reasoning_effort"`
	ThinkingBudget  int    `json:"thinking_budget"  yaml:"thinking_budget"`
	ServiceTier     string `json:"service_tier"     yaml:"service_tier"`
}

LLMTierBinding binds a tier to a provider alias + concrete model + per-call knobs. Provider must be a key in cfg.LLMProviders — the resolver rejects unknown aliases with a loud error.

ReasoningEffort, ThinkingBudget, and ServiceTier are per-tier knobs; they are not configurable at the provider level.

type LegacyKeyWarning added in v0.26.1 

type LegacyKeyWarning struct {
	Key       string
	Migration string
}

LegacyKeyWarning describes a removed config key and its migration path.

func DetectLegacyKeys added in v0.26.1 

func DetectLegacyKeys(path string) []LegacyKeyWarning

DetectLegacyKeys reads a YAML config file and returns warnings for any removed keys found. Returns nil if the file does not exist or contains no legacy keys.

type MCPServer 

type MCPServer struct {
	Name          string            `json:"name"`
	Command       string            `json:"command,omitempty"`
	Args          []string          `json:"args,omitempty"`
	Env           map[string]string `json:"env,omitempty"`
	Transport     string            `json:"transport,omitempty"`
	URL           string            `json:"url,omitempty"`
	Headers       map[string]string `json:"headers,omitempty"`
	AuthMode      string            `json:"auth_mode,omitempty"`
	AuthTokenEnv  string            `json:"auth_token_env,omitempty"`
	OAuthProvider string            `json:"oauth_provider,omitempty"`
	Source        string            `json:"source,omitempty"`
}

func NormalizeMCPServer added in v0.11.0 

func NormalizeMCPServer(server MCPServer) MCPServer

type MemoryConfig added in v0.6.0 

type MemoryConfig struct {
	MemoryBackend         string
	MemorySemanticEnabled bool
	MemoryEmbedProvider   string
	MemoryEmbedBaseURL    string
	MemoryEmbedAPIKey     string
	MemoryEmbedModel      string
	MemoryEmbedDimensions int
}

type RemoteAccessConfig added in v0.32.0 

type RemoteAccessConfig struct {
	RemoteAccessTailscaleServeEnabled   bool
	RemoteAccessTailscaleServeHTTPSPort int
}

type ResolvedLLMTier added in v0.25.0 

type ResolvedLLMTier struct {
	Tier string

	// From the referenced provider pool entry
	Kind          string
	AuthMode      string
	OAuthProvider string // derived from Kind, see llmdefaults.OAuthProvider
	BaseURL       string
	APIKey        string

	// From the tier binding
	Model           string
	ReasoningEffort string
	ThinkingBudget  int
	ServiceTier     string

	// Provenance — alias of the provider pool entry that served this tier
	ProviderAlias string
}

ResolvedLLMTier is the flat, final view of one tier's effective LLM configuration after merging the named provider pool entry and the tier binding. The router builder consumes this struct directly — callers never read cfg.LLMProviders or cfg.LLMTiers in isolation.

ProviderAlias records which pool entry served this tier so that tars doctor and startup logs can show provenance (e.g. "heavy → codex / gpt-5.4").

OAuthProvider is derived from Kind via llmdefaults.OAuthProvider when AuthMode is "oauth"; it is not user-configurable. ServiceTier comes from the tier binding only — there is no provider-level fallback.

func ResolveLLMTier added in v0.25.0 

func ResolveLLMTier(cfg *Config, tier string) (ResolvedLLMTier, error)

ResolveLLMTier returns the effective settings for the given tier. The tier name is normalized (lowercased, trimmed) before lookup.

Errors (all loud — no silent fallback):

  • cfg is nil
  • tier is empty
  • cfg.LLMTiers[tier] is missing
  • binding.Provider is empty
  • cfg.LLMProviders[binding.Provider] is missing
  • resolved Kind is empty
  • binding.Model is empty

Kind is normalized to lowercase; other string fields are trimmed. Kind value is NOT validated against a closed list — llm.NewProvider rejects unknown kinds with a clear error at router build time, and the config package must stay free of an internal/llm import.

type RuntimeConfig added in v0.6.0 

type RuntimeConfig struct {
	WorkspaceDir           string
	SessionDefaultID       string
	SessionTelegramScope   string
	StyleDirectnessDefault int
	StyleHumorDefault      int
	StyleCautionDefault    int
	StyleAutonomyDefault   int
	LogLevel               string
	LogFile                string
	LogRotateMaxSizeMB     int
	LogRotateMaxDays       int
	LogRotateMaxBackups    int
	// PlanClarifyMode controls whether the LLM asks clarifying questions
	// before drafting a plan. One of "smart" (default), "auto", or "ask".
	// See internal/prompt/builder.go for behavior per mode.
	PlanClarifyMode string
}

type ToolConfig added in v0.6.0 

type ToolConfig struct {
	ToolsWebSearchEnabled             bool
	ToolsWebFetchEnabled              bool
	ToolsDefaultSet                   string
	ToolsAllowHighRiskUser            bool
	ToolsWebSearchAPIKey              string
	ToolsWebSearchProvider            string
	ToolsWebSearchPerplexityAPIKey    string
	ToolsWebSearchPerplexityModel     string
	ToolsWebSearchPerplexityBaseURL   string
	ToolsWebSearchCacheTTLSeconds     int
	ToolsWebFetchPrivateHostAllowlist []string
	ToolsWebFetchAllowPrivateHosts    bool
	ToolsApplyPatchEnabled            bool
	ToolsMessageEnabled               bool
	ToolsAgentRuntimeEnabled          bool
	// ToolsExecMaxTimeoutMS caps the per-call timeout the LLM can pass to
	// the exec tool. Long-running commands (`make build`, `gh pr checks
	// --watch`, `npm install`) need more than the historical 30s default;
	// raise this to give them headroom while still preventing infinite
	// hangs. 0 falls back to defaults.go.
	ToolsExecMaxTimeoutMS int
	// ToolsProcessMaxTimeoutMS caps background (process-managed)
	// commands started via `exec background:true`, plus the per-call
	// timeout for the `process` tool's `wait` action. Independent of the
	// foreground cap so watchers like `gh pr checks --watch` can run for
	// tens of minutes. 0 falls back to defaults.go.
	ToolsProcessMaxTimeoutMS int
}

type UsageConfig added in v0.6.0 

type UsageConfig struct {
	UsageLimitDailyUSD    float64
	UsageLimitWeeklyUSD   float64
	UsageLimitMonthlyUSD  float64
	UsageDailyTokenBudget int
	UsageLimitMode        string
	UsagePriceOverrides   map[string]UsagePrice
}

type UsagePrice 

type UsagePrice struct {
	InputPer1MUSD      float64 `json:"input_per_1m_usd"`
	OutputPer1MUSD     float64 `json:"output_per_1m_usd"`
	CacheReadPer1MUSD  float64 `json:"cache_read_per_1m_usd,omitempty"`
	CacheWritePer1MUSD float64 `json:"cache_write_per_1m_usd,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.