settings

package
v0.17.4 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package settings is the one reader for <configDir>/config.json: Field (typed key), FieldInto (pointer target), FieldStrict (unreadable kept apart from absent, for a caller gating a destructive action) and Read (one parsed generation for several keys), all through one freshness-checked cache capped at maxBytes.

There is no exported raw-bytes reader: the cache's slice is shared by every caller, so an exported accessor would let any caller corrupt every other's settings. For the same reason a Document exposes decoders only, never the parsed map the cache shares.

Index

Constants

View Source
const (
	SpecPlanningOff   = "off"
	SpecPlanningQuick = "quick"
)

The values of KeySpecPlanning: KAS's own specPlan workflow vocabulary, plus off.

View Source
const (
	FeatureFollowKiro = ""
	FeatureOn         = "on"
	FeatureOff        = "off"
)

The three values of a setting that follows kiro-cli until the user chooses (KeyWorkValidation, KeyCloudFormationSafety, KeyAutoRouting, KeyAutoDelegation). FeatureFollowKiro sends nothing, so KAS's own experiment decides.

View Source
const (
	KeyAgentIgnoreFiles = "agent_ignore_files"

	// KeyAdditionalDirectories lists the directories beyond the workspace that agents may read
	// and write (AgentDirs owns which entries are granted). Default empty.
	KeyAdditionalDirectories = "additional_directories"

	// KeyChatRetentionDays is three states: -1 keeps every chat, 0 deletes at close, N keeps N
	// days. A dropped key falls back to the 7-day default, hence PATCH merges, never replaces.
	KeyChatRetentionDays = "chat_retention_days"

	KeyDebugLogs            = "debug_logs"
	KeyLastModel            = "last_model"
	KeyNotificationsEnabled = "notifications_enabled"

	// KeyLastEffortByModel maps model id to the effort level last picked under it: the preference
	// a chat holding no level for that model takes, then pinned onto Chat.Effort, which owns it
	// from there; both readers (effortSeedFor, getLastEffortFor) look up the chat's model.
	KeyLastEffortByModel = "last_effort_by_model"

	// KeyLastMergeMethod is the PR merge method last picked (forge spelling), the merge dialog's
	// next default when the repository offers it. Empty means none picked.
	KeyLastMergeMethod = "last_merge_method"

	KeyNotifyAgentFinished = "notify_agent_finished"
	KeyNotifyPRStatus      = "notify_pr_status"
	KeyNotifyRunOutcome    = "notify_run_outcome"
	KeySupervisedDefault   = "supervised_default"

	// KeySecurityProfile is the security posture every session opens with (a policyfile profile
	// id sent as policy presets). Global: KAS cannot change a live session's policy. An unset or
	// unknown value resolves to policyfile.DefaultProfile, never to Custom (no presets).
	KeySecurityProfile = "security_profile"

	// KeyScheduledAutoApprove lets a SCHEDULED run's tool requests be approved instead of refused
	// after the unattended budget. Off by default, and its own switch: unattended consent must be
	// chosen, not inherited.
	KeyScheduledAutoApprove = "scheduled_auto_approve"

	// KeyKnowledgeEnabled reaches the agent per spawn under _meta.kiro.settings; it defaults TRUE.
	KeyKnowledgeEnabled  = "knowledge_enabled"
	KeyGuardPayloadLinks = "guard_payload_links"

	// KeyContentCollectionEnabled lets model requests be used by AWS for service
	// improvement. Default off. internal/agent asserts it on the engine at each spawn
	// and pushes a change live, because KAS holds it per process and persists none
	// of it; an organization's lock overrides it.
	KeyContentCollectionEnabled = "content_collection_enabled"

	// KeyMemoryMode is the Memory dropdown (memory.go's Memory* values), resolved per session door by
	// MemoryPreferenceFor. KAS freezes the mode per session; the reflection half is re-sent on
	// session/load.
	KeyMemoryMode = "memory_mode"

	// KeyMCPWaitForReady makes KAS hold each prompt until every enabled MCP server
	// has settled. It reaches the agent through the rendered KAS MCP file, not the
	// spawn, so a flip is live at the next prompt of every open chat. Default off.
	KeyMCPWaitForReady = "mcp_wait_for_ready" //nolint:gosec // G101: a settings key ("MCPWait" reads as "pw"), not a credential

	// KeyAutoCompactionEnabled and KeyAutoCompactPct are the chat compaction
	// policy internal/agent's autoCompactionPolicy reads. The door value they
	// imply is frozen by KAS per session, so a flip reaches a chat at its next
	// session/load; the pct itself acts at once because marotte drives it.
	KeyAutoCompactionEnabled = "auto_compaction_enabled"
	KeyAutoCompactPct        = "auto_compact_pct"

	// The Agent capabilities that ride KAS's doors, resolved per session door by
	// internal/agent's agentFeatures (values in agent_features.go).
	// KeyWorkValidation, KeyCloudFormationSafety, KeyAutoRouting and
	// KeyAutoDelegation are three-state: empty sends nothing, so kiro-cli's own
	// experiment decides. KeyModelFallback on sends KAS's refusal and availability
	// fallback flags; off sends nothing, leaving kiro-cli's default (off) in force.
	KeySpecPlanning         = "spec_planning"
	KeySpecPlanningAskFirst = "spec_planning_ask_first"
	KeySteeringReminders    = "steering_reminders_enabled"
	KeyWorkflowsEnabled     = "workflows_enabled"
	KeyWorkValidation       = "work_validation"
	KeyCloudFormationSafety = "cloudformation_safety_check"
	KeyAutoRouting          = "auto_routing"
	KeyAutoDelegation       = "auto_delegation"
	KeyModelFallback        = "model_fallback_enabled"

	// KeyOutputStyle, a KAS output style id, rides each chat prompt as _meta.kiro.outputStyle.
	// KeyTerminalCommandTimeoutMs is the shell tool's default timeout (0 = KAS's
	// 120 s), sent at initialize and pushed live to the engine.
	KeyOutputStyle              = "output_style"
	KeyTerminalCommandTimeoutMs = "terminal_command_timeout_ms"

	// KeyEngineHeapMiB is the agent engine's JavaScript heap limit in MiB: 0 (the default) adds no flag and leaves
	// kiro-cli's own, otherwise ValidEngineHeapMiB's range. It applies when the engine restarts.
	KeyEngineHeapMiB = "engine_heap_mib"

	// KeyHighThroughput starts the agent server on kiro-cli's bundled Node.js with internal/kasnode's flags, default
	// ON (defaultHighThroughput); off is kiro-cli's stock engine. It applies when the engine restarts.
	KeyHighThroughput = "high_throughput_optimizations"

	// KeyTheme is "dark" | "light" | "system" ("system" is a stored choice; absent resolves to
	// system at the client). The browser's localStorage copy is a pre-paint hint this value
	// overwrites. KeyFBPath is the file browser's last directory, per workspace.
	KeyTheme  = "theme"
	KeyFBPath = "fb_path"

	// KeySettingsEpoch and KeySettingsRevision stamp the document's version: Update owns both, and
	// a PATCH may set neither.
	KeySettingsEpoch    = "settings_epoch"
	KeySettingsRevision = "settings_revision"
)

