system-settings-inventory-reference

# System settings inventory This reference teaches the kernel-level catch-all behind `system(action="settings", input={})`. System owns a genuine adjustable LingTai setting only when no other concrete ToolPlugin owns it. SHOW returns exactly `key`, `current`, `default`, `configurable`, and `comment`; it never sets, resets, writes, refreshes, or mutates process environment. A row with `configurable: true` says only that an authorized external procedure below exists. It does not authorize the caller to perform that procedure. SHOW resolves one complete fresh snapshot. A malformed/unreadable `init.json`, active preset, System owner document, or risky-action gate document makes the whole inventory unavailable—there are no partial rows and no exception details. Sensitive rows replace both `current` and `default` with `<redacted>` before JSON serialization. ## Root and manifest inputs The canonical source is the real `init.json` reader: JSONC parse, active-preset materialization, provider inheritance, schema validation, and path resolution. No environment peers are invented for these fields. An active preset replaces the authored `manifest.llm` block, but its `llm.context_limit` remains preset-local for fit/authorization checks and is removed before effective init materialization; the System runtime-policy row reports the separate environment/v2/default result. Psyche owns configurable prompt pairs through its separate closed owner document; System neither resolves nor projects them. Derived `system/manifest.resolved.json` is never authority. | Key | Default and accepted value | Invalid behavior | Redaction | Application timing | |---|---|---|---|---| | `env_file` | absent; UTF-8 dotenv path | Missing file loads nothing; an invalid `init.json` path value fails the canonical read | full | Boot or System refresh; editing the dotenv needs refresh | | `venv_path` | absent, so launcher-managed resolution applies; venv-root path | An unusable configured root fails launcher validation | full | Full relaunch only | | `agent_name` | `null`; string or null boot seed | Wrong type fails init validation | none | Creation/full relaunch only; immutable for an existing identity, so `configurable` is false | | `language` | `en`; string | Wrong type fails init validation | none | System refresh | | `disable` | `[]`; `list[str]` | A non-list or any non-string entry fails init validation; entries are interpreted by capability composition without coercion or dropping | none | Capability rebuild during System refresh | | `admin` | `{}`; object | Wrong type fails validation | full authorization map | System refresh | | `time_awareness` | `true`; boolean | Wrong type fails validation | none | System refresh | | `timezone_awareness` | `true`; boolean | Wrong type fails validation | none | System refresh | | `preset.active` / `preset.default` | absent outside a preset block; non-empty strings and members of `allowed` | Missing/non-string/non-member values fail preset validation | full path/reference | Authorized preset workflow plus System refresh | | `preset.allowed` | absent outside a preset block; non-empty `list[str]` when preset is present | Empty, non-list, or invalid entries fail preset validation | full path/reference list | Authorized preset workflow plus System refresh | | `summarize_notification_threshold` | `3000`; non-negative integer, `0` disables the threshold hint | Negative or wrong type fails validation | none | System refresh | The seven ordinary runtime-policy rows are not init/preset rows. They resolve from valid `LINGTAI_<FIELD>` environment values, then a valid closed-v2 `settings/system.json` field, then the fixed runtime default. Each row's `comment` points here directly; the System entry keeps only legacy aliases: | Key | Fixed default | Accepted environment / v2 value | Application timing | |---|---|---|---| | `context_limit` | `272000` conservative service window | positive integer; v2 also accepts `null` for no configured limit | boot and System refresh before rebuilding LLM/session state | | `snapshot_interval` | `null` (off) | finite positive seconds; environment `off` / v2 `null` disables | boot and System refresh; enabling initializes the snapshot port first | | `max_rpm` | `60` | integer `>= 0`; `0` disables the request gate | boot and System refresh before rebuilding the LLM service | | `max_aed_attempts` | `3` | integer `>= 1` | boot and System refresh | | `aed_timeout` | `360.0` seconds | finite positive number | boot and System refresh | | `streaming` | `false` | canonical boolean words in the environment / JSON boolean in v2 | boot and System refresh, including the live SessionManager flag | | `activeness` | `balanced` | non-blank environment string / non-blank string or `null` in v2 | boot and System refresh; compatibility posture only | The corresponding environment names are `LINGTAI_CONTEXT_LIMIT`, `LINGTAI_SNAPSHOT_INTERVAL`, `LINGTAI_MAX_RPM`, `LINGTAI_MAX_AED_ATTEMPTS`, `LINGTAI_AED_TIMEOUT`, `LINGTAI_STREAMING`, and `LINGTAI_ACTIVENESS`. Legacy `manifest.context_limit`, `snapshot_interval`, `max_rpm`, `max_aed_attempts`, `aed_timeout`, `streaming`, and `activeness` are recognized-and-ignored compatibility data. SHOW never reports them as current truth and an active preset cannot override these runtime-policy rows. The row comment points directly to this document shape and authorized procedure; the System router does not own another copy of this policy. ### Runtime-policy v2 document shape The same `settings/system.json` file may be a closed v2 document naming any subset of the seven ordinary runtime-policy fields above plus `cache_miss_budget` (positive integer; see "Cache-miss budget" below) and `notification_max_chars` (positive integer; Core still clamps it to 2048–10000 and `LINGTAI_NOTIFICATION_MAX_CHARS` still wins), for example: ```json {"schema_version": 2, "context_limit": 200000, "max_rpm": 30, "streaming": true} ``` Booleans never stand in for numbers, `NaN`/`Infinity` are rejected, and an unknown, duplicate, or invalid key rejects the whole document so nothing is applied partially. An absent key and an explicit `null` are different: absent falls through to the fixed default, `null` is the configured value. The kernel-fixed context-pressure thresholds (0.85 / 1.0 / 3 rounds / 0.75) and the legacy `molt_*` fields are not settings: naming them makes the document invalid. The seven ordinary runtime-policy fields are resolved at CLI boot, before the first LLM service is built, and once on every refresh, so the service, `AgentConfig`, and the session streaming flag always agree; `init.json` and `system/manifest.resolved.json` are never rewritten to reflect it. Enabling `snapshot_interval` by refresh on a running agent initializes the snapshot repository first; if that fails, snapshots stay off for the process and `snapshot_initialize_failed` is logged. After explicit owner/human authorization, edit the intended environment value at its launcher owner or the corresponding v2 field with File/Shell, preserving unrelated fields. Follow `refresh-precheck` before applying a change at the boot/refresh timing in the table, then query System settings again. An invalid owner document applies no partial subset; this does not authorize repair, runtime refresh or configuration writes by itself. Cache-budget live resolution is separate and described below. ### Cache-miss budget Default-only row illustration (query SHOW for the actual current value): ```json {"key":"cache_miss_budget","current":2000000,"default":2000000,"configurable":true,"comment":"system-manual/reference/settings-inventory#cache-miss-budget"} ``` `current` resolves from a valid live `LINGTAI_CACHE_MISS_BUDGET`, then a live valid `settings/system.json` (the v1-only document below, or the v2 `cache_miss_budget` field above), then the fixed `2,000,000` default. The environment value is a positive base-10 integer string; the owner-file value is a positive JSON integer (a boolean is not an integer here). Invalid environment input falls through. A missing owner file selects the default; a present unreadable, malformed, duplicate-key, wrong-version, or otherwise invalid owner document makes SHOW return the fixed whole-inventory unavailable failure unless a valid environment value bypasses it. The runtime consumer retains its existing safe-default fallback on missing, unreadable, malformed or invalid owner JSON; this is distinct from SHOW failing the whole inventory. The reader never creates or rewrites the owner file. `configurable: true` means an authorized owner procedure exists outside SHOW; SHOW itself never writes, resets, or removes anything. This advisory budget is public, not sensitive, and is not redacted. The v1-only document shape (for an agent that only ever needs this one setting) is: ```json {"schema_version": 1, "cache_miss_budget": 2000000} ``` Both values must be JSON integers (not booleans), the version must be `1`, the budget must be positive, and no other or duplicate keys are accepted. Authorized change procedure: after explicit owner/human authorization, set `LINGTAI_CACHE_MISS_BUDGET` in the launcher or the agent's configured `env_file` (an `env_file` edit needs refresh before the running agent sees it), or use the existing File/Shell capability to write one of the two document shapes above to `settings/system.json` (remove the file through the same capability to return to the default), then call `system(action="settings", input={})` again and verify `current`. If the environment source still wins, change or remove it at its launcher/`env_file` owner instead of editing the lower-precedence file repeatedly. Direct process-env and unshadowed file changes apply on the next metadata snapshot; an `env_file` edit still needs refresh. Threshold changes and refreshes do not reset cumulative `token_usage.session.cache_miss_tokens`; only molt does. The threshold is advisory and never blocks a request. This path is unrelated to `.notification/system.json`. Legacy `init.json` `manifest.cache_miss_budget` is ignored and has no runtime effect. `manifest.summarize_notification_threshold` remains System-owned: it controls cross-cutting Agent/ToolExecutor result hints, not the Context ToolPlugin's public summarize action. Conversely, `manifest.pseudo_agent_subscriptions` belongs to the concrete Email ToolPlugin because CLI composition hands it directly to `PosixFilesystemMailAdapter`, which resolves the subscription paths. It is intentionally absent from System SHOW. The Email-owner inventory uses the generic sensitive-value seam to fully redact both current and default path lists; System neither duplicates that row nor exposes the paths. Authorized change procedure: after explicit owner/human authorization, edit the exact `init.json` field with the existing File or Shell capability. For a preset-owned LLM/context value, edit the authorized preset outside SHOW or use the existing `system(action="refresh", input={"preset": ...})` workflow; never edit the derived resolved manifest or widen `preset.allowed` as a shortcut. Run the refresh precheck, refresh/relaunch at the timing above, then call SHOW again. Psyche-owned prompt/file pairs are changed only through the procedure in `psyche-manual`; changing or removing a pointer never changes or deletes the referenced file. Existing identity changes use `system(action="name_set"|"name_nickname")`; editing `manifest.agent_name` is not a supported rename procedure. ## LLM and provider inputs Every effective `manifest.llm` axis is System-owned because no LLM ToolPlugin exists. Precedence is active preset over authored init for the whole block. The credential path is the exception inside the materialized block: a named non-empty `api_key_env` value wins inline `api_key`. Initial boot uses only those two authored sources through `resolve_env_checked`; it does not consult an invented `{PROVIDER}_API_KEY` fallback. No secret, alias value, header, auth path, endpoint pool, or credential-bearing URL is ever projected. | Key | Default and accepted value | Invalid behavior | Projection | Timing | |---|---|---|---|---| | `llm.provider` | no default; required string supported by the adapter registry | Missing/wrong type fails init; unknown provider fails adapter construction | literal | LLM rebuild on refresh | | `llm.model` | no default; required string | Missing/wrong type fails init/provider construction | literal | LLM rebuild on refresh | | `llm.api_key` | no universal default; string/null plus the credential precedence above | Missing required credentials fail initial adapter construction; a missing named alias uses an authored inline key when present and otherwise remains absent | `<redacted>` | LLM rebuild on refresh | | `llm.api_key_env` | absent; environment-variable name | Wrong type, or alias without inline key and without `env_file`, fails canonical validation | `<redacted>` | Resolved at boot/refresh | | `llm.base_url` | provider-owned when omitted; string/null | Provider validation owns unsupported endpoints | `<redacted>` because URLs may embed credentials | LLM rebuild on refresh | | `llm.compact_threshold` | no universal owner default; positive integer or null. Official OpenAI and `_custom` names (`custom`, `grok`, `qwen`, `kimi`) on effective `openai` compatibility have selected-route default `100000`; omission consumes it and explicit compact null is forwarded as disabled. Canonical provider-default normalization filters authored `api_compat: null`, so `_custom` still defaults to OpenAI and forwards that compact null. Exact `anthropic`/`gemini` compatibility ignores it. Other admitted non-null compatibility values fall through to `OpenAIAdapter` without forwarding this axis, so current/default are both `100000`. DeepSeek current is an authored positive value or null and default is null. Gemini/other ignored factories and native `codex`/`codex-pool`/`codex_pool` current/default are null; native Codex uses separate `codex_compact_token_limit` | Non-positive integer or wrong type fails validation | selected-adapter current and default | Adapter rebuild on refresh | | `llm.wire_api` | Selected-route truth, not one universal default. Omitted official OpenAI, DeepSeek, and `_custom` OpenAI/fallback routes select `chat_completions`; omitted MiMo selects `responses`; an explicit selector that canonical init admits is forwarded and preserved on those factories (notably MiMo preserves explicit `auto`). Codex aliases ignore the generic selector and always report forced `responses`. `_custom` Anthropic/Gemini routes and every other factory that ignores this axis report null current/default | Unknown values fail init validation. Canonical init admits non-`auto` only for official OpenAI, DeepSeek, and exact `custom`+OpenAI compatibility; `auto` is admitted everywhere but ignored routes still report null | selected-factory current and omitted default | Adapter rebuild on refresh | | `llm.inject_reasoning_fallback` | Selected-factory truth. Official OpenAI and `_custom` aliases on exact/default OpenAI compatibility forward an authored boolean; omission/null consults `LINGTAI_INJECT_REASONING_FALLBACK`, whose invalid/unset default is `true`. A malformed finite `_custom` selector still chooses OpenAI but `_custom` does not forward the authored axis, so the adapter consults that environment resolver. DeepSeek forwards an authored boolean and otherwise pins `true`, independent of that environment variable. Every ignoring factory reports null current/default | Wrong init type fails canonical validation; ignored factories add no provider-specific validation | selected-factory boolean/default or null | Adapter construction on refresh | | `llm.reasoning_effort_vocab` | official OpenAI and `_custom` names (`custom`, `grok`, `qwen`, `kimi`) on effective `openai` compatibility have selected-route default `openai`; string/null (`seven_tier` selects retained alternate mapping), with omitted and explicit vocabulary null consuming `openai`. Canonical normalization filters authored compat null but retains a non-null authored vocabulary, so `_custom` forwards (for example) `seven_tier`. Exact `anthropic`/`gemini` compatibility ignores the axis. Other admitted non-null compatibility values fall through to `OpenAIAdapter` without forwarding the axis, so current/default remain `openai`. DeepSeek's provider policy, Gemini/other ignored factories, and all native Codex spellings ignore this generic axis, so current/default are null | Wrong type fails validation; other strings retain the OpenAI behavior only when the effective OpenAI route forwards them | selected-adapter current and default | Adapter rebuild on refresh | | `llm.prompt_cache_namespace` | Official OpenAI and `_custom` aliases on exact/default OpenAI compatibility forward an authored string and otherwise use null. A malformed finite `_custom` selector chooses OpenAI without forwarding this axis, so it remains null. DeepSeek forwards an authored string and otherwise uses `deepseek`. Every ignoring factory reports null current/default | Wrong init type fails canonical validation; ignored factories add no provider-specific validation | selected-factory namespace/default only, never prompt/cache content | Adapter rebuild on refresh | | `llm.service_tier` | Codex aliases only: absent is null; authored `fast` is reported as `fast` and the factory normalizes it to private wire `priority`. Every non-Codex route ignores the axis and reports null current/default | Wrong type fails init. An unsupported Codex value fails canonical factory validation and SHOW; unsupported OpenAI/custom/other values are ignored and are not predicted to fail | selected-factory canonical authored value | Adapter rebuild on refresh | | `llm.thinking` | selected-route default comes from canonical `build_agent_config` hydration with thinking omitted: provider-owned `default` for Codex aliases/DeepSeek and legacy `high` otherwise | Unsupported provider/model/wire or effort fails canonical/provider validation | literal hydrated effort only | Session rebuild on refresh | | `llm.api_compat` | Every name bound to `_custom` (`custom`, `grok`, `qwen`, `kimi`) has factory default `openai`; omission and explicit null both select/report `openai`. Exact `anthropic` and `gemini` report those adapter routes. Every other finite accepted value—including case variants, unknown strings, numbers, lists, and objects—selects and reports canonical public `openai`, because that is the custom adapter's fallback. Other registered factories ignore this axis and report null current/default | Any non-finite float at any nesting depth fails canonical init validation; other finite compatibility values remain deliberately tolerant and select the fallback above | effective selected adapter route and default, never malformed authored syntax | Adapter rebuild on refresh | | `llm.codex_session_anchor` | derived from the resolved agent `init.json` path for Codex | Explicit value is an internal/testing escape, not an authorized production setting | `<redacted>` | Adapter rebuild; `configurable` is false | | `llm.codex_auth_path` | provider-owned legacy auth path when absent; path-like override | Missing/unreadable/invalid auth fails the request/provider path closed | `<redacted>` | Adapter rebuild/request-owned reread | | `llm.codex_auth_pool_path` | provider/TUI pool resolution when absent; path-like override | Invalid pool fails the provider account-source path closed | `<redacted>` | Adapter rebuild and request-bound account selection | | `llm.codex_base_urls` | absent means single `base_url`; string or list accepted by the Codex adapter | Invalid/empty entries follow the adapter's pool validation/fallback | `<redacted>` | Adapter rebuild; selection rotates only at the documented molt boundary | | `llm.default_headers` | `{}` user headers; JSON object in normal use | Non-object values are not forwarded as user headers; provider construction owns final validation | `<redacted>` including names and values | Adapter rebuild on refresh | Authorized change procedure: after explicit owner/human authorization, update the selected preset (when active) or `init.json`, keep credentials in the supported private env/file source, run the refresh precheck, refresh, and SHOW again. Never print a before/after credential, header, prompt, token, auth path, or endpoint-pool value. SHOW never edits a preset, credential file, header map, or process environment. ## Kernel environment controls These are genuine kernel/LLM settings without another ToolPlugin owner. Direct process-environment changes apply at the canonical read point; an `env_file` edit first needs System refresh. Missing/invalid values fall back exactly as shown. `LINGTAI_CODEX_WS` is a compatibility alias under the single `llm.codex_transport` row: a non-empty canonical `LINGTAI_CODEX_TRANSPORT` always decides first. | Key (environment) | Default; accepted values; invalid behavior | Current read/application timing | Projection | |---|---|---|---| | `nudge.enabled` (`LINGTAI_NUDGE_ENABLED`) | on; `on/off`, `true/false`, `1/0`; invalid → on | Every Nudge operation | literal boolean | | `nudge.repeat_interval_seconds` (`LINGTAI_NUDGE_REPEAT_INTERVAL`) | `86400`; positive duration with `s/m/h/d`; invalid → 24h | Every Nudge operation | numeric seconds | | `nudge.folder_size_gb` (`LINGTAI_NUDGE_FOLDER_SIZE_GB`) | `5`; positive finite decimal GB; invalid → 5 | Every folder-size evaluation | number | | `lifecycle.active_stuck_threshold_seconds` (`LINGTAI_ACTIVE_STUCK_THRESHOLD_S`) | `600`; finite numeric seconds floored to 30; parse failure or non-finite value → 600 | Each ACTIVE watchdog evaluation | number |