fix: expose freellmpool models in OpenCode

[0xzr]

Summary

• register the freellmpool provider and six named routing aliases through OpenCodes runtime config hook
• preserve the selected default, custom provider/model settings, explicit disablement, allowlists, and user-supplied authentication
• forward FREELLMPOOL_PROXY_KEY to OpenAI-compatible model calls as well as plugin tools
• keep profile setup print-only and document authenticated manual fallbacks without rewriting user configuration
• extend clean-package smoke coverage for registration, idempotence, preservation, auth, defaults, and provider controls

Validation

• 883 passed full suite before the final docs-only regression addition
• line coverage 86.50%; branch coverage 74.67%
• Ruff, security exception policy, high/high Bandit: pass
• both OpenCode package clean-install/load smokes: pass
• opencode models freellmpool: six aliases visible
• live opencode run --model freellmpool/agent: pass
• Codex Sol 5.6 xhigh approved exact commit tree 402c97b80b219df5f61352454fd63ea69ee6b73f

Closes #99

Summary by Sourcery

Expose the freellmpool provider and its routing aliases to OpenCode via a runtime config hook while keeping user configuration and authentication intact.

New Features:

• Automatically register the freellmpool OpenCode provider and six named routing alias models through the plugin's runtime config hook.

Bug Fixes:

• Ensure the OpenCode plugin respects disabled providers, preserves existing provider options, custom models, and the selected default model, and correctly forwards proxy authentication.
• Prevent documentation examples from suggesting model defaults inside legacy manual fallback blocks that could override user choices.

Enhancements:

• Define shared provider model metadata for freellmpool and use it in both runtime registration and profile defaults so aliases appear with descriptive names in the OpenCode model picker.
• Clarify that profile installation and the OpenCode plugin operate in a print-only / non-mutating manner toward third-party config files while still registering providers at runtime.
• Standardize documentation examples to include FREELLMPOOL_PROXY_KEY in OpenCode provider configuration and describe model verification via opencode models freellmpool.
• Extend OpenCode package smoke tests and profile tests to cover provider registration idempotence, auth forwarding, preservation of user config and defaults, and docs consistency for proxy auth.

Documentation:

• Update integration, agent, promotion, and HTML docs to describe automatic freellmpool provider registration, non-mutating behavior, and to show proxy-key-based authentication in OpenCode configuration examples.

Tests:

• Expand OpenCode package smoke tests to validate freellmpool provider/model registration behavior, authentication propagation, default preservation, and disabled-provider handling.
• Add tests to ensure documentation config snippets consistently forward FREELLMPOOL_PROXY_KEY and that manual fallback examples avoid setting freellmpool as the default model.
• Adjust profile tests to assert inclusion of the FREELLMPOOL_PROXY_KEY placeholder in default OpenCode provider options.

Chores:

• Record the OpenCode plugin provider registration and configuration preservation behavior in the changelog.

[sourcery-ai]

Reviewer's Guide

Adds a runtime config hook to the OpenCode freellmpool plugin that auto-registers the freellmpool provider and six routing alias models while preserving existing configuration and proxy auth, and updates docs/tests/smoke checks to cover the new behavior and authenticated config examples.

Sequence diagram for OpenCode freellmpool runtime config hook

sequenceDiagram
  actor OpenCode
  participant FreellmpoolPlugin
  participant InstallProvider

  OpenCode->>FreellmpoolPlugin: FreellmpoolPlugin({ client })
  OpenCode->>FreellmpoolPlugin: config(config)
  FreellmpoolPlugin->>InstallProvider: installProvider(config)

  alt [config.disabled_providers includes freellmpool]
    InstallProvider-->>FreellmpoolPlugin: return
  else Provider_enabled
    opt [config.enabled_providers exists]
      InstallProvider->>config: enabled_providers.push("freellmpool")
    end
    InstallProvider->>config: config.provider.freellmpool ||= {}
    InstallProvider->>config: provider.options.baseURL ||= BASE_URL + "/v1"
    opt [PROXY_KEY is set]
      InstallProvider->>config: provider.options.apiKey ||= PROXY_KEY
    end
    InstallProvider->>config: provider.options.headerTimeout ??= 600000
    InstallProvider->>config: provider.options.timeout ??= 600000
    InstallProvider->>config: provider.options.chunkTimeout ??= 120000
    InstallProvider->>config: provider.models[id].name ||= PROVIDER_MODELS[id].name
  end

Loading

File-Level Changes

Change	Details	Files
Introduce installProvider helper and config hook to register freellmpool provider/models in OpenCode without overwriting user settings, while wiring in proxy authentication and timeouts.	Define PROVIDER_MODELS map with six named routing aliases and display names. Implement installProvider(config) to conditionally enable freellmpool, initialize provider/options/models objects, set baseURL/timeouts, and apply FREELLMPOOL_PROXY_KEY as apiKey when absent. Ensure provider models entries for each alias are created with default names but do not overwrite existing model configs. Add FreellmpoolPlugin.config async hook that calls installProvider on the OpenCode runtime config object.	integrations/opencode/freellmpool.js
Expand OpenCode package smoke test to verify plugin config hook behavior, provider model registration, auth forwarding, idempotence, default model preservation, and disabled_providers respect.	Set FREELLMPOOL_PROXY_KEY in the smoke runner environment before importing the plugin. After loading the plugin, call loaded.config with a config that has custom provider options/models and assert they are preserved while aliases are added. Call loaded.config twice on the same config to confirm idempotence of provider/model registration. Use a fresh config to assert apiKey is set from the environment when missing. Verify the plugin does not change an existing top-level model selection. Verify freellmpool is not added when it is in disabled_providers. Add corresponding error message strings for new smoke failures.	scripts/check_opencode_packages.mjs tests/test_opencode_packages.py
Align profile and documentation examples with the new provider/model behavior and authenticated proxy usage, including clarifying that setup is print-only and config hook does not rewrite user files.	Update Profile.opencode template to include provider name, FREELLMPOOL_PROXY_KEY-based apiKey, and explicit model alias entries with human-readable names. Add tests to assert the profile provider options include apiKey env substitution. Modify INTEGRATIONS.md, AGENTS.md, OpenCode README, main README, and run-opencode-on-free-models.html to describe the plugin config hook behavior, model picker verification, and that profiles/plugins do not edit third-party config files. Update multiple doc snippets and promotional content to include "apiKey": "{env:FREELLMPOOL_PROXY_KEY}" in freellmpool provider options and mention routing aliases. Add a docs test ensuring all listed docs contain the apiKey env placeholder and that manual fallback examples for older OpenCode versions do not hard-code freellmpool/ models in the config block preceding the picker section. Extend CHANGELOG with a note about the OpenCode plugin now registering provider and routing aliases via the runtime config hook while preserving existing provider options and auth.	src/freellmpool/profiles.py tests/test_profiles.py docs/INTEGRATIONS.md docs/AGENTS.md integrations/opencode/README.md README.md docs/run-opencode-on-free-models.html docs/promotion/long-form-article.md docs/promotion/reddit-opencode.md docs/promotion/reply-bank.md CHANGELOG.md tests/test_opencode_packages.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#99	Make the OpenCode freellmpool plugin register the freellmpool provider and six routing alias models via the runtime config hook so that opencode models freellmpool shows agent, spread, auto, fast, quality, and fair, while preserving existing provider settings, defaults, authentication, and respecting disabled/enabled providers without rewriting the user’s configuration.	✅
#99	Add regression and smoke-test coverage plus documentation updates to validate provider registration, idempotence, preservation of config and defaults, proxy authentication using FREELLMPOOL_PROXY_KEY, and live OpenCode model-list/completion behavior.	✅

Possibly linked issues

• OpenCode plugin install does not expose freellmpool models #99: PR adds config hook to register freellmpool provider/models, preserve user config/auth, and expose six aliases.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• Revisit the enabled_providers handling in installProvider — automatically pushing freellmpool into an existing allowlist may be surprising for users who intend that list to remain explicit.
• The defensive checks in installProvider (for config, config.provider, provider.models, etc.) are quite repetitive; consider simplifying the control flow or extracting small helpers to make the mutation logic easier to follow and maintain.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Revisit the `enabled_providers` handling in `installProvider` — automatically pushing `freellmpool` into an existing allowlist may be surprising for users who intend that list to remain explicit.
- The defensive checks in `installProvider` (for `config`, `config.provider`, `provider.models`, etc.) are quite repetitive; consider simplifying the control flow or extracting small helpers to make the mutation logic easier to follow and maintain.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}