(bug) Pi rejects every custom-provider connection before the run starts

[mmabrouk]

When a custom-provider connection is selected as the model for the pi_core harness and a run is triggered, the run is rejected before the agent starts — for every custom provider, including the one the error message itself recommends.

Steps to reproduce

1. In the connections drawer, add a custom provider connection with a provider-family kind (for example an OpenAI-compatible key, data.kind = "openai").
2. In the agent config, pick that connection's model for harness pi_core.
3. Trigger a run (/run on the agent service, or a run from the playground).

Observed

deployment 'openai' is not supported by harness 'pi_core' in v1

The error suggests switching to the OpenAI-compatible custom connection instead — but selecting that connection (data.kind = "custom") produces the same rejection, because "custom" isn't "direct" either.

The frontend model dropdown still lists these models under Pi, so nothing in the UI warns the user before they hit this.

Where this lives

• sdks/python/agenta/sdk/agents/platform/connections.py — _custom_provider_candidate sets deployment = data.get("kind") for every custom-provider candidate, so provider-family kinds (openai, openrouter, ...) end up as literal deployment values, indistinguishable from real deployment kinds (azure, bedrock, vertex_ai, custom).
• sdks/python/agenta/sdk/agents/capabilities.py — HARNESS_CONNECTION_CAPABILITIES["pi_core"].deployments only allows ["direct"].
• services/oss/src/agent/app.py — _check_harness_post_resolve is the gate that raises UnsupportedDeploymentError, producing the message above.
• The frontend already distinguishes provider-family kinds from real deployment kinds via DEPLOYMENT_KINDS in web/packages/agenta-entity-ui/src/DrillInView/SchemaControls/connectionUtils.ts (around lines 344-373). The backend has no equivalent classification.

Suggested fix: normalize provider-family kinds to deployment="direct" inside _custom_provider_candidate, sharing the frontend's deployment-kind classification as the single source of truth for what counts as a deployment vs. a plain provider family.

Context

Found while probing custom-provider connections end to end against the dev stack (2026-07-07). Surfaced by the new connect-model drawer in #5096, which now actively offers these custom-provider paths to users. Related: this is one of five connection gaps found in the same investigation — see also the Claude-side and resolution-ranking issues.

[linear-code]

AGE-3917

[mmabrouk]

Related custom-provider connection issues from the same investigation: #5115 (Claude custom gateway key not injected), #5116 (Claude + Vertex AI credentials), #5117 (connection-resolution shadowing/ambiguity), #5118 (frontend polish).

[sumit1kr]

Hi @mmabrouk, I reproduced this on the latest codebase and traced the execution path.

The resolved custom-provider connection is created in _custom_provider_candidate, where deployment is assigned from data["kind"] (for example "openai", "openrouter", or "custom").

During session initialization, _resolve_session_connection invokes _check_harness_post_resolve, which delegates to harness_allows_deployment. Since HARNESS_CONNECTION_CAPABILITIES["pi_core"] only allows deployments=["direct"], these provider-family values fail the capability check and the run is rejected with UnsupportedDeploymentError before the agent starts.

So the root cause appears to be that provider-family kinds are being propagated as deployment kinds during capability validation, causing valid custom-provider connections to be rejected by the pi_core harness.

I'd be happy to work on a fix for this. If that sounds good, could you please assign this issue to me?

[mmabrouk]

Verified fixed on main (traced the current source statically, did not run it). Closing.

The rejection this issue describes was real: _custom_provider_candidate copied data["kind"] straight into deployment, and HARNESS_CONNECTION_CAPABILITIES["pi_core"] allowed only deployments=["direct"], so a valid custom-provider connection was rejected with UnsupportedDeploymentError before the run started. Two changes on main close both ends of that path.

1. Known provider families now normalize to direct. sdks/python/agenta/sdk/agents/platform/connections.py:376-381 reads kind into data_kind, maps a known family to provider, and sets deployment = "direct" if provider is not None else provider_kind. A vault record with kind: "openrouter" (or any known Pi family) now resolves to deployment="direct", which was always allowed. This is PR #5265 ("[fix] Route known custom providers directly"), merged 2026-07-13.

2. Pi now consumes the custom surface. sdks/python/agenta/sdk/agents/capabilities.py lists deployments=["direct", "custom"] for both pi_core and pi_agenta, and the gate moved to harness_allows_pair(harness, provider, deployment), which checks the provider axis, the deployment axis, and their cross product. That covers the provider-less kind: "custom" (OpenAI-compatible) case, which fix 1 alone would still have rejected.

Regression tests pin both cases: test_known_direct_custom_provider_uses_direct_deployment (the kind: "openrouter" report) and test_openai_compatible_custom_normalizes_to_openai (the provider-less custom case).

Two rejections remain by design and are out of scope here: Pi's custom surface accepts only the openai family (enforced by HARNESS_CUSTOM_DEPLOYMENT_PROVIDERS), and Pi does not yet consume azure/bedrock/vertex. If someone sees UnsupportedDeploymentError today, one of those is the likely cause, not the original bug.