feat: implement Unified Model Selection Configuration

[Leoyzen]

Unified Model Selection Configuration

Summary

This PR implements unified model selection support across AgentPool's protocol servers. Users can now define custom model variants in their manifest configuration, which will be exposed through both OpenCode and ACP server endpoints.

What's New

Shared Model Utilities (src/agentpool_server/shared/)

• New shared module for model-related helper functions
• extract_provider(): Extract provider names from any model configuration type (OpenAI, Anthropic, Gemini, etc.)
• build_providers_from_tokonomics(): Convert tokonomics discovery results into server-compatible provider objects
• apply_configured_variants(): Merge user-defined model variants with auto-discovered models

OpenCode Server Updates (opencode_server/routes/config_routes.py)

• Implements intelligent fallback hierarchy for model discovery:
  1. User-defined model_variants from manifest (preferred)
  2. Dynamic discovery via tokonomics
  3. Agent-specific modes (Codex/Claude thought levels)
  4. Empty list with warning (last resort)
• Removed hardcoded dummy provider fallback
• Configured variants take precedence over discovered models with identical IDs

ACP Server Updates (acp_server/acp_agent.py)

• get_session_model_state(): Now includes configured variants in session state responses
• set_session_model(): Validates model IDs against both tokonomics discovery and configured variants
• User-defined variants override auto-discovered models with matching IDs

Example Configuration

agents:
  my_agent:
    type: native
    model: "openai:gpt-4o"

model_variants:
  fast:
    type: string
    identifier: "openai:gpt-4o-mini"
  creative:
    type: anthropic
    identifier: "claude-sonnet-4"
  reliable:
    type: fallback
    models:
      - type: openai
        identifier: "gpt-4o"
      - type: anthropic  
        identifier: "claude-opus-4"

Key Behaviors

• Precedence: Configured variants override discovered models with the same ID
• Fallback: When no variants are configured, servers gracefully fall back to automatic discovery
• Backward Compatible: Existing configurations continue to work without changes
• Type-Safe: Full pattern matching implementation without runtime attribute access

Testing

• 29 comprehensive unit tests covering all model configuration types
• Tests for provider extraction, provider building, and variant merging
• Integration tests for end-to-end workflows

---

Files Changed: 5
Additions: 788 lines
Deletions: 71 lines

[phil65]

Can you explain what the aim is? Right now we expose thinking modes as variants I think, and it is also already possible to define "custom" models. Does this offer anything new compared to that?

[Leoyzen]

@phil65 The core goal of this PR is to address model management challenges in multi-source and private deployment scenarios.

Key Use Cases:

1. Multi-model aggregation services like OpenRouter

   • OpenRouter provides unified access to 200+ models, but capabilities, pricing, and context windows vary significantly
   • Administrators need precise control over available model scope in configuration, rather than exposing all models and confusing users

2. Privately deployed models

   • Organizations may run self-hosted models (e.g., vLLM, Ollama) that aren't in tokonomics discovery
   • These require explicit configuration to be usable

3. Model selection access control

   • Different users/scenarios should see different model options
   • Example: Regular users only see fast and reliable, while advanced users can access claude-opus-4

Distinction from existing features:

• thinking modes control reasoning intensity for specific agents (e.g., Claude's 4k/8k/16k tokens) without changing the underlying model
• model_variants provide model-definition-level abstraction, allowing custom identifiers to map to specific configurations
• This PR unifies the exposure of model_variants across OpenCode and ACP protocols, enabling IDEs like Zed to use configured model variants

Why this is a practical need:
In production environments, multi-vendor model support and access control are essential. While the codebase currently supports configuring model_variants, they aren't consistently exposed in server endpoints—meaning users in Zed/OpenCode cannot see or use these custom models. This PR bridges that gap.

[phil65]

Ok. Not really a fan of all these different concepts living next to each other, but I will think about it.

[Leoyzen]

@phil65 Thank you for the feedback. Let me clarify the original motivation behind this PR.

The primary goal was to provide a centralized place for custom model configuration that can be exposed to external applications like OpenCode, Zed, and other IDEs—allowing users to select models dynamically rather than being limited to a hardcoded list.

Real-world use case:
In some deployment scenarios (especially enterprise or team environments):

• Model configurations are managed remotely by administrators
• End users do not configure their own API keys and rely on the shared configuration
• Users need to choose from a curated set of models (e.g., fast, reliable, creative) based on their current task

Currently, AgentPool doesn't support model selection in TUI/GUI or WebUI interfaces—users are stuck with whatever is hardcoded or auto-discovered. This PR bridges that gap by:

1. Allowing admins to define meaningful model variants (not just raw model IDs)
2. Exposing these variants consistently across both OpenCode and ACP protocols
3. Enabling end users to make informed choices in their preferred client

I completely understand your concern about architectural complexity—having multiple overlapping concepts (thinking modes, model_variants, auto-discovery, custom models) can be confusing.

If you have a better proposal for unifying these concepts or a cleaner approach to achieve the same goal, I'm happy to close this PR and implement the alternative solution. Just let me know your preferred direction!