2/2 Implement explicit model gateway

[monadoid]

Why

#2438 makes model routing explicit in the protocol. This PR implements that contract in the runtime.

Model IDs from integrated providers are intentionally open: openai/gpt-future-preview is valid direct-provider input without a Stagehand catalog update. The runtime still validates the stable configuration choices it owns: direct credentials, Browserbase gateway selection, and custom endpoint configuration.

What changed

• Adds one server-side resolver with three execution targets:

  openai/gpt-future-preview
    → direct provider inference
  
  browserbase/openai/gpt-future-preview
    → Browserbase gateway → openai/gpt-future-preview
  
  { baseURL, modelName }
    → OpenAI-compatible endpoint
  

• Dispatches on the resolved target instead of treating a missing provider API key as Browserbase routing.

• Adds the Browserbase gateway client, which:

  • derives the regional Stagehand API URL;
  • authenticates with the Browserbase API key and session ID;
  • forwards the upstream provider-qualified model name unchanged.

• Implements the OpenAI-compatible endpoint path.

• Updates direct-provider adapters to forward an open provider model ID.

• Removes all runtime handling of type: "unlisted".

Test plan

• Focused schema, resolver, gateway-dispatch, and runtime-state tests pass.
• Gateway behavior is covered with mocked transport and real request construction.
• Live Browserbase gateway coverage remains an opt-in integration test because it requires dedicated credentials and a deployed endpoint.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5800c9e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

Review completed against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 15 files (changes from recent commits).

Confidence score: 4/5

• In packages/sdk-python/src/stagehand/client_models.py, the Stagehand(...) constructor now throws a raw Pydantic extra-field error when callers pass model_api_key or model_headers for Browserbase gateway models, which can break previously working client initialization with an opaque message—add explicit handling that rejects or ignores these fields with a clear SDK-level error/migration hint.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/sdk-python/src/stagehand/client_models.py">

<violation number="1" location="packages/sdk-python/src/stagehand/client_models.py:161">
P3: Constructing `Stagehand(model="browserbase/...", model_api_key=...)` or passing `model_headers` now raises a raw Pydantic extra-field validation error. Browserbase gateway models have no per-model connection fields; reject those options explicitly with the SDK's argument-validation path (or otherwise handle them) before expanding `connection`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Constructing Stagehand(model="browserbase/...", model_api_key=...) or passing model_headers now raises a raw Pydantic extra-field validation error. Browserbase gateway models have no per-model connection fields; reject those options explicitly with the SDK's argument-validation path (or otherwise handle them) before expanding connection.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk-python/src/stagehand/client_models.py, line 161:

<comment>Constructing `Stagehand(model="browserbase/...", model_api_key=...)` or passing `model_headers` now raises a raw Pydantic extra-field validation error. Browserbase gateway models have no per-model connection fields; reject those options explicitly with the SDK's argument-validation path (or otherwise handle them) before expanding `connection`.</comment>

<file context>
@@ -155,6 +156,13 @@ def _model_config(
     if base_url is None:
+        if model.startswith("browserbase/"):
+            return ModelConfig(
+                root=BrowserbaseModelConfig.model_validate({
+                    "model_name": model,
+                    **connection,
</file context>