refactor(llm): promote decorator chain settings from NearAiConfig to top-level LlmConfig

[anthhub]

Summary

Retry, circuit breaker, and response cache settings were nested under NearAiConfig with NEARAI_* env var prefixes, but are applied to all LLM backends via build_provider_chain(). This confused users on non-NearAI backends (Gemini, OpenAI, Bedrock, etc.) who had to set NEARAI_MAX_RETRIES to control retry behavior.

• Added 6 top-level fields to LlmConfig: max_retries, circuit_breaker_threshold, circuit_breaker_recovery_secs, response_cache_enabled, response_cache_ttl_secs, response_cache_max_entries
• New LLM_* env vars resolve these fields, with automatic fallback to existing NEARAI_* / bare-name vars for backward compatibility
• build_provider_chain() now reads from LlmConfig directly instead of config.nearai
• No breaking changes — existing env vars continue to work

Fixes #1554

Test plan

• All 48 LLM/config tests pass
• cargo check (default features)
• cargo fmt
• Backward compatible: NEARAI_MAX_RETRIES still works when LLM_MAX_RETRIES is unset

[gemini-code-assist]

Code Review

This pull request refactors the LLM configuration by introducing top-level fields for retries, circuit breaker settings, and response caching. It adds environment variable parsing for these new fields with fallbacks to maintain backward compatibility. A review comment correctly identified an inconsistency in an error message regarding the circuit breaker threshold, suggesting it be updated to reflect that non-negative integers are valid.

[gemini-code-assist]

The error message states that LLM_CIRCUIT_BREAKER_THRESHOLD must be a positive integer. However, a value of 0 is a valid u32 and represents a valid configuration (tripping the breaker on the first failure). To be more accurate, this message should indicate a "non-negative integer".

Suggested change

	message: format!("must be a positive integer: {e}"),
	message: format!("must be a non-negative integer: {e}"),

[zmanian]

Review -- REQUEST_CHANGES

The refactoring rationale is sound -- these decorator chain settings apply to all LLM backends, not just NearAI, so LLM_* prefixed env vars make more sense. The backward compatibility approach (LLM_* takes priority, falls back to NEARAI_*) is correct.

Medium

1. No tests for the new env var parsing paths -- 6 new optional_env("LLM_*") blocks with fallback logic, but zero new tests verifying: LLM_* overrides NEARAI_, fallback works when only NEARAI_ is set, invalid LLM_* values produce correct ConfigError::InvalidValue. This is the core behavior the PR introduces.

2. Module spec (src/llm/CLAUDE.md) is stale -- Lines 112, 130, 170-171, 204-206 still reference NearAiConfig fields and NEARAI_* env vars as the configuration source. The "Provider Chain Construction" diagram still says NEARAI_CIRCUIT_BREAKER_THRESHOLD.

3. NearAiConfig fields not deprecated -- The 6 fields still exist on NearAiConfig with no deprecation marker. Future code can accidentally read config.nearai.max_retries instead of config.max_retries. Consider #[deprecated] or a follow-up tracking issue.

4. Failover settings inconsistency -- failover_cooldown_secs, failover_cooldown_threshold, fallback_model are still read from config.nearai.*. Same rationale applies -- users on non-NearAI backends face the same confusing prefix.

Low

5. .env.example not updated with the new LLM_* vars.
6. response_cache_max_entries default is 100 in for_testing() but 1000 everywhere else (pre-existing, but propagated).

Required

• Add at least one config-level test for the LLM_* override / NEARAI_* fallback behavior
• Update src/llm/CLAUDE.md to reflect the new env vars

[zmanian]

Re-Review -- APPROVE

Both requested items addressed in 5d6a74e:

1. Tests added: 3 new tests covering LLM_* override, NEARAI_* fallback, and invalid value error. Well-structured with lock_env() guards.
2. Module spec updated: src/llm/CLAUDE.md now documents LLM_* env vars for circuit breaker, retry, and response cache settings, including fallback behavior. Provider chain ASCII diagram updated.

[zmanian]

Re-Review -- APPROVE

The two new commits since my last review (5d6a74e: tests + docs, 5bf240a: merge conflict resolution) address both required items from my previous review:

1. Tests: 3 new tests added -- llm_max_retries_overrides_nearai, nearai_max_retries_used_as_fallback, llm_max_retries_invalid_value_produces_error. These cover the override, fallback, and error paths for the new env var parsing. Properly guarded with lock_env().

2. Module spec updated: src/llm/CLAUDE.md now documents LLM_* env vars with fallback behavior for circuit breaker, retry, and response cache settings. Provider chain diagram updated.

3. Merge commit (5bf240a): Clean conflict resolution keeping both the new decorator chain tests and the staging DB>ENV priority tests.

Minor (non-blocking)

• src/config/llm.rs:130 -- circuit breaker threshold error message still says "must be a positive integer" but u32 accepts 0. Should be "non-negative integer" for consistency with the other error messages. (Gemini flagged this too.)

• Medium items from previous review (NearAiConfig deprecation markers, failover settings inconsistency, .env.example, for_testing() cache entries default of 100 vs 1000 elsewhere) remain open but are not blocking for this PR.