fix: expose Vertex headers in public model config types

[shrey150]

Summary

• expose headers on GoogleVertexProviderSettings in Stagehand public model types
• add a public API type test proving model configs with headers are accepted for google/openai/anthropic
• add a patch changeset

Context

Runtime already forwards provider options to createVertex(), but TypeScript rejected headers in model config. This aligns public types with runtime behavior.

Validation

• pnpm -C packages/core run typecheck
• pnpm -C packages/core run build:esm
• pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/public-api/llm-and-agents.test.js
• pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/llm-provider.test.js

---

Summary by cubic

Expose the headers field on GoogleVertexProviderSettings in the public model config types so custom provider headers (e.g., X-Goog-Priority) are accepted without TypeScript errors. Updated the public API type test to cover Vertex headers and align the model config check with the public API style, keeping types consistent with runtime behavior.

^{Written for commit bf4907d. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: bf4907d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant App as Client Application
    participant Config as ModelConfiguration (Type)
    participant Core as AISdkClient (Stagehand Core)
    participant SDK as AI SDK Provider (Vertex/OpenAI)
    participant API as LLM Backend API (Google/OpenAI)

    Note over App,Config: User defines configuration
    App->>Config: Define modelName & settings
    Note right of Config: CHANGED: GoogleVertexProviderSettings<br/>now exposes 'headers' field

    App->>Core: Initialize Stagehand with config
    
    rect rgb(30, 41, 59)
    Note over Core,SDK: Provider Initialization Flow
    Core->>Core: Extract provider-specific settings
    
    alt Provider is Google Vertex
        Core->>SDK: createVertex({ project, location, headers, ... })
        Note right of Core: NEW: Headers (e.g., X-Goog-Priority)<br/>passed to SDK factory
    else Provider is OpenAI/Anthropic
        Core->>SDK: createOpenAI/Anthropic({ apiKey, headers, ... })
    end
    end

    SDK-->>Core: Return Model Instance

    Note over Core,API: Runtime Request Flow
    App->>Core: act() / observe() / prompt()
    Core->>SDK: Generate request
    SDK->>API: HTTP POST (Request Body)
    Note right of SDK: Includes custom headers<br/>from initial config
    API-->>SDK: Response
    SDK-->>Core: Parsed Result
    Core-->>App: Stagehand Response

Loading

[greptile-apps]

Greptile Summary

This PR fixes a TypeScript type mismatch for Google Vertex AI provider by exposing the headers property in GoogleVertexProviderSettings. The runtime already forwarded provider options including headers to createVertex(), but TypeScript was rejecting configs with custom headers like X-Goog-Priority.

Changes:

• Added "headers" to the Pick type for GoogleVertexProviderSettings in packages/core/lib/v3/types/public/model.ts
• Added comprehensive type test validating that ModelConfiguration accepts custom headers for Google, OpenAI, and Anthropic providers
• Included patch changeset documenting the fix

The change is minimal, focused, and properly tested. It aligns the public API types with the existing runtime behavior without introducing any breaking changes.

Confidence Score: 5/5

• This PR is safe to merge with no risks - it's a minimal type-only fix that aligns TypeScript types with existing runtime behavior.
• Score reflects that this is a minimal, well-tested type fix with no breaking changes. The change only exposes an existing property that the runtime already supported, and includes proper test coverage and documentation.
• No files require special attention

Important Files Changed

Filename	Overview
.changeset/flat-mice-cheer.md	Adds patch changeset documenting the headers exposure in GoogleVertexProviderSettings
packages/core/lib/v3/types/public/model.ts	Exposes headers property in GoogleVertexProviderSettings Pick type, aligning TypeScript types with runtime behavior
packages/core/tests/unit/public-api/llm-and-agents.test.ts	Adds type test validating that model configs accept custom headers for Google, OpenAI, and Anthropic providers

_{Last reviewed commit: c7e9266}

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[shrey150]

Merge activity

• Mar 3, 6:29 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 3, 6:30 PM UTC: @shrey150 merged this pull request with Graphite.