docs(agent-workflows): plan for custom providers + model auth in Pi

[mmabrouk]

Problem

A user selects a model and a provider for a Pi agent. Built-in providers work once a provider_key is stored (OpenRouter works this way: Pi ships 253 built-in OpenRouter models). Custom providers do not work on Pi, requested models can drop silently, and one provider is mis-mapped. This is a docs-only plan-feature workspace that diagnoses the gaps and sequences the fix. No code changes.

The five gaps (verified 2026-07-02)

1. Deployment gate (server-side). A custom_provider whose kind is a known direct provider (OpenRouter, OpenAI) resolves with deployment=<kind> in connections.py _custom_provider_candidate, not deployment="direct". Pi advertises deployments=["direct"], so _check_harness_post_resolve raises UnsupportedDeploymentError before the runner runs. This is why "OpenRouter works as a provider_key but not as a custom provider."
2. Runner never teaches Pi a custom provider. No Pi models.json is written anywhere in services/runner/src/; endpoint.baseUrl is applied for Claude only. A custom base URL and genuinely custom model ids never reach Pi.
3. Silent model drop. applyModel falls back to the harness default when setModel fails; strict is wired for Claude only. A requested-but-unsettable model returns HTTP 200 on the wrong model.
4. Picker never shows custom-provider models. buildModelOptionGroups reads only the static harness catalog; each vault custom-provider's models array is dropped at the VaultConnectionEntry type boundary.
5. Together env-var mismatch (one-liner). The provider-to-env map emits TOGETHERAI_API_KEY; Pi reads TOGETHER_API_KEY. Duplicated across three files, already drifted on minimax.

The plan (recommended order)

• Slice 0 (Gap 5): fix together_ai -> TOGETHER_API_KEY in all three maps, add missing minimax. Independent quick win.
• Slice 1 (Gap 1): normalize a known-direct custom_provider to deployment="direct" at resolve time. The fastest unblock: one resolver change makes a custom OpenRouter/OpenAI work on Pi for any built-in id, no runner or frontend work (the resolved env already carries the right *_API_KEY).
• Slice 2 (Gap 2, model-config Part 1): the runner writes auth.json (keys as "$ENV" references) and models.json (base URL override plus custom model) into PI_CODING_AGENT_DIR, local and Daytona. All inputs already ride resolved_connection + secrets; no wire change.
• Slice 3 (Gap 3, model-config Part 2): ModelNotSettableError, AGENTA_AGENT_MODEL_STRICT (default false, flip later), fix allowedModels to read c.value.
• Slice 4 (Gap 4): surface a project's custom-provider models in the picker (add models? to VaultConnectionEntry, merge under the harness filter) plus the static grouped-choice baseline.

Every contract this plan touches (the deployment field, the models.json shape, the picker-choices source, AGENTA_AGENT_MODEL_STRICT, the wire boundary) is classified by semantic role in design.md (the design-interfaces pass on paper). Open decisions and non-goals (Bedrock/Vertex/Azure on Pi stay fail-loud; no vault storage change; no new wire field) are recorded in status.md.

Builds on

• docs/design/agent-workflows/projects/provider-model-auth/ (BUILT, PR feat(agent): provider/model/connection for agent harnesses #4815): the connection resolver, the ResolvedConnection contract, the harness capability table, clear-then-apply.
• docs/design/agent-workflows/projects/model-config/ (DESIGNED, not built): the Pi auth.json/models.json write, fail-loud model, model choices per harness.

Appendix (not a slice): the Pi startup-banner leak in otel.ts isBannerLine (does not match pi-acp's newer Extensions section or .js paths) is a related, separately shippable fix.

https://claude.ai/code/session_01HCMtsTWnCdh8fPEzGrda6C

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 3, 2026 9:43am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9c8a467e-907f-4e5c-a5be-504e094f0e2f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch custom-providers-in-pi-plan

---

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.}