fix: restore baseline reasoning-effort variants

[Lp-Francois]

Summary

Restore baseline reasoning-effort variants when LiteLLM exposes sparse per-level metadata. With plugin 1.4.1 and OpenCode 2.0.20, GPT-6 Astra currently offers only max and xhigh: discovery requires each level's flag to be explicitly true, but LiteLLM does not expose standard medium/high flags and treats low as opt-out.

The shared discovery path now includes low, medium, and high unless disabled when per-level flags are present, yielding low, medium, high, xhigh, and max for Astra. Both OpenCode entrypoints consume this metadata.

Deliberate choices:

• Explicit reasoning_effort_levels / supports_reasoning_efforts lists are authoritative, including empty lists, so restricted models do not gain unsupported baseline levels.
• model_info values win over litellm_params; missing/null values fall back to params, while explicit false is preserved.
• supports_reasoning: true alone does not justify inventing effort variants. Optional none/minimal remain opt-in rather than duplicating LiteLLM's provider-specific opt-out rules.
• Positive custom effort flags remain supported. Explicit supports_reasoning: false disables inferred variants.

Reference: LiteLLM's capability resolver documents the sparse flags and baseline semantics.

Type of change

• 🐛 Bug fix (non-breaking)
• ✨ New feature (non-breaking)
• 💥 Breaking change
• 📝 Documentation only
• 🔧 Internal / refactor

Checklist

• npm run typecheck passes
• No new runtime dependencies (or justified in this PR description)
• README updated if public API or behavior changed
• CHANGELOG.md updated under ## [Unreleased]
• Commit messages follow Conventional Commits

How was this tested?

• npm run typecheck
• npm test: 7 files, 87 tests passed.
• git diff --check
• Added table-driven discovery regressions for sparse Astra metadata, params fallback, explicit and empty lists, false/null handling, absent metadata, optional/custom levels, and malformed list members.
• Extended the OpenCode 2 provider-registration test to assert all five Astra variants and their outgoing reasoningEffort settings.

The Astra fixture reproduces reasoning metadata observed from a live LiteLLM /v1/model/info response. No generation requests were made to validate the newly selectable levels; this change addresses metadata discovery. Gateway version was not collected.

Screenshots / logs (optional)

Minimal relevant metadata:

{
  "key": "bedrock_mantle/openai.gpt-6-astra",
  "supports_reasoning": true,
  "supports_max_reasoning_effort": true,
  "supports_xhigh_reasoning_effort": true,
  "supports_none_reasoning_effort": false,
  "supports_minimal_reasoning_effort": false,
  "supports_low_reasoning_effort": null,
  "reasoning_effort_levels": null
}

Note: This PR was created with the contentful-github-create-pull-request skill, powered by Agents Kit. To follow or use this workflow, see the Agents Kit CLI skill docs.

Summary by CodeRabbit

• Bug Fixes
  • Reasoning-effort options now fall back to standard levels when metadata is sparse, while honoring explicit effort lists and disabled levels.
  • Prevented unsupported request parameters or negative-only flags from creating inferred options.
  • Restricted inferred options for GPT Pro models to provider-supported levels, including aliased and dated model names.
• Documentation
  • Clarified how metadata, explicit effort lists, and model-specific restrictions affect available reasoning options.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 39d0c249-46f5-439d-993b-5b3a42f73fe9

📥 Commits

Reviewing files that changed from the base of the PR and between 782d349 and e14dba4.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• src/types/index.ts
• src/utils/litellm-api.ts
• src/utils/reasoning-efforts.ts
• test/litellm-api.test.ts
• test/plugin-v2.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a reasoning-effort resolver for LiteLLM metadata. Model discovery uses it to determine available effort variants, including explicit lists, supported-parameter checks, inferred levels, and GPT Pro restrictions. Tests and documentation cover the updated behavior.

Changes

Reasoning Effort Discovery

Layer / File(s)	Summary
Resolve reasoning-effort metadata src/types/index.ts, src/utils/reasoning-efforts.ts, src/utils/litellm-api.ts, test/litellm-api.test.ts	The resolver combines model metadata and parameters, applies explicit-list and supported-parameter rules, infers eligible effort levels, and limits inferred GPT Pro variants. Model discovery calls the resolver. Tests cover resolution behavior.
Validate discovered model variants test/plugin-v2.test.ts, README.md, CHANGELOG.md	Plugin tests check variants for models with different metadata. The README documents the resolver rules, and the changelog lists the fixes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: yuseferi

Merge Risk: ⚪ Minimal · up to e14db

The change restores reasoning-effort variants while respecting metadata restrictions. No actionable merge-blocking issue was identified; merge after normal checks pass.

Security Architecture Review

Security architecture risk: 🔵 Low · up to e14db

The change affects discovered effort options without expanding credential or permission authority. Remaining uncertainty concerns how externally supplied option values are handled downstream.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Influence over discovery metadata can affect the variants exposed for corresponding model aliases and retained in configuration caches. The inspected flow confines that influence to variant identifiers and effort settings, rather than provider credentials, endpoint selection, or permission policy.

Trust Boundaries and Controls

• observed — Discovery retains its configured URL and header construction. Explicit lists accept string values without a fixed effort allowlist and precede inferred-model restrictions; this is capability metadata authority, not a demonstrated authorization bypass. The host adapter casts variant identifiers without validating their contents, leaving final external handling unverified.

Resilience and Maintainability Implications

• observed — Publication uses existing failure-containment mechanisms: refresh guards are released on completion, unsuccessful refreshes preserve stale data, changed credentials prevent second-host refresh publication, failed reloads restore previous models, and cache writes use temporary-file replacement with cleanup.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: restoring baseline reasoning-effort variants.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}