1/2 Add gateway concept to protocol

[monadoid]

Why

Model provider and inference gateway are related but different choices:

• Provider is the upstream model API, such as OpenAI or Anthropic.
• Gateway is the service Stagehand calls for inference.

For direct inference, Stagehand calls the provider with the caller's provider key. Browserbase is an explicit gateway in front of an upstream provider/model: it authorizes the project and handles billing while the selected upstream model can still be an OpenAI or Anthropic model.

The protocol previously inferred Browserbase routing from a missing provider key and treated model IDs as a closed catalog. Neither belongs in the public contract: routing should be explicit, while a newly released model from an integrated provider should not require a Stagehand release.

What changed

• Adds the browserbase/... namespace for explicit Browserbase gateway inference.

  { modelName: "browserbase/openai/gpt-future-preview" }

• Replaces the per-model allowlist with an open, provider-qualified model-name schema. Providers remain a closed set:

  { modelName: "openai/gpt-future-preview", apiKey: "..." }

• Removes the type: "unlisted" path. Without a global model catalog, an integrated provider's new model ID is the normal direct-provider form.

• Keeps custom OpenAI-compatible endpoints explicit through baseURL:

  { modelName: "customer-deployment", baseURL: "https://models.example.com/v1" }

• Regenerates protocol JSON, exported TypeScript types, and generated Python models.

This PR defines the protocol contract. #2440 implements execution of the direct, Browserbase, and custom-endpoint targets.

Test plan

• Focused protocol schema tests pass.
• The generated protocol and Python models are up to date.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b60768f

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]

All reported issues were addressed across 6 files

Architecture diagram

sequenceDiagram
    participant Client as Stagehand Client
    participant SDK as Stagehand SDK
    participant Parser as ModelConfig Parser
    participant Gateway as Gateway Dispatcher
    participant Provider as Upstream Provider (OpenAI/Anthropic)
    participant BbGateway as Browserbase Gateway

    Note over Client,Parser: NEW: Model config selection flow

    Client->>SDK: startSession({ model: modelConfig })

    alt KnownModelConfig (direct)
        Client->>SDK: { modelName: "openai/gpt-5.4-mini", apiKey: "sk-..." }
        SDK->>Parser: validate(MODEL_CONFIG_SCHEMA)
        Parser->>Parser: match KnownModelConfigSchema
        Parser-->>SDK: KnownModelConfig { modelName, apiKey, headers? }
        SDK->>Gateway: dispatch(modelConfig, apiKey)
        Gateway->>Provider: POST /v1/chat/completions (apiKey in header)
        Provider-->>Gateway: inference response
        Gateway-->>SDK: response

    else UnlistedModelConfig (direct, uncataloged)
        Client->>SDK: { type: "unlisted", modelName: "openai/gpt-new-preview", apiKey: "sk-..." }
        SDK->>Parser: validate(MODEL_CONFIG_SCHEMA)
        Parser->>Parser: match UnlistedModelConfigSchema
        Parser-->>SDK: UnlistedModelConfig { type, modelName, apiKey }
        SDK->>Gateway: dispatch(modelConfig, apiKey)
        Gateway->>Provider: POST /v1/chat/completions (apiKey in header)
        Provider-->>Gateway: inference response
        Gateway-->>SDK: response

    else BrowserbaseModelConfig (gateway-managed, cataloged)
        Client->>SDK: { modelName: "browserbase/openai/gpt-5.4-mini" }
        Note over Client,SDK: NEW: No apiKey needed - Browserbase handles auth/billing
        SDK->>Parser: validate(MODEL_CONFIG_SCHEMA)
        Parser->>Parser: match BrowserbaseModelConfigSchema
        Parser-->>SDK: BrowserbaseModelConfig { modelName }
        SDK->>Gateway: dispatch(modelConfig)
        Gateway->>BbGateway: POST /v1/chat/completions (Browserbase credentials)
        BbGateway->>BbGateway: authorize project, handle billing
        BbGateway->>Provider: forward to upstream model
        Provider-->>BbGateway: inference response
        BbGateway-->>Gateway: response
        Gateway-->>SDK: response

    else BrowserbaseUnlistedModelConfig (gateway-managed, uncataloged)
        Client->>SDK: { type: "unlisted", modelName: "browserbase/openai/gpt-new-preview" }
        Note over Client,SDK: NEW: No apiKey, uncataloged model via Browserbase
        SDK->>Parser: validate(MODEL_CONFIG_SCHEMA)
        Parser->>Parser: match BrowserbaseUnlistedModelConfigSchema
        Parser-->>SDK: BrowserbaseUnlistedModelConfig { type, modelName }
        SDK->>Gateway: dispatch(modelConfig)
        Gateway->>BbGateway: POST /v1/chat/completions (Browserbase credentials)
        BbGateway->>BbGateway: authorize project, handle billing
        BbGateway->>Provider: forward to uncataloged upstream model
        Provider-->>BbGateway: inference response
        BbGateway-->>Gateway: response
        Gateway-->>SDK: response

    else CustomModelConfig (customer endpoint)
        Client->>SDK: { modelName: "...", baseURL: "https://custom.endpoint", apiKey: "..." }
        SDK->>Parser: validate(MODEL_CONFIG_SCHEMA)
        Parser->>Parser: match CustomModelConfigSchema
        Parser-->>SDK: CustomModelConfig { modelName, baseURL, apiKey }
        SDK->>Gateway: dispatch(modelConfig)
        Gateway->>Provider: POST to baseURL/v1/chat/completions (apiKey in header)
        Provider-->>Gateway: inference response
        Gateway-->>SDK: response
    end

    SDK-->>Client: session with LLM client

Loading

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

Re-trigger cubic</sub>