Skip to content

Finish the default_/bare-noun config naming scheme#720

Merged
dcellison merged 2 commits into
mainfrom
refactor/per-user-field-naming
Jun 22, 2026
Merged

Finish the default_/bare-noun config naming scheme#720
dcellison merged 2 commits into
mainfrom
refactor/per-user-field-naming

Conversation

@dcellison

Copy link
Copy Markdown
Owner

Summary

Finishes the config naming scheme so it is uniform: a default_ prefix marks an installation default (global), a bare noun marks the per-user override. Follow-up to the AGENT_BACKEND -> DEFAULT_BACKEND rename in #719.

Concept Global env Config field users.yaml key UserConfig field
backend DEFAULT_BACKEND (unchanged) default_backend (unchanged) backend backend
provider DEFAULT_PROVIDER default_provider provider provider
model DEFAULT_MODEL (unchanged) default_model (unchanged) model (unchanged) model (unchanged)
timeout DEFAULT_TIMEOUT default_timeout timeout (unchanged) timeout (unchanged)

Changes

Four key groups move, each with a one-release back-compat read window and a one-shot deprecation warning:

  • Per-user backend: UserConfig.default_backend -> backend; users.yaml default_backend -> backend. Read chain backend -> default_backend -> agent_backend (the per-user key was renamed twice, so the oldest name still resolves this release).
  • Per-user provider: UserConfig.llm_provider -> provider; users.yaml llm_provider -> provider.
  • Global provider: Config.llm_provider -> default_provider; env LLM_PROVIDER -> DEFAULT_PROVIDER; install.conf key migrated at apply time.
  • Global timeout: Config.agent_timeout_seconds -> default_timeout; env AGENT_TIMEOUT_SECONDS -> DEFAULT_TIMEOUT; install.conf key migrated at apply time. The older CLAUDE_TIMEOUT_SECONDS step is removed entirely (read fallback, wizard prefill, apply migration, and deprecated-env map entry).

Mechanism

  • _resolve_default_backend is generalized into _resolve_renamed_key(get, *, new_key, legacy_keys, context, default), taking an ordered legacy-key list. It is the single back-compat implementation for every reader (process env, install.conf dict, users.yaml entry) and warns once per (context, matched legacy key).
  • A new _entry_provider mirrors _entry_backend so both per-user provider read sites resolve through the same chain: the runtime loader and the installer goose-provider scanner (the scanner previously read llm_provider directly, which would have left a migrated install's goose API-key collection blind to the new key).
  • The behavioral eval and the memory backend gate share a new _resolve_eval_provider helper so neither eval-time reader bypasses the rename window.

Effective-param names that hold a post-cascade runtime value are left unchanged; only config fields, env vars, and users.yaml keys move.

Tests

make check and make test pass (4598 passed, 1 skipped). New back-compat coverage: legacy env/yaml resolution with warnings for each group, the apply-time LLM_PROVIDER and AGENT_TIMEOUT_SECONDS migrations, CLAUDE_TIMEOUT_SECONDS no longer honored, the installer scanners reading all backend keys and the new provider key, and the per-user provider inheritance cascade.

Docs

Templates (.env, users.yaml, goose-config comment) and README updated to the new names with one-release deprecation notes on the global env table. The wiki update is staged separately and will be pushed after this merges.

Completes the convention started by the AGENT_BACKEND -> DEFAULT_BACKEND
rename: a `default_` prefix marks an installation default (global) and a
bare noun marks the per-user override. Four key groups move, each with a
one-release back-compat read window and a one-shot deprecation warning:

- per-user backend: UserConfig.default_backend -> backend, users.yaml
  key default_backend -> backend (read chain backend, default_backend,
  agent_backend; the key was renamed twice).
- per-user provider: UserConfig.llm_provider -> provider, users.yaml
  key llm_provider -> provider.
- global provider: Config.llm_provider -> default_provider, env
  LLM_PROVIDER -> DEFAULT_PROVIDER, with apply-time install.conf
  migration.
- global timeout: Config.agent_timeout_seconds -> default_timeout, env
  AGENT_TIMEOUT_SECONDS -> DEFAULT_TIMEOUT, with apply-time migration.
  The older CLAUDE_TIMEOUT_SECONDS step is removed entirely (read
  fallback, wizard prefill, apply migration, deprecated-env map entry).

_resolve_default_backend is generalized into _resolve_renamed_key, which
takes an ordered legacy-key list and is the single back-compat
implementation for every reader (env, install.conf dict, users.yaml
entry). A new _entry_provider mirrors _entry_backend so both per-user
provider read sites (the runtime loader and the wizard goose-provider
scanner) resolve through the same chain. The two eval-time provider
readers (behavioral eval, memory backend gate) share a new
_resolve_eval_provider helper so neither bypasses the rename window.

Effective-param names that hold a post-cascade runtime value are left
unchanged; only config fields, env vars, and users.yaml keys move.
Templates, README, and tests are updated; back-compat tests cover each
legacy read, the apply-time migrations, and the inheritance cascade.
Two review fixes for the config-naming PR:

- Memory backend gate: stamp the resolved eval-time provider into the
  per-backend config (`make_backend_config` now sets default_provider),
  so the extraction path resolves the same (backend, provider) pair the
  run summary reports. Without it, a goose/opencode arm run from an
  install whose global backend is single-provider (claude/codex) left
  default_provider="" and extracted with an empty provider while the
  report showed the resolved one. Completes the gate's provider routing.

- Docs: DEFAULT_PROVIDER is required for the multi-provider backends
  (goose, opencode), not "non-Claude" (which wrongly implies codex), and
  opencode does use the provider (it selects the model registry), so the
  users.yaml note no longer says it is ignored for opencode. Reworded
  README, templates/.env, and templates/users.yaml accordingly.
@dcellison dcellison merged commit 758f05e into main Jun 22, 2026
1 check passed
@dcellison dcellison deleted the refactor/per-user-field-naming branch June 22, 2026 23:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants