release: 3.6.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.5.0"
+  ".": "3.6.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 7
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-2132f9afd90a3b3c35b772f0de3ac8432cfe46ecfa22ec9c1ed4a3d0eda1ad41.yml
-openapi_spec_hash: 6da568c2948d8ab6000db4291e15a033
-config_hash: 64c9cc393de93af70e11dbf0b1ba9388
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-1c405024b4a17886e921871250a445362463b7ae6070cacc3d1927d59036730c.yml
+openapi_spec_hash: c4ea3735257a48ed105002eb7aaa095a
+config_hash: 85d56c7c196269badbd0b4a9dfb28d45

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.6.0 (2026-01-21)
+
+Full Changelog: [v3.5.0...v3.6.0](https://github.com/browserbase/stagehand-php/compare/v3.5.0...v3.6.0)
+
+### Features
+
+* add v3 integration tests matching cloud exactly ([720a537](https://github.com/browserbase/stagehand-php/commit/720a537000903162af127af6c5ba6d3c97d4a0dd))
+
 ## 3.5.0 (2026-01-21)
 
 Full Changelog: [v3.4.0...v3.5.0](https://github.com/browserbase/stagehand-php/compare/v3.4.0...v3.5.0)

src/Sessions/SessionActParams/Options.php

@@ -10,10 +10,11 @@
 use Stagehand\Sessions\ModelConfig;
 
 /**
- * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ * @phpstan-import-type ModelVariants from \Stagehand\Sessions\SessionActParams\Options\Model
+ * @phpstan-import-type ModelShape from \Stagehand\Sessions\SessionActParams\Options\Model
  *
  * @phpstan-type OptionsShape = array{
- *   model?: null|ModelConfig|ModelConfigShape,
+ *   model?: ModelShape|null,
  *   timeout?: float|null,
  *   variables?: array<string,string>|null,
  * }
@@ -23,8 +24,13 @@ final class Options implements BaseModel
     /** @use SdkModel<OptionsShape> */
     use SdkModel;
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @var ModelVariants|null $model
+     */
     #[Optional]
-    public ?ModelConfig $model;
+    public string|ModelConfig|null $model;
 
     /**
      * Timeout in ms for the action.
@@ -50,11 +56,11 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
-     * @param ModelConfig|ModelConfigShape|null $model
+     * @param ModelShape|null $model
      * @param array<string,string>|null $variables
      */
     public static function with(
-        ModelConfig|array|null $model = null,
+        string|ModelConfig|array|null $model = null,
         ?float $timeout = null,
         ?array $variables = null,
     ): self {
@@ -68,9 +74,11 @@ public static function with(
     }
 
     /**
-     * @param ModelConfig|ModelConfigShape $model
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @param ModelShape $model
      */
-    public function withModel(ModelConfig|array $model): self
+    public function withModel(string|ModelConfig|array $model): self
     {
         $self = clone $this;
         $self['model'] = $model;

src/Sessions/SessionActParams/Options/Model.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionActParams\Options;
+
+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').
+ *
+ * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ *
+ * @phpstan-type ModelVariants = string|ModelConfig
+ * @phpstan-type ModelShape = ModelVariants|ModelConfigShape
+ */
+final class Model implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return [ModelConfig::class, 'string'];
+    }
+}

src/Sessions/SessionExecuteParams/AgentConfig.php

@@ -11,11 +11,12 @@
 use Stagehand\Sessions\SessionExecuteParams\AgentConfig\Provider;
 
 /**
- * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ * @phpstan-import-type ModelVariants from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\Model
+ * @phpstan-import-type ModelShape from \Stagehand\Sessions\SessionExecuteParams\AgentConfig\Model
  *
  * @phpstan-type AgentConfigShape = array{
  *   cua?: bool|null,
- *   model?: null|ModelConfig|ModelConfigShape,
+ *   model?: ModelShape|null,
  *   provider?: null|Provider|value-of<Provider>,
  *   systemPrompt?: string|null,
  * }
@@ -31,8 +32,13 @@ final class AgentConfig implements BaseModel
     #[Optional]
     public ?bool $cua;
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @var ModelVariants|null $model
+     */
     #[Optional]
-    public ?ModelConfig $model;
+    public string|ModelConfig|null $model;
 
     /**
      * AI provider for the agent (legacy, use model: openai/gpt-5-nano instead).
@@ -58,12 +64,12 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
-     * @param ModelConfig|ModelConfigShape|null $model
+     * @param ModelShape|null $model
      * @param Provider|value-of<Provider>|null $provider
      */
     public static function with(
         ?bool $cua = null,
-        ModelConfig|array|null $model = null,
+        string|ModelConfig|array|null $model = null,
         Provider|string|null $provider = null,
         ?string $systemPrompt = null,
     ): self {
@@ -89,9 +95,11 @@ public function withCua(bool $cua): self
     }
 
     /**
-     * @param ModelConfig|ModelConfigShape $model
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @param ModelShape $model
      */
-    public function withModel(ModelConfig|array $model): self
+    public function withModel(string|ModelConfig|array $model): self
     {
         $self = clone $this;
         $self['model'] = $model;

src/Sessions/SessionExecuteParams/AgentConfig/Model.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').
+ *
+ * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ *
+ * @phpstan-type ModelVariants = string|ModelConfig
+ * @phpstan-type ModelShape = ModelVariants|ModelConfigShape
+ */
+final class Model implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return [ModelConfig::class, 'string'];
+    }
+}

src/Sessions/SessionExtractParams/Options.php

@@ -10,21 +10,25 @@
 use Stagehand\Sessions\ModelConfig;
 
 /**
- * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ * @phpstan-import-type ModelVariants from \Stagehand\Sessions\SessionExtractParams\Options\Model
+ * @phpstan-import-type ModelShape from \Stagehand\Sessions\SessionExtractParams\Options\Model
  *
  * @phpstan-type OptionsShape = array{
- *   model?: null|ModelConfig|ModelConfigShape,
- *   selector?: string|null,
- *   timeout?: float|null,
+ *   model?: ModelShape|null, selector?: string|null, timeout?: float|null
  * }
  */
 final class Options implements BaseModel
 {
     /** @use SdkModel<OptionsShape> */
     use SdkModel;
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @var ModelVariants|null $model
+     */
     #[Optional]
-    public ?ModelConfig $model;
+    public string|ModelConfig|null $model;
 
     /**
      * CSS selector to scope extraction to a specific element.
@@ -48,10 +52,10 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
-     * @param ModelConfig|ModelConfigShape|null $model
+     * @param ModelShape|null $model
      */
     public static function with(
-        ModelConfig|array|null $model = null,
+        string|ModelConfig|array|null $model = null,
         ?string $selector = null,
         ?float $timeout = null,
     ): self {
@@ -65,9 +69,11 @@ public static function with(
     }
 
     /**
-     * @param ModelConfig|ModelConfigShape $model
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @param ModelShape $model
      */
-    public function withModel(ModelConfig|array $model): self
+    public function withModel(string|ModelConfig|array $model): self
     {
         $self = clone $this;
         $self['model'] = $model;

src/Sessions/SessionExtractParams/Options/Model.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExtractParams\Options;
+
+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').
+ *
+ * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ *
+ * @phpstan-type ModelVariants = string|ModelConfig
+ * @phpstan-type ModelShape = ModelVariants|ModelConfigShape
+ */
+final class Model implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return [ModelConfig::class, 'string'];
+    }
+}

src/Sessions/SessionObserveParams/Options.php

@@ -10,21 +10,25 @@
 use Stagehand\Sessions\ModelConfig;
 
 /**
- * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ * @phpstan-import-type ModelVariants from \Stagehand\Sessions\SessionObserveParams\Options\Model
+ * @phpstan-import-type ModelShape from \Stagehand\Sessions\SessionObserveParams\Options\Model
  *
  * @phpstan-type OptionsShape = array{
- *   model?: null|ModelConfig|ModelConfigShape,
- *   selector?: string|null,
- *   timeout?: float|null,
+ *   model?: ModelShape|null, selector?: string|null, timeout?: float|null
  * }
  */
 final class Options implements BaseModel
 {
     /** @use SdkModel<OptionsShape> */
     use SdkModel;
 
+    /**
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @var ModelVariants|null $model
+     */
     #[Optional]
-    public ?ModelConfig $model;
+    public string|ModelConfig|null $model;
 
     /**
      * CSS selector to scope observation to a specific element.
@@ -48,10 +52,10 @@ public function __construct()
      *
      * You must use named parameters to construct any parameters with a default value.
      *
-     * @param ModelConfig|ModelConfigShape|null $model
+     * @param ModelShape|null $model
      */
     public static function with(
-        ModelConfig|array|null $model = null,
+        string|ModelConfig|array|null $model = null,
         ?string $selector = null,
         ?float $timeout = null,
     ): self {
@@ -65,9 +69,11 @@ public static function with(
     }
 
     /**
-     * @param ModelConfig|ModelConfigShape $model
+     * Model configuration object or model name string (e.g., 'openai/gpt-5-nano').
+     *
+     * @param ModelShape $model
      */
-    public function withModel(ModelConfig|array $model): self
+    public function withModel(string|ModelConfig|array $model): self
     {
         $self = clone $this;
         $self['model'] = $model;

src/Sessions/SessionObserveParams/Options/Model.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionObserveParams\Options;
+
+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').
+ *
+ * @phpstan-import-type ModelConfigShape from \Stagehand\Sessions\ModelConfig
+ *
+ * @phpstan-type ModelVariants = string|ModelConfig
+ * @phpstan-type ModelShape = ModelVariants|ModelConfigShape
+ */
+final class Model 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.5.0';
+const VERSION = '3.6.0';
 // x-release-please-end