Settings key names. Reference these instead of bare string literals.

View Source
const (
	DefaultAutoCompactionEnabled = true
	DefaultAutoCompactPct        = 80
)

DefaultAutoCompactPct is the point at which marotte adds nothing to KAS's own 80/95, which is why an invalid stored value reads as it.

View Source
const (
	DefaultNotifyAgentFinished = true
	DefaultNotifyPRStatus      = false
	DefaultNotifyRunOutcome    = true
)

DefaultNotifyPRStatus is OFF while its siblings are ON: a PR's CI verdict is already on the forge, where the other two report unobserved work.

View Source
const AgentIgnoreFloor = ".kiroignore"

AgentIgnoreFloor is sent to KAS whatever the user's list holds, so a root `.kiroignore` is always enforced; AgentIgnoreList puts it first.

View Source
const DefaultChatRetentionDays = 7

DefaultChatRetentionDays is the default for chat_retention_days: -1 forever, 0 delete on close (History hidden), N purge after N days. The purge treats <= 0 as no purge. GET /api/settings resolves it, so the client carries no copy.

View Source
const DefaultContentCollectionEnabled = false

DefaultContentCollectionEnabled is the content-collection switch's default: off, so nothing is offered for service improvement until the user opts in.

View Source
const DefaultMemoryMode = memoryOff

