feat: remove experimental requirement on agent variables (#2079)

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/stagehand-f10429ab9f004c9a7f9f362d7fa82915e0dc04b1ba08a7bc9fd442ed5854cc77.yml
-openapi_spec_hash: 818f2e6e7eb5eb6f21f346b0b9828dce
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase/stagehand-6f6bfb81d092f30a5e2005328c97d61b9ea36132bb19e9e79e55294b9534ce20.yml
+openapi_spec_hash: f3fc1e3688a38dc2c28f7178f7d534e5
 config_hash: 1fb12ae9b478488bc1e56bfbdc210b01

src/Sessions/SessionExecuteParams/ExecuteOptions.php

@@ -8,14 +8,19 @@
 use Stagehand\Core\Attributes\Required;
 use Stagehand\Core\Concerns\SdkModel;
 use Stagehand\Core\Contracts\BaseModel;
+use Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable;
 
 /**
+ * @phpstan-import-type VariableVariants from \Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable
+ * @phpstan-import-type VariableShape from \Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable
+ *
  * @phpstan-type ExecuteOptionsShape = array{
  *   instruction: string,
  *   highlightCursor?: bool|null,
  *   maxSteps?: float|null,
  *   toolTimeout?: float|null,
  *   useSearch?: bool|null,
+ *   variables?: array<string,VariableShape>|null,
  * }
  */
 final class ExecuteOptions implements BaseModel
@@ -53,6 +58,14 @@ final class ExecuteOptions implements BaseModel
     #[Optional]
     public ?bool $useSearch;
 
+    /**
+     * Variables available to the agent via %variableName% syntax in supported tools.
+     *
+     * @var array<string,VariableVariants>|null $variables
+     */
+    #[Optional(map: Variable::class)]
+    public ?array $variables;
+
     /**
      * `new ExecuteOptions()` is missing required properties by the API.
      *
@@ -76,13 +89,16 @@ public function __construct()
      * Construct an instance from the required parameters.
      *
      * You must use named parameters to construct any parameters with a default value.
+     *
+     * @param array<string,VariableShape>|null $variables
      */
     public static function with(
         string $instruction,
         ?bool $highlightCursor = null,
         ?float $maxSteps = null,
         ?float $toolTimeout = null,
         ?bool $useSearch = null,
+        ?array $variables = null,
     ): self {
         $self = new self;
 
@@ -92,6 +108,7 @@ public static function with(
         null !== $maxSteps && $self['maxSteps'] = $maxSteps;
         null !== $toolTimeout && $self['toolTimeout'] = $toolTimeout;
         null !== $useSearch && $self['useSearch'] = $useSearch;
+        null !== $variables && $self['variables'] = $variables;
 
         return $self;
     }
@@ -150,4 +167,17 @@ public function withUseSearch(bool $useSearch): self
 
         return $self;
     }
+
+    /**
+     * Variables available to the agent via %variableName% syntax in supported tools.
+     *
+     * @param array<string,VariableShape> $variables
+     */
+    public function withVariables(array $variables): self
+    {
+        $self = clone $this;
+        $self['variables'] = $variables;
+
+        return $self;
+    }
 }

src/Sessions/SessionExecuteParams/ExecuteOptions/Variable.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExecuteParams\ExecuteOptions;
+
+use Stagehand\Core\Concerns\SdkUnion;
+use Stagehand\Core\Conversion\Contracts\Converter;
+use Stagehand\Core\Conversion\Contracts\ConverterSource;
+use Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable\UnionMember3;
+
+/**
+ * @phpstan-import-type UnionMember3Shape from \Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable\UnionMember3
+ *
+ * @phpstan-type VariableVariants = string|float|bool|UnionMember3
+ * @phpstan-type VariableShape = VariableVariants|UnionMember3Shape
+ */
+final class Variable implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return ['string', 'float', 'bool', UnionMember3::class];
+    }
+}

src/Sessions/SessionExecuteParams/ExecuteOptions/Variable/UnionMember3.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable;
+
+use Stagehand\Core\Attributes\Optional;
+use Stagehand\Core\Attributes\Required;
+use Stagehand\Core\Concerns\SdkModel;
+use Stagehand\Core\Contracts\BaseModel;
+
+/**
+ * @phpstan-import-type ValueVariants from \Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable\UnionMember3\Value
+ * @phpstan-import-type ValueShape from \Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable\UnionMember3\Value
+ *
+ * @phpstan-type UnionMember3Shape = array{
+ *   value: ValueShape, description?: string|null
+ * }
+ */
+final class UnionMember3 implements BaseModel
+{
+    /** @use SdkModel<UnionMember3Shape> */
+    use SdkModel;
+
+    /** @var ValueVariants $value */
+    #[Required]
+    public string|float|bool $value;
+
+    #[Optional]
+    public ?string $description;
+
+    /**
+     * `new UnionMember3()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * UnionMember3::with(value: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new UnionMember3)->withValue(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     *
+     * @param ValueShape $value
+     */
+    public static function with(
+        string|float|bool $value,
+        ?string $description = null
+    ): self {
+        $self = new self;
+
+        $self['value'] = $value;
+
+        null !== $description && $self['description'] = $description;
+
+        return $self;
+    }
+
+    /**
+     * @param ValueShape $value
+     */
+    public function withValue(string|float|bool $value): self
+    {
+        $self = clone $this;
+        $self['value'] = $value;
+
+        return $self;
+    }
+
+    public function withDescription(string $description): self
+    {
+        $self = clone $this;
+        $self['description'] = $description;
+
+        return $self;
+    }
+}

src/Sessions/SessionExecuteParams/ExecuteOptions/Variable/UnionMember3/Value.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExecuteParams\ExecuteOptions\Variable\UnionMember3;
+
+use Stagehand\Core\Concerns\SdkUnion;
+use Stagehand\Core\Conversion\Contracts\Converter;
+use Stagehand\Core\Conversion\Contracts\ConverterSource;
+
+/**
+ * @phpstan-type ValueVariants = string|float|bool
+ * @phpstan-type ValueShape = ValueVariants
+ */
+final class Value implements ConverterSource
+{
+    use SdkUnion;
+
+    /**
+     * @return list<string|Converter|ConverterSource>|array<string,string|Converter|ConverterSource>
+     */
+    public static function variants(): array
+    {
+        return ['string', 'float', 'bool'];
+    }
+}

tests/Services/SessionsTest.php

@@ -159,6 +159,7 @@ public function testExecuteWithOptionalParams(): void
                 'maxSteps' => 20,
                 'toolTimeout' => 30000,
                 'useSearch' => true,
+                'variables' => ['foo' => 'string'],
             ],
             frameID: 'frameId',
             shouldCache: true,