(bug) A custom provider's model list can shadow a working standard key, and ambiguous matches run with no credential

[mmabrouk]

Two related connection-resolution bugs found while probing custom-provider connections: a custom provider's model list can shadow a working standard key, and a genuinely ambiguous match runs with no credential instead of failing loud.

1. A custom provider's model list can shadow a working standard key

Steps to reproduce

1. Create a standard OpenAI vault connection with no slug (the common project-default case).
2. Also create a custom-provider connection whose models list happens to include a model name the standard key also serves (for example gpt-4o-mini), also with no slug.
3. Run against gpt-4o-mini.

Observed

The custom-provider connection resolves first, even though the standard OpenAI key would have worked and is what the user most likely intended.

Where this lives

sdks/python/agenta/sdk/agents/platform/connections.py — _candidate_pool (around lines 364-378) filters candidates by model-name match first and only falls back to provider match if there's no model match. For slug-less default connections this lets a custom provider's models list outrank a standard key's provider-family match.

Suggested fix: for slug-less default connections, rank a provider-family match on a standard key above a model-name match on a custom provider.

2. Ambiguous resolution is swallowed and the run proceeds with no credential

Steps to reproduce

1. Create two connections that both resolve for the same provider/mode combination such that resolve_connection raises AmbiguousConnectionError, on a slug-less (default) connection.
2. Run against that provider/model.

Observed

services/oss/src/agent/app.py — _resolve_session_connection's except ConnectionResolutionError branch (which AmbiguousConnectionError falls under) logs a warning and degrades to credential_mode="runtime_provided" with an empty env, exactly as it does for a genuinely missing default connection. The run proceeds with no credential injected at all, and the user later sees a generic "add your key" auth error — nothing tells them the real problem was an ambiguous match between two of their own connections.

Suggested fix: don't fold AmbiguousConnectionError into the same tolerant-degrade path as "no connection configured" — surface it as the run's actual failure reason so the user knows which connections are conflicting.

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 makes it much easier to end up with multiple overlapping connections. Related: this is one of five connection gaps found in the same investigation — see also the Pi-side and Claude-side issues.

[linear-code]

AGE-3920

[mmabrouk]

Related custom-provider connection issues from the same investigation: #5114 (Pi rejects custom providers pre-run), #5115 (Claude custom gateway key not injected), #5116 (Claude + Vertex AI credentials), #5118 (frontend polish).

[sumit1kr]

Hi @mmabrouk, I reproduced both issues on the latest codebase and traced the corresponding code paths.

Bug 1 — Custom provider shadows standard key

In _candidate_pool (connections.py), model-name matches are returned before provider-family matches are considered. As a result, if a custom provider advertises a model such as gpt-4o-mini, it will be selected ahead of a slug-less default OpenAI connection, even though the standard provider key would also satisfy the request.

I think the default-connection resolution should prefer a standard provider-family match over a custom provider's model-name match when both are valid candidates.

Bug 2 — AmbiguousConnectionError silently degrades

AmbiguousConnectionError inherits from ConnectionResolutionError, so _resolve_session_connection in app.py catches it in the broad except ConnectionResolutionError block and falls back to credential_mode="runtime_provided" with an empty env. This ends up looking identical to the "no default connection configured" case, and the user only sees a later authentication error instead of the actual ambiguity.

It seems better to handle AmbiguousConnectionError separately so the run fails with the real conflict rather than silently degrading.

I'd be happy to work on both fixes in a single PR if that sounds reasonable. Could you assign this issue to me?

[Souptik96]

@sumit1kr your analysis of both bugs matches what I found independently — credit where it's due, particularly on bug 2, where the inheritance chain (AmbiguousConnectionError → ConnectionResolutionError → the broad except in _resolve_session_connection) is the whole mechanism and you named it exactly.

You asked to be assigned on 7 July and nobody answered in the 24 days since. I don't want to step on your work, so to be explicit about what I'm doing: I'm opening a PR for bug 1 only. If you're still on this, say so and I'll close mine — and bug 2 is untouched either way, so it's yours if you want it.

Two things worth recording for whoever picks this up.

Bug 1's mechanism is slightly sharper than "model matches are returned first." A provider_key candidate can never match by model id — _provider_key_candidate builds the candidate without model_slugs or model_keys at all, so matches_model() is structurally always False for a standard key. That means the moment any custom provider advertises the requested id, _candidate_pool's model_matches list is non-empty and the if model.provider: provider-family branch is never reached. The standard key isn't out-ranked, it's excluded from consideration. On current main this sits at connections.py:417-431 (the issue says ~364-378; the file has drifted since 7 July).

The line numbers for bug 2 have moved too. services/oss/src/agent/app.py is now 168 lines and contains no _resolve_session_connection — that logic has been relocated since the issue was filed, so anyone starting on bug 2 should re-locate it first rather than trusting the path in the description. That relocation is the main reason I've scoped my PR to bug 1 rather than doing both in one PR as you proposed; the two fixes no longer live near each other.

One thing I'd like @mmabrouk's read on. The suggested fix — rank a provider-family match on a standard key above a model-name match on a custom provider, for slug-less default connections — is what I've implemented, and it fixes the reported case cleanly. But it has a consequence the issue doesn't mention: when a user has two standard keys for the same provider family and a custom provider advertising the requested model, the new ranking selects the standard-key pool, which is then genuinely ambiguous, so resolution raises AmbiguousConnectionError where today it would silently resolve to the custom provider. I think failing loud is right there and consistent with how _choose_default already treats competing defaults, but it is a behaviour change beyond the strict letter of the issue, so I've pinned it with a test and called it out rather than burying it.

The named path (_choose_named) is deliberately untouched: if a user names a connection by slug, narrowing by model id is correct, so _candidate_pool keeps its current semantics there.

I'll link the PR here shortly. I'm not a maintainer, just contributing — happy to adjust the ranking rule or the ambiguity call if you'd rather it went another way.