DefaultMemoryMode is kiro-cli's shipped default: its TUI sends mode disabled unless KIRO_INTERNAL=1, and KAS's own fallback is {disabled, reflection: false} from 2.31.0.

View Source
const (
	DefaultWorkflowsEnabled = true
)

Defaults for the agent-capability settings, matching kiro-cli's own except DefaultWorkflowsEnabled, on by the user's choice (the TUI's is off).

View Source
const Filename = filename

Filename is the basename of marotte's config file (not kiro-cli's cli.json).

View Source
const OutputStyleDefault = "default"

OutputStyleDefault is KAS's default output style id, the one prompts never send.

Variables

View Source
var ErrUnparseable = errors.New("settings: config.json does not parse")

ErrUnparseable marks a Read whose generation was read but does not parse as a JSON object; an oversized file is truncated at maxBytes and lands here too.

View Source
var ErrUnreadable = errors.New("settings: stored document unreadable")

ErrUnreadable marks the Update failure about the STORED document: config.json exists and could not be read or parsed, so the remedy is the file itself.

KnownKeys is the set of marotte-managed config.json keys; PATCH warns about others but does not reject them. kiro-cli's own settings (cli.json) are not in it. There is no model_effort key: effort is per chat (Chat.Effort), seeded by KeyLastEffortByModel.

Functions

func AgentIgnoreList

func AgentIgnoreList(entries []string) []string

AgentIgnoreList is the list marotte sends KAS: AgentIgnoreFloor first, then the user's entries in order, deduped, with refused entries dropped (config.json is hand-editable).

func Announce added in v0.15.0

func Announce(ctx context.Context, configDir string, publish func(context.Context, marotte.ServerEvent))

Announce publishes a settings_updated event stamped with the stored document's version, for a change to the effective settings that writes nothing, such as a kiro-cli default. It holds Update's lock, so no write's event leaves between its read and its publish. With no readable document the stamp is 0, as a settings read answers then.

func DebugLogs added in v0.12.16

func DebugLogs(ctx context.Context, configDir string) bool

DebugLogs reports whether the process logs at debug level; anything but a readable true is info, so a broken settings file never drops into debug.

func DebugLogsIn added in v0.17.0

func DebugLogsIn(d Document) bool

DebugLogsIn is DebugLogs over d: anything but a stored true is info.

func DefaultAgentIgnoreFiles

func DefaultAgentIgnoreFiles() []string

DefaultAgentIgnoreFiles is the default for agent_ignore_files: EMPTY (other Kiro clients apply no workspace ignore file; AgentIgnoreFloor is sent regardless). Non-nil, so it marshals [].

func EffectiveDefaults

func EffectiveDefaults() marotte.EffectiveSettings

