Optionally install and configure WP AI Gateway for OpenCode runtimes

[chubes4]

Goal

When opencode is selected in wp-coding-agents setup or upgrade, optionally install and configure wp-ai-gateway plus the WordPress AI Client provider stack so OpenCode can use the WordPress site as an OpenAI-compatible AI gateway.

This enables subscription-backed Codex access through WordPress without passing raw upstream credentials into OpenCode, Lab, or WP Codebox fan-out sessions.

Product shape

OpenCode runtime
  OPENAI_BASE_URL=<site>/wp-json/wp-ai-gateway/v1
  OPENAI_API_KEY=<gateway token>
        |
        v
wp-ai-gateway
  provider=codex
  model=gpt-5.5
        |
        v
ai-provider-for-openai Codex OAuth provider
        |
        v
ChatGPT/Codex subscription-backed access

Dependencies

• Support provider-owned custom request authentication WordPress/php-ai-client#237
• Add ChatGPT Codex OAuth provider WordPress/ai-provider-for-openai#30
• Harden generic OpenAI-compatible gateway CLI, token, and model routing Automattic/wp-ai-gateway#1

Scope

• Add an explicit opt-in setup/upgrade path for OpenCode installs.
• Suggested flags:
  • --with-ai-gateway
  • --ai-gateway-provider <provider>
  • --ai-gateway-model <model>
  • --ai-gateway-token <token> only for restoring a known token, not as the default path
  • --codex-oauth-refresh-token <token> or an env-based equivalent if provider setup exposes this cleanly
  • --no-ai-gateway if interactive setup later prompts
• Install/activate, without vendoring:
  • wp-ai-gateway from https://github.com/chubes4/wp-ai-gateway
  • ai-provider-for-openai with Codex provider support once available
  • a compatible php-ai-client/WordPress AI Client runtime if the site does not already have one
• Configure gateway provider/model through WP-CLI.
• Mint or reuse a gateway bearer token.
• Write OpenCode configuration or bridge environment so OpenCode uses the gateway as an OpenAI-compatible endpoint.
• Preserve existing native OpenCode auth behavior when gateway mode is not opted in.

Acceptance criteria

• ./setup.sh --runtime opencode --with-ai-gateway --ai-gateway-provider codex --ai-gateway-model gpt-5.5 ... installs and activates the gateway stack.
• Setup clearly reports that clients receive only the gateway token while upstream Codex OAuth tokens stay in WordPress.
• Generated OpenCode config/env points at:
  • OPENAI_BASE_URL=<site-url>/wp-json/wp-ai-gateway/v1
  • OPENAI_API_KEY=<gateway token> or a secret reference that resolves to that token
• Existing opencode.json repair remains additive by default and does not clobber user-owned config unless gateway mode is explicitly requested.
• Upgrade can install missing gateway pieces when explicitly requested.
• Upgrade does not rotate the gateway token unless explicitly requested.
• Upgrade does not overwrite configured provider/model unless explicitly requested.
• Dry-run prints planned plugin installs, WP-CLI commands, and config writes without printing secrets.
• Non-gateway OpenCode installs continue to use native OpenCode auth and existing model config.

Smoke tests

• ./setup.sh --local --runtime opencode --with-ai-gateway --ai-gateway-provider codex --ai-gateway-model gpt-5.5 --dry-run
• ./upgrade.sh --local --runtime opencode --with-ai-gateway --dry-run
• Regression: existing opencode.json additive repair preserves user provider/model fields when gateway mode is not set.
• Regression: gateway mode-generated config includes gateway base URL and token env/reference, not raw Codex refresh/access tokens.
• Runtime smoke on a real/test site:
  • curl <site>/wp-json/wp-ai-gateway/v1/models -H "Authorization: Bearer <gateway token>"
  • one OpenCode prompt through gateway using site-default

Risks

• Need a final source check for the exact OpenCode custom OpenAI-compatible provider config shape before implementation.
• Existing upgrade docs promise auth state is not touched. Gateway token creation is auth state, so it must remain explicit opt-in and clearly reported.
• Early implementation may need branch/tag pinning until the provider stack is released.

[chubes4]

Course-corrected boundary for the recursive OpenCode concern:

• wp-ai-gateway stays generic. It should not know about OpenCode.
• ai-provider-for-opencode stays a generic WordPress AI Client provider. It should not know about wp-ai-gateway.
• DMC stays generic. It should not know about wp-ai-gateway or OpenCode gateway mode.
• wp-coding-agents owns the product wiring because it is the layer selecting OpenCode and writing runtime config.

For this issue, the loop/topology check should be narrow and setup-time only: when --runtime opencode --with-ai-gateway is used, prevent obviously self-referential generated config. Do not add gateway-specific logic to provider repos.