Files
codex/codex-rs/app-server-protocol/schema/json/v2/ConfigReadResponse.json
guinness-oai 4f2918dd7f [codex] Add opaque desktop config namespace (#22584)
## Summary
- reserve an explicit opaque `desktop` namespace in `ConfigToml`
- expose `desktop` directly in the app-server v2 `config/read` response
- keep `config/value/write` and `config/batchWrite` as the only mutation
seam for paths like `desktop.someKey`
- regenerate the config/app-server schema outputs and document the new
contract

## Why
The desktop settings work wants one durable, user-editable home for
app-owned preferences in `~/.codex/config.toml`, without forcing Rust to
model every individual desktop setting key.

This PR is only the enabling Rust/app-server layer. It gives the
Electron app a first-class config namespace it can read and write
through the existing config APIs, while leaving the actual desktop
migration to the app PR.

## Behavior and design notes
- **Opaque but explicit:** `desktop` is first-class at the typed config
root, while its children remain app-owned and open-ended.
- **Strict validation still works:** arbitrary nested `desktop.*` keys
are accepted instead of being rejected as unknown config.
- **Existing config APIs stay the seam:** `config/read` returns the bag,
and dotted writes such as `desktop.someKey` continue to flow through
`config/value/write` / `config/batchWrite` rather than a bespoke RPC.
- **No new consumer behavior:** Core/TUI do not start depending on
desktop preferences. This only preserves and exposes the namespace for
callers that intentionally use it.
- **Same persistence machinery:** hand-edited `config.toml` keeps using
the existing TOML edit/write path; this PR does not introduce a second
serializer or side channel.
- **TOML-friendly values:** the namespace is intended for ordinary
JSON-shaped setting values that map cleanly into TOML: strings, numbers,
booleans, arrays, and nested object/table values. This PR does not add
special handling for TOML-only edge cases such as datetimes.

## Layering semantics
Reads keep using the ordinary effective config pipeline, so `desktop`
participates in the same layered `config/read` behavior as the rest of
`ConfigToml`. Writes still target user config through the existing
config service.

## Why this is the shape
The alternative would be teaching Rust about each desktop setting as it
is added. That would make ordinary app preferences into a cross-repo
change, which is exactly the coupling we want to avoid.

This keeps the contract small:
1. Rust owns one opaque `desktop` namespace in `config.toml`.
2. The desktop app owns the schema and meaning of individual keys inside
it.
3. The existing config APIs remain the transport and mutation surface.

That is the piece the desktop settings PR needs in order to move forward
cleanly.

## Verification
- `cargo test -p codex-config strict_config_accepts_opaque_desktop_keys`
- `cargo test -p codex-core
desktop_toml_round_trips_opaque_nested_values`
- `cargo test -p codex-core config_schema_matches_fixture`
- `cargo test -p codex-app-server-protocol`
- `cargo test -p codex-app-server --test all desktop_settings`
2026-05-15 02:34:21 +00:00

913 lines
21 KiB
JSON
Generated

{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AbsolutePathBuf": {
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
"type": "string"
},
"AnalyticsConfig": {
"additionalProperties": true,
"properties": {
"enabled": {
"type": [
"boolean",
"null"
]
}
},
"type": "object"
},
"AppConfig": {
"properties": {
"default_tools_approval_mode": {
"anyOf": [
{
"$ref": "#/definitions/AppToolApproval"
},
{
"type": "null"
}
]
},
"default_tools_enabled": {
"type": [
"boolean",
"null"
]
},
"destructive_enabled": {
"type": [
"boolean",
"null"
]
},
"enabled": {
"default": true,
"type": "boolean"
},
"open_world_enabled": {
"type": [
"boolean",
"null"
]
},
"tools": {
"anyOf": [
{
"$ref": "#/definitions/AppToolsConfig"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"AppToolApproval": {
"enum": [
"auto",
"prompt",
"approve"
],
"type": "string"
},
"AppToolConfig": {
"properties": {
"approval_mode": {
"anyOf": [
{
"$ref": "#/definitions/AppToolApproval"
},
{
"type": "null"
}
]
},
"enabled": {
"type": [
"boolean",
"null"
]
}
},
"type": "object"
},
"AppToolsConfig": {
"type": "object"
},
"ApprovalsReviewer": {
"description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
"enum": [
"user",
"auto_review",
"guardian_subagent"
],
"type": "string"
},
"AppsConfig": {
"properties": {
"_default": {
"anyOf": [
{
"$ref": "#/definitions/AppsDefaultConfig"
},
{
"type": "null"
}
],
"default": null
}
},
"type": "object"
},
"AppsDefaultConfig": {
"properties": {
"destructive_enabled": {
"default": true,
"type": "boolean"
},
"enabled": {
"default": true,
"type": "boolean"
},
"open_world_enabled": {
"default": true,
"type": "boolean"
}
},
"type": "object"
},
"AskForApproval": {
"oneOf": [
{
"enum": [
"untrusted",
"on-failure",
"on-request",
"never"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"granular": {
"properties": {
"mcp_elicitations": {
"type": "boolean"
},
"request_permissions": {
"default": false,
"type": "boolean"
},
"rules": {
"type": "boolean"
},
"sandbox_approval": {
"type": "boolean"
},
"skill_approval": {
"default": false,
"type": "boolean"
}
},
"required": [
"mcp_elicitations",
"rules",
"sandbox_approval"
],
"type": "object"
}
},
"required": [
"granular"
],
"title": "GranularAskForApproval",
"type": "object"
}
]
},
"Config": {
"additionalProperties": true,
"properties": {
"analytics": {
"anyOf": [
{
"$ref": "#/definitions/AnalyticsConfig"
},
{
"type": "null"
}
]
},
"approval_policy": {
"anyOf": [
{
"$ref": "#/definitions/AskForApproval"
},
{
"type": "null"
}
]
},
"approvals_reviewer": {
"anyOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
},
{
"type": "null"
}
],
"description": "[UNSTABLE] Optional default for where approval requests are routed for review."
},
"compact_prompt": {
"type": [
"string",
"null"
]
},
"desktop": {
"additionalProperties": true,
"type": [
"object",
"null"
]
},
"developer_instructions": {
"type": [
"string",
"null"
]
},
"forced_chatgpt_workspace_id": {
"anyOf": [
{
"$ref": "#/definitions/ForcedChatgptWorkspaceIds"
},
{
"type": "null"
}
]
},
"forced_login_method": {
"anyOf": [
{
"$ref": "#/definitions/ForcedLoginMethod"
},
{
"type": "null"
}
]
},
"instructions": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"model_auto_compact_token_limit": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"model_context_window": {
"format": "int64",
"type": [
"integer",
"null"
]
},
"model_provider": {
"type": [
"string",
"null"
]
},
"model_reasoning_effort": {
"anyOf": [
{
"$ref": "#/definitions/ReasoningEffort"
},
{
"type": "null"
}
]
},
"model_reasoning_summary": {
"anyOf": [
{
"$ref": "#/definitions/ReasoningSummary"
},
{
"type": "null"
}
]
},
"model_verbosity": {
"anyOf": [
{
"$ref": "#/definitions/Verbosity"
},
{
"type": "null"
}
]
},
"profile": {
"type": [
"string",
"null"
]
},
"profiles": {
"additionalProperties": {
"$ref": "#/definitions/ProfileV2"
},
"default": {},
"type": "object"
},
"review_model": {
"type": [
"string",
"null"
]
},
"sandbox_mode": {
"anyOf": [
{
"$ref": "#/definitions/SandboxMode"
},
{
"type": "null"
}
]
},
"sandbox_workspace_write": {
"anyOf": [
{
"$ref": "#/definitions/SandboxWorkspaceWrite"
},
{
"type": "null"
}
]
},
"service_tier": {
"type": [
"string",
"null"
]
},
"tools": {
"anyOf": [
{
"$ref": "#/definitions/ToolsV2"
},
{
"type": "null"
}
]
},
"web_search": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchMode"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"ConfigLayer": {
"properties": {
"config": true,
"disabledReason": {
"type": [
"string",
"null"
]
},
"name": {
"$ref": "#/definitions/ConfigLayerSource"
},
"version": {
"type": "string"
}
},
"required": [
"config",
"name",
"version"
],
"type": "object"
},
"ConfigLayerMetadata": {
"properties": {
"name": {
"$ref": "#/definitions/ConfigLayerSource"
},
"version": {
"type": "string"
}
},
"required": [
"name",
"version"
],
"type": "object"
},
"ConfigLayerSource": {
"oneOf": [
{
"description": "Managed preferences layer delivered by MDM (macOS only).",
"properties": {
"domain": {
"type": "string"
},
"key": {
"type": "string"
},
"type": {
"enum": [
"mdm"
],
"title": "MdmConfigLayerSourceType",
"type": "string"
}
},
"required": [
"domain",
"key",
"type"
],
"title": "MdmConfigLayerSource",
"type": "object"
},
{
"description": "Managed config layer from a file (usually `managed_config.toml`).",
"properties": {
"file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "This is the path to the system config.toml file, though it is not guaranteed to exist."
},
"type": {
"enum": [
"system"
],
"title": "SystemConfigLayerSourceType",
"type": "string"
}
},
"required": [
"file",
"type"
],
"title": "SystemConfigLayerSource",
"type": "object"
},
{
"description": "User config layer from $CODEX_HOME/config.toml. This layer is special in that it is expected to be: - writable by the user - generally outside the workspace directory",
"properties": {
"file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "This is the path to the user's config.toml file, though it is not guaranteed to exist."
},
"profile": {
"description": "Name of the selected profile-v2 config layered on top of the base user config, when this layer represents one.",
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"user"
],
"title": "UserConfigLayerSourceType",
"type": "string"
}
},
"required": [
"file",
"type"
],
"title": "UserConfigLayerSource",
"type": "object"
},
{
"description": "Path to a .codex/ folder within a project. There could be multiple of these between `cwd` and the project/repo root.",
"properties": {
"dotCodexFolder": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": {
"enum": [
"project"
],
"title": "ProjectConfigLayerSourceType",
"type": "string"
}
},
"required": [
"dotCodexFolder",
"type"
],
"title": "ProjectConfigLayerSource",
"type": "object"
},
{
"description": "Session-layer overrides supplied via `-c`/`--config`.",
"properties": {
"type": {
"enum": [
"sessionFlags"
],
"title": "SessionFlagsConfigLayerSourceType",
"type": "string"
}
},
"required": [
"type"
],
"title": "SessionFlagsConfigLayerSource",
"type": "object"
},
{
"description": "`managed_config.toml` was designed to be a config that was loaded as the last layer on top of everything else. This scheme did not quite work out as intended, but we keep this variant as a \"best effort\" while we phase out `managed_config.toml` in favor of `requirements.toml`.",
"properties": {
"file": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": {
"enum": [
"legacyManagedConfigTomlFromFile"
],
"title": "LegacyManagedConfigTomlFromFileConfigLayerSourceType",
"type": "string"
}
},
"required": [
"file",
"type"
],
"title": "LegacyManagedConfigTomlFromFileConfigLayerSource",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"legacyManagedConfigTomlFromMdm"
],
"title": "LegacyManagedConfigTomlFromMdmConfigLayerSourceType",
"type": "string"
}
},
"required": [
"type"
],
"title": "LegacyManagedConfigTomlFromMdmConfigLayerSource",
"type": "object"
}
]
},
"ForcedChatgptWorkspaceIds": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Backward-compatible API shape for ChatGPT workspace login restrictions."
},
"ForcedLoginMethod": {
"enum": [
"chatgpt",
"api"
],
"type": "string"
},
"ProfileV2": {
"additionalProperties": true,
"properties": {
"approval_policy": {
"anyOf": [
{
"$ref": "#/definitions/AskForApproval"
},
{
"type": "null"
}
]
},
"approvals_reviewer": {
"anyOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
},
{
"type": "null"
}
],
"description": "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used."
},
"chatgpt_base_url": {
"type": [
"string",
"null"
]
},
"model": {
"type": [
"string",
"null"
]
},
"model_provider": {
"type": [
"string",
"null"
]
},
"model_reasoning_effort": {
"anyOf": [
{
"$ref": "#/definitions/ReasoningEffort"
},
{
"type": "null"
}
]
},
"model_reasoning_summary": {
"anyOf": [
{
"$ref": "#/definitions/ReasoningSummary"
},
{
"type": "null"
}
]
},
"model_verbosity": {
"anyOf": [
{
"$ref": "#/definitions/Verbosity"
},
{
"type": "null"
}
]
},
"service_tier": {
"type": [
"string",
"null"
]
},
"tools": {
"anyOf": [
{
"$ref": "#/definitions/ToolsV2"
},
{
"type": "null"
}
]
},
"web_search": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchMode"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"ReasoningEffort": {
"description": "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
"enum": [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh"
],
"type": "string"
},
"ReasoningSummary": {
"description": "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries",
"oneOf": [
{
"enum": [
"auto",
"concise",
"detailed"
],
"type": "string"
},
{
"description": "Option to disable reasoning summaries.",
"enum": [
"none"
],
"type": "string"
}
]
},
"SandboxMode": {
"enum": [
"read-only",
"workspace-write",
"danger-full-access"
],
"type": "string"
},
"SandboxWorkspaceWrite": {
"properties": {
"exclude_slash_tmp": {
"default": false,
"type": "boolean"
},
"exclude_tmpdir_env_var": {
"default": false,
"type": "boolean"
},
"network_access": {
"default": false,
"type": "boolean"
},
"writable_roots": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"ToolsV2": {
"properties": {
"web_search": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchToolConfig"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"Verbosity": {
"description": "Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.",
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
"WebSearchContextSize": {
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
"WebSearchLocation": {
"additionalProperties": false,
"properties": {
"city": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"region": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"WebSearchMode": {
"enum": [
"disabled",
"cached",
"live"
],
"type": "string"
},
"WebSearchToolConfig": {
"additionalProperties": false,
"properties": {
"allowed_domains": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"context_size": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchContextSize"
},
{
"type": "null"
}
]
},
"location": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchLocation"
},
{
"type": "null"
}
]
}
},
"type": "object"
}
},
"properties": {
"config": {
"$ref": "#/definitions/Config"
},
"layers": {
"items": {
"$ref": "#/definitions/ConfigLayer"
},
"type": [
"array",
"null"
]
},
"origins": {
"additionalProperties": {
"$ref": "#/definitions/ConfigLayerMetadata"
},
"type": "object"
}
},
"required": [
"config",
"origins"
],
"title": "ConfigReadResponse",
"type": "object"
}