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
- Variables
- func AgentIgnoreList(entries []string) []string
- func Announce(ctx context.Context, configDir string, ...)
- func DebugLogs(ctx context.Context, configDir string) bool
- func DebugLogsIn(d Document) bool
- func DefaultAgentIgnoreFiles() []string
- func EffectiveDefaults() marotte.EffectiveSettings
- func EffectiveFrom(stored map[string]json.RawMessage) (effective marotte.EffectiveSettings, rejected []string)
- func Field[T any](ctx context.Context, configDir, key string) (T, bool)
- func FieldInto(ctx context.Context, configDir, key string, out any) bool
- func FieldStrict[T any](ctx context.Context, configDir, key string) (value T, found bool, err error)
- func HighThroughputIn(d Document) bool
- func Lookup[T any](d Document, key string) (value T, found bool, err error)
- func LookupOr[T any](d Document, key string, def T) T
- func MCPWaitForReady(ctx context.Context, configDir string) (on, readable bool)
- func MCPWaitForReadyIn(d Document) bool
- func MemoryPreferenceFor(mode string) marotte.MemoryPreference
- func RetentionEnabled(ctx context.Context, configDir string) bool
- func ThreeStateChoice(e *marotte.EffectiveSettings, key string) (string, bool)
- func Update(ctx context.Context, configDir string, ...) (map[string]json.RawMessage, error)
- func ValidAgentIgnoreEntry(entry string) error
- func ValidAutoCompactPct(pct int) bool
- func ValidFeatureChoice(v string) bool
- func ValidOutputStyle(v string) bool
- func ValidSpecPlanning(v string) bool
- func ValidTerminalCommandTimeoutMs(ms int) bool
- func ValidateAgentPatch(patch map[string]json.RawMessage) error
- func ValidateCompactionPatch(patch map[string]json.RawMessage) error
- func WarnUnknownKeys(keys []string, source string) []string
- type AgentDirs
- type Document
Constants ¶
const ( SpecPlanningOff = "off" SpecPlanningQuick = "quick" )
The values of KeySpecPlanning: KAS's own specPlan workflow vocabulary, plus off.
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.
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.
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.
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.
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.
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.
const DefaultContentCollectionEnabled = false
DefaultContentCollectionEnabled is the content-collection switch's default: off, so nothing is offered for service improvement until the user opts in.
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.
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).
const Filename = filename
Filename is the basename of marotte's config file (not kiro-cli's cli.json).
const OutputStyleDefault = "default"
OutputStyleDefault is KAS's default output style id, the one prompts never send.
Variables ¶
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.
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.
var KnownKeys = map[string]struct{}{ KeyAgentIgnoreFiles: {}, KeyAdditionalDirectories: {}, KeyAutoCompactionEnabled: {}, KeyAutoCompactPct: {}, KeyAutoDelegation: {}, KeyAutoRouting: {}, KeyChatRetentionDays: {}, KeyCloudFormationSafety: {}, KeyDebugLogs: {}, KeyEngineHeapMiB: {}, KeyHighThroughput: {}, KeyOutputStyle: {}, KeySpecPlanning: {}, KeySpecPlanningAskFirst: {}, KeySteeringReminders: {}, KeyTerminalCommandTimeoutMs: {}, KeyWorkValidation: {}, KeyWorkflowsEnabled: {}, KeyFBPath: {}, KeyGuardPayloadLinks: {}, KeyKnowledgeEnabled: {}, KeyModelFallback: {}, KeyContentCollectionEnabled: {}, KeyLastEffortByModel: {}, KeyLastMergeMethod: {}, KeyLastModel: {}, KeyMCPWaitForReady: {}, KeyMemoryMode: {}, KeyNotificationsEnabled: {}, KeyNotifyAgentFinished: {}, KeyNotifyPRStatus: {}, KeyNotifyRunOutcome: {}, KeySupervisedDefault: {}, KeyScheduledAutoApprove: {}, KeySecurityProfile: {}, KeySettingsEpoch: {}, KeySettingsRevision: {}, KeyTheme: {}, }
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 ¶
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
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
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 ¶
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 ¶
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
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
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
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
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
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 ¶
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 ¶
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
ValidAutoCompactPct reports whether pct is a value the slider can produce: 50..90 in steps of 5.
func ValidFeatureChoice ¶ added in v0.12.0
ValidFeatureChoice reports whether v is a follow-kiro-cli choice.
func ValidOutputStyle ¶ added in v0.12.0
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
ValidSpecPlanning reports whether v is one of the three spec-planning values.
func ValidTerminalCommandTimeoutMs ¶ added in v0.12.0
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 ¶
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
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
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
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.