@spec compaction_model_assisted(keyword()) :: boolean()

Whether model-assisted compaction is enabled (default false).

@spec compaction_native(keyword()) :: boolean() | nil

Native OpenAI compaction overlay preference.

Absence (nil) means no preference; after Provider/backend resolve the overlay defaults on for chatgpt_codex / API-key OpenAI. Explicit false always wins. Explicit true still refuses open_responses and Anthropic. Invalid values are ignored with a warning and stored as nil.

@spec file_anthropic_models(keyword()) :: [String.t()] | nil

Anthropic models list from config.json only, or nil when absent/invalid.

@spec file_context_windows(keyword()) :: %{required(String.t()) => pos_integer()}

Context-window overrides from config.json (model => positive integer).

@spec file_model(keyword()) :: String.t() | nil

Effective model when config.json is present; application and env precedence still applies.

@spec file_models(keyword()) :: [String.t()] | nil

Models list from config.json only, or nil when absent/invalid.

@spec host_commands(keyword()) ::
  {:ok, %{required(String.t()) => non_neg_integer() | pos_integer()}}

Resolved host-command boundary limits.

@spec load(keyword()) :: load_result()

Load and resolve config.json.

Returns a JSON-serializable map with "path", "present", "effective", and "warnings". Missing files yield defaults and an empty warning list.

@spec merge_provider_opts(keyword(), keyword()) :: keyword()

Merge config defaults into Provider opts without clobbering explicit values.

@spec models_refreshed_at(keyword()) :: String.t() | nil

UTC timestamp written by the last explicit model-catalog refresh, if present.

@spec permission_default(keyword()) :: Permissions.mode()

Resolved permission default (:auto, :ask, or :read_only).

@spec presenter_idle_timeout_ms(keyword()) :: pos_integer()

Resolved presenter idle timeout in milliseconds.

Pixir has three independent clocks: stream_idle_timeout_ms bounds silence within a Provider transport stream; this key is the idle deadline between Session events in the CLI one-shot/resume Conversation.await path (ACP does not read it); and bash_timeout_ms caps each bash tool call. The 300-second default deliberately exceeds the bash default plus cleanup grace so a timed-out tool returns before the CLI gives up. Agents may raise a bash call's timeout_ms as high as bash_timeout_max_ms (600 seconds by default), above this default. At each expired presenter deadline, a live registered bash process extends the next wait only by the smaller of the presenter interval and its remaining effective timeout plus kill-escalation grace; a dead, closed, or over-cap process does not extend it.

@spec reasoning_effort(keyword()) :: String.t() | nil

Resolved reasoning effort, or nil to omit and let the model default.

@spec request_snapshot(keyword()) :: {:ok, map()} | {:error, map()}

Resolve one immutable model/backend snapshot from exactly one source-document read.

@spec responses_backend(keyword()) ::
  {:ok, :absent | Pixir.Providers.ResponsesBackend.t()} | {:error, map()}

Resolve only the explicit Responses backend descriptor from one request snapshot.

@spec skills_user_scope(keyword()) :: boolean()

Whether Skills discovery includes the user scope (default true).

@spec text_verbosity(keyword()) :: String.t() | nil

Resolved text verbosity, or nil to omit and let the model default.

@spec valid_reasoning_efforts() :: [String.t()]

Known reasoning effort intent ids (legacy list API); not a model/backend capability grant.

@spec web_search(keyword()) :: map() | false | nil

Resolved hosted web search preference.

This is not the runtime default. Absence (nil) means no preference; the Provider/backend seam decides later. An explicit disable is false. A map is an explicit enable (and may carry search policy fields). Invalid values are ignored with a warning and stored as false so they cannot default-on.