EffectiveDefaults is the ONE statement of every client-rendered preference's value when config.json is SILENT. It is not a consumer's answer for an UNREADABLE file, which differs per consumer (composition's chatRetention purges nothing then), so the two must not merge.

func EffectiveFrom

func EffectiveFrom(stored map[string]json.RawMessage) (effective marotte.EffectiveSettings, rejected []string)

EffectiveFrom resolves the stored document into the client's view: EffectiveDefaults with every stored value that FITS ITS TYPE overlaid, plus the keys that did not fit. Value validity is the client's (theme "purple" passes). A nil or empty map yields the defaults.

func Field

func Field[T any](ctx context.Context, configDir, key string) (T, bool)

Field reads config.json and decodes the named key into T, returning the zero value and false when the file is missing, the key is absent, parsing fails (logged at Warn naming the key) or ctx has ended (not logged). It wraps FieldStrict for callers whose fallback is a display default.

func FieldInto

func FieldInto(ctx context.Context, configDir, key string, out any) bool

FieldInto is the pointer-target variant of Field: it decodes the named key into out and reports success; like Field, it logs no failure that is ctx's.

func FieldStrict

func FieldStrict[T any](ctx context.Context, configDir, key string) (value T, found bool, err error)

FieldStrict is Field with unreadability kept apart from absence: found reports the key was PRESENT and decoded; err reports config.json exists and could not be read or parsed.

func HighThroughputIn added in v0.17.0

func HighThroughputIn(d Document) bool

HighThroughputIn reports whether the next engine starts with the high throughput launcher; an absent or invalid value is the default.

func Lookup added in v0.17.0

func Lookup[T any](d Document, key string) (value T, found bool, err error)

Lookup decodes key from d: found reports the key was present and decoded; err wraps errKeyParse for a present key that does not decode into T.

func LookupOr added in v0.17.0

func LookupOr[T any](d Document, key string, def T) T

LookupOr is Lookup with a default: an absent key reads as def, and a key that does not decode reads as def and logs "settings: parse <key>" at Warn.

func MCPWaitForReady added in v0.12.16

func MCPWaitForReady(ctx context.Context, configDir string) (on, readable bool)

MCPWaitForReady reports whether KAS's rendered MCP file carries waitForReady; anything but a stored true is off. readable is false over an unreadable config.json, where off is no answer.

func MCPWaitForReadyIn added in v0.17.0

func MCPWaitForReadyIn(d Document) bool

MCPWaitForReadyIn is MCPWaitForReady over d: anything but a stored true is off.

func MemoryPreferenceFor added in v0.12.0

func MemoryPreferenceFor(mode string) marotte.MemoryPreference

MemoryPreferenceFor maps a dropdown value onto KAS's `settings.memory` fields. An unrecognised value takes DefaultMemoryMode.

func RetentionEnabled

func RetentionEnabled(ctx context.Context, configDir string) bool

RetentionEnabled reports whether chat retention keeps a closed chat's record. It FAILS TOWARD KEEPING: unreadable answers ON, absent takes the default, only 0 answers OFF. It must never share a reader with the purge, whose 0-sentinel's safe direction is the inverse.

func ThreeStateChoice added in v0.13.0

func ThreeStateChoice(e *marotte.EffectiveSettings, key string) (string, bool)

ThreeStateChoice answers a follow-kiro-cli setting's effective choice by key, false for a key that is not one.

func Update

func Update(ctx context.Context, configDir string, fn func(doc map[string]json.RawMessage) error, publish func(context.Context, marotte.ServerEvent)) (map[string]json.RawMessage, error)

Update applies fn to the stored document and writes it back atomically under ONE per- configDir lock across read, merge and write, so concurrent writers drop no key. An unreadable document refuses (ErrUnreadable): merging over an empty map would destroy every key fn does not name. An absent file is ordinary. Each write stamps the document with the next version (cache.next), whatever fn put there, and refuses when none is left; a refusal writes nothing. publish, when not nil, gets the write's settings_updated event before the lock is released, so events leave in version order; by then the map fn edited is the document written, stamped. That map is returned.

func ValidAgentIgnoreEntry

func ValidAgentIgnoreEntry(entry string) error

ValidAgentIgnoreEntry mirrors KAS's `Bvt` rule for rule: non-empty, already trimmed, not ".", no path separator, no "..", no glob metacharacter. An entry KAS refuses is one it SKIPS, so accepting it would show an unenforced name as enforced.

func ValidAutoCompactPct added in v0.12.0

func ValidAutoCompactPct(pct int) bool

ValidAutoCompactPct reports whether pct is a value the slider can produce: 50..90 in steps of 5.

func ValidFeatureChoice added in v0.12.0

func ValidFeatureChoice(v string) bool

ValidFeatureChoice reports whether v is a follow-kiro-cli choice.

func ValidOutputStyle added in v0.12.0

func ValidOutputStyle(v string) bool

ValidOutputStyle reports whether v has the shape of an output style id: 1 to 64 bytes of [a-z0-9_-]. The vocabulary is KAS's (GET /api/config-template output_styles), so membership is not checked: KAS reads an id it does not serve as default.

func ValidSpecPlanning added in v0.12.0

func ValidSpecPlanning(v string) bool

ValidSpecPlanning reports whether v is one of the three spec-planning values.

func ValidTerminalCommandTimeoutMs added in v0.12.0

func ValidTerminalCommandTimeoutMs(ms int) bool

ValidTerminalCommandTimeoutMs reports whether ms is unset (0) or inside KAS's bounds; KAS ignores the whole terminal object for a value outside them.

func ValidateAgentPatch added in v0.12.0

func ValidateAgentPatch(patch map[string]json.RawMessage) error

ValidateAgentPatch refuses a patch whose agent-capability keys carry a value the UI cannot produce. A patch carrying none of them passes.

func ValidateCompactionPatch added in v0.12.0

func ValidateCompactionPatch(patch map[string]json.RawMessage) error

ValidateCompactionPatch refuses a patch whose compaction keys the UI cannot produce: auto_compaction_enabled must be a bool and auto_compact_pct an integer in 50..90 in steps of 5. A patch that carries neither key passes.

func WarnUnknownKeys

func WarnUnknownKeys(keys []string, source string) []string

WarnUnknownKeys logs a warning for each key in keys outside KnownKeys and returns them sorted (nil when all are known). source identifies the call site.

Types

type AgentDirs added in v0.15.0

type AgentDirs struct {
	Workspace string
	Config    string
}

AgentDirs names the two trees that decide which additional directories agents may reach: Workspace, which they reach already, and Config, marotte's config directory, which holds its secrets and which no additional directory may equal, sit inside or contain.

func (AgentDirs) Assess added in v0.15.0

func (d AgentDirs) Assess(entries []string) (granted []string, refused map[string]string)

Assess splits entries into the ones granted today, in order and deduplicated, and the reason for each other one, keyed by the entry. An entry is granted when checkEntry accepts it and it neither lies inside nor contains an entry granted before it, so granted entries never overlap. refused is never nil. A stored entry is assessed again on every read: config.json is hand-editable, and a directory can change after it was added.

func (AgentDirs) Granted added in v0.15.0

func (d AgentDirs) Granted(ctx context.Context) (granted []string, refused map[string]string, err error)

Granted is Assess over the list stored in config.json now. An unreadable config.json grants nothing and returns the read error.

func (AgentDirs) ValidatePatch added in v0.15.0

func (d AgentDirs) ValidatePatch(stored, patch map[string]json.RawMessage) error

ValidatePatch judges patch against stored, the document it is merged into. A patch without the key passes. Otherwise its additional_directories must be a list of strings naming no entry twice, and Assess over that list may refuse only entries it already refuses over the stored list; the first other refusal is returned with Assess's reason. So a write never adds a refused entry or takes the grant from a kept one, and one refused today never blocks removing or adding another. Run it under settings.Update's lock, so stored is what the patch replaces.

type Document added in v0.17.0

type Document struct {
	// contains filtered or unexported fields
}

Document is one generation of config.json, parsed once. Every value decoded from it comes from the same bytes, with no I/O, so readers that take a Document cannot mix two readings. The zero Document is the absent document.

func Read added in v0.17.0

func Read(ctx context.Context, configDir string) (doc Document, gen uint64, err error)

Read reads config.json once and parses it once. gen is the generation the bytes were stored under; an absent file is one generation while it stays absent. err is nil for a readable document and wraps ErrUnparseable, with that generation's gen, for one that does not parse; any other err is a read error (a stat or open failure, a non-regular file, ctx ended) and gen is 0.

func (Document) Into added in v0.17.0

func (d Document) Into(key string, out any) bool

Into decodes key into out and reports success, logging a key that does not decode.

Jump to

Keyboard shortcuts

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