feat: Include LLM headers in ModelConfig

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-a4a5ea048bb50d06460d81d6828b53b12b19e9224121ee6338dcd1f0781e22a1.yml
-openapi_spec_hash: 9b81c0ae04576318d13d7a80d4ab7b5a
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-bc309fd00fe0507f4cbe3bc77fa27d0fbffeaa6e71998778da34de42608a67e8.yml
+openapi_spec_hash: 1db1af5c1b068bba1d652102f4454668
 config_hash: d6c6f623d03971bdba921650e5eb7e5f

src/Sessions/ModelConfig.php

@@ -15,6 +15,7 @@
  *   modelName: string,
  *   apiKey?: string|null,
  *   baseURL?: string|null,
+ *   headers?: array<string,string>|null,
  *   provider?: null|Provider|value-of<Provider>,
  * }
  */
@@ -41,6 +42,14 @@ final class ModelConfig implements BaseModel
     #[Optional]
     public ?string $baseURL;
 
+    /**
+     * Custom headers sent with every request to the model provider.
+     *
+     * @var array<string,string>|null $headers
+     */
+    #[Optional(map: 'string')]
+    public ?array $headers;
+
     /**
      * AI provider for the model (or provide a baseURL endpoint instead).
      *
@@ -73,12 +82,14 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
+     * @param array<string,string>|null $headers
      * @param Provider|value-of<Provider>|null $provider
      */
     public static function with(
         string $modelName,
         ?string $apiKey = null,
         ?string $baseURL = null,
+        ?array $headers = null,
         Provider|string|null $provider = null,
     ): self {
         $self = new self;
@@ -87,6 +98,7 @@ public static function with(
 
         null !== $apiKey && $self['apiKey'] = $apiKey;
         null !== $baseURL && $self['baseURL'] = $baseURL;
+        null !== $headers && $self['headers'] = $headers;
         null !== $provider && $self['provider'] = $provider;
 
         return $self;
@@ -125,6 +137,19 @@ public function withBaseURL(string $baseURL): self
         return $self;
     }
 
+    /**
+     * Custom headers sent with every request to the model provider.
+     *
+     * @param array<string,string> $headers
+     */
+    public function withHeaders(array $headers): self
+    {
+        $self = clone $this;
+        $self['headers'] = $headers;
+
+        return $self;
+    }
+
     /**
      * AI provider for the model (or provide a baseURL endpoint instead).
      *

tests/Services/SessionsTest.php

@@ -72,6 +72,7 @@ public function testActWithOptionalParams(): void
                     'modelName' => 'openai/gpt-5-nano',
                     'apiKey' => 'sk-some-openai-api-key',
                     'baseURL' => 'https://api.openai.com/v1',
+                    'headers' => ['foo' => 'string'],
                     'provider' => 'openai',
                 ],
                 'timeout' => 30000,
@@ -138,13 +139,15 @@ public function testExecuteWithOptionalParams(): void
                     'modelName' => 'openai/gpt-5-nano',
                     'apiKey' => 'sk-some-openai-api-key',
                     'baseURL' => 'https://api.openai.com/v1',
+                    'headers' => ['foo' => 'string'],
                     'provider' => 'openai',
                 ],
                 'mode' => 'cua',
                 'model' => [
                     'modelName' => 'openai/gpt-5-nano',
                     'apiKey' => 'sk-some-openai-api-key',
                     'baseURL' => 'https://api.openai.com/v1',
+                    'headers' => ['foo' => 'string'],
                     'provider' => 'openai',
                 ],
                 'provider' => 'openai',