release: 3.11.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.10.0"
+  ".": "3.11.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-43e6dd4ce19381de488d296e9036fea15bfea9a6f946cf8ccf4e02aecc8fb765.yml
-openapi_spec_hash: f736e7a8acea0d73e1031c86ea803246
-config_hash: b375728ccf7d33287335852f4f59c293
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-8fbb3fa8f3a37c1c7408de427fe125aadec49f705e8e30d191601a9b69c4cc41.yml
+openapi_spec_hash: 48b4dfac35a842d7fb0d228caf87544e
+config_hash: 242651c4871c2869ba3c2e3d337505b9

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.11.0 (2026-01-29)
+
+Full Changelog: [v3.10.0...v3.11.0](https://github.com/browserbase/stagehand-php/compare/v3.10.0...v3.11.0)
+
+### Features
+
+* Add executionModel serialization to api client ([bd33c5a](https://github.com/browserbase/stagehand-php/commit/bd33c5a50a358970421a391050fb0be1939348b1))
+
 ## 3.10.0 (2026-01-29)
 
 Full Changelog: [v3.9.1...v3.10.0](https://github.com/browserbase/stagehand-php/compare/v3.9.1...v3.10.0)

README.md

@@ -77,10 +77,22 @@ The REST API documentation can be found on [docs.stagehand.dev](https://docs.sta
 
 ## Installation
 
+To use this package, install via Composer by adding the following to your application's `composer.json`:
+
 <!-- x-release-please-start-version -->
 
-```
-composer require "browserbase/stagehand 3.10.0"
+```json
+{
+  "repositories": [
+    {
+      "type": "vcs",
+      "url": "git@github.com:browserbase/stagehand-php.git"
+    }
+  ],
+  "require": {
+    "browserbase/stagehand": "dev-main"
+  }
+}
 ```
 
 <!-- x-release-please-end -->

src/SSEStream.php

@@ -49,7 +49,7 @@ private function parsedGenerator(): \Generator
             }
 
             if ($data = $row['data'] ?? '') {
-                if (str_starts_with($data, needle: '{"data":{"status":"finished"')) {
+                if (str_starts_with($data, needle: 'finished')) {
                     $done = true;
 
                     continue;

src/Sessions/SessionExecuteParams/AgentConfig.php

@@ -12,11 +12,14 @@
 use Stagehand\Sessions\SessionExecuteParams\AgentConfig\Provider;
 
 /**
+ * @phpstan-import-type ExecutionModelVariants from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\ExecutionModel
  * @phpstan-import-type ModelVariants from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\Model
+ * @phpstan-import-type ExecutionModelShape from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\ExecutionModel
  * @phpstan-import-type ModelShape from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\Model
  *
  * @phpstan-type AgentConfigShape = array{
  *   cua?: bool|null,
+ *   executionModel?: ExecutionModelShape|null,
  *   mode?: null|Mode|value-of<Mode>,
  *   model?: ModelShape|null,
  *   provider?: null|Provider|value-of<Provider>,
@@ -34,6 +37,14 @@ final class AgentConfig implements BaseModel
     #[Optional]
     public ?bool $cua;
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for tool execution (observe/act calls within agent tools). If not specified, inherits from the main model configuration.
+     *
+     * @var ExecutionModelVariants|null $executionModel
+     */
+    #[Optional]
+    public string|ModelConfig|null $executionModel;
+
     /**
      * Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
      *
@@ -74,12 +85,14 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
+     * @param ExecutionModelShape|null $executionModel
      * @param Mode|value-of<Mode>|null $mode
      * @param ModelShape|null $model
      * @param Provider|value-of<Provider>|null $provider
      */
     public static function with(
         ?bool $cua = null,
+        string|ModelConfig|array|null $executionModel = null,
         Mode|string|null $mode = null,
         string|ModelConfig|array|null $model = null,
         Provider|string|null $provider = null,
@@ -88,6 +101,7 @@ public static function with(
         $self = new self;
 
         null !== $cua && $self['cua'] = $cua;
+        null !== $executionModel && $self['executionModel'] = $executionModel;
         null !== $mode && $self['mode'] = $mode;
         null !== $model && $self['model'] = $model;
         null !== $provider && $self['provider'] = $provider;
@@ -107,6 +121,20 @@ public function withCua(bool $cua): self
         return $self;
     }
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for tool execution (observe/act calls within agent tools). If not specified, inherits from the main model configuration.
+     *
+     * @param ExecutionModelShape $executionModel
+     */
+    public function withExecutionModel(
+        string|ModelConfig|array $executionModel
+    ): self {
+        $self = clone $this;
+        $self['executionModel'] = $executionModel;
+
+        return $self;
+    }
+
     /**
      * Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
      *

src/Sessions/SessionExecuteParams/AgentConfig/ExecutionModel.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExecuteParams\AgentConfig;
+
+use Stagehand\Core\Concerns\SdkUnion;
+use Stagehand\Core\Conversion\Contracts\Converter;
+use Stagehand\Core\Conversion\Contracts\ConverterSource;
+use Stagehand\Sessions\ModelConfig;
+
+/**
+ * Model configuration object or model name string (e.g., 'openai/gpt-5-nano') for tool execution (observe/act calls within agent tools). If not specified, inherits from the main model configuration.
+ *
+ * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ *
+ * @phpstan-type ExecutionModelVariants = string|ModelConfig
+ * @phpstan-type ExecutionModelShape = ExecutionModelVariants|ModelConfigShape
+ */
+final class ExecutionModel implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return [ModelConfig::class, 'string'];
+    }
+}

src/Version.php

@@ -5,5 +5,5 @@
 namespace Stagehand;
 
 // x-release-please-start-version
-const VERSION = '3.10.0';
+const VERSION = '3.11.0';
 // x-release-please-end

tests/Services/SessionsTest.php

@@ -128,6 +128,12 @@ public function testExecuteWithOptionalParams(): void
             'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
             agentConfig: [
                 'cua' => true,
+                'executionModel' => [
+                    'modelName' => 'openai/gpt-5-nano',
+                    'apiKey' => 'sk-some-openai-api-key',
+                    'baseURL' => 'https://api.openai.com/v1',
+                    'provider' => 'openai',
+                ],
                 'mode' => 'cua',
                 'model' => [
                     'modelName' => 'openai/gpt-5-nano',