feat: True Multi-Provider Agent System with Model Tiers

[Steffen025]

Problem

PAI-OpenCode claims to be provider-agnostic with 75+ providers, but in practice spawning agents with different models from different providers is broken or severely limited. This is the #1 pain point for anyone who doesn't have an Anthropic Claude Max subscription.

What's Broken

1. Options-leak bug in upstream OpenCode — Unknown YAML frontmatter fields in agent .md files leak into LLM API requests via agent.options. This causes 400 Bad Request errors when using non-Anthropic providers that don't accept unknown fields. (Upstream PR #12967)

2. No model tier system — Every agent gets exactly ONE model. There's no way to say "use a cheap model for grunt work, but a powerful model for architecture decisions." The current opencode.json forces you to hardcode one model per agent, period.

3. All agents use the same provider — The provider profile system (switch-provider.ts) switches ALL agents at once. You can't mix providers: e.g., Opus on Anthropic for orchestration + Kimi K2.5 on Zen for coding + Sonar on Perplexity for search. The "multi-research" flag was a workaround but only covers research agents.

4. opencode.json template uses only Anthropic models — New users who set up PAI-OpenCode get a config that only works with an Anthropic API key. The template should demonstrate true multi-provider routing.

Real-World Impact

• Users with Zen, OpenRouter, or other aggregator accounts can't use their subscriptions effectively
• Cost optimization is impossible (can't route cheap tasks to cheap models)
• The "75+ providers" claim is misleading when the agent system only works well with one provider at a time

Solution

Phase 1: Patched OpenCode Binary (pai-opencode fork)

We maintain a patched fork at Steffen025/opencode with:

• Options-leak fix — Unknown agent frontmatter → metadata instead of options (commit 6710bdf)
• Model tiers — quick/standard/advanced tiers per agent (commit a780316)
• PAI CODE branding — Logo, binary name, exit message (commit 1f4c44d)

The Install Wizard should download this binary instead of upstream OpenCode.

Phase 2: True Multi-Provider Config Template

Update opencode.json to demonstrate real multi-provider routing:

{
  "agent": {
    "Algorithm": {
      "model": "anthropic/claude-opus-4-6"  // Orchestrator stays on Anthropic
    },
    "Engineer": {
      "model": "opencode/kimi-k2.5",         // Coding on Zen
      "model_tiers": {
        "quick": "opencode/minimax-m2.1",    // Simple fixes
        "standard": "opencode/kimi-k2.5",   // Normal coding
        "advanced": "opencode/glm-4.7"      // Text/docs writing
      }
    },
    "explore": {
      "model": "opencode/glm-4.7"           // Tool-use optimized
    },
    "PerplexityResearcher": {
      "model": "perplexity/sonar"            // Native provider
    }
    // ...
  }
}

Phase 3: Agent System Alignment

• Update PAI skill docs to reference model tiers
• Add model_tier selection guidance to the Algorithm/orchestrator instructions
• Ensure the Task tool passes model_tier correctly to agent resolution

Scope of Work

• Push patched fork to Steffen025/opencode + create GitHub Release with binary
• Update Install Wizard to download pai-opencode binary from fork releases
• Create multi-provider opencode.json template (not just Anthropic-only)
• Add model tier examples for key agents (Engineer, Researcher, etc.)
• Update README to reflect true multi-provider capabilities
• Update INSTALL.md with new binary installation flow
• Test end-to-end: fresh install → multi-provider agents working

References

• Upstream options-leak PR: fix(config): prevent agent frontmatter fields from leaking into LLM API requests anomalyco/opencode#12967
• Upstream model-tiers concept: feat(agent): implement model tier selection with variant support for subagents anomalyco/opencode#11377
• Local patched branch: feature/model-tiers in anomalyco/opencode fork