feat: [feat]: add support for local caching of agent when using api (2)

Author: stainless-app[bot]

.stats.yml

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

src/ServiceContracts/SessionsContract.php

@@ -103,6 +103,7 @@ public function end(
      * @param AgentConfig|AgentConfigShape $agentConfig Body param
      * @param ExecuteOptions|ExecuteOptionsShape $executeOptions Body param
      * @param string|null $frameID Body param: Target frame ID for the agent
+     * @param bool $shouldCache Body param: If true, the server captures a cache entry and returns it to the client
      * @param \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|value-of<\Stagehand\Sessions\SessionExecuteParams\XStreamResponse> $xStreamResponse Header param: Whether to stream the response via SSE
      * @param RequestOpts|null $requestOptions
      *
@@ -113,6 +114,7 @@ public function execute(
         AgentConfig|array $agentConfig,
         ExecuteOptions|array $executeOptions,
         ?string $frameID = null,
+        ?bool $shouldCache = null,
         \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|string|null $xStreamResponse = null,
         RequestOptions|array|null $requestOptions = null,
     ): SessionExecuteResponse;
@@ -124,6 +126,7 @@ public function execute(
      * @param AgentConfig|AgentConfigShape $agentConfig Body param
      * @param ExecuteOptions|ExecuteOptionsShape $executeOptions Body param
      * @param string|null $frameID Body param: Target frame ID for the agent
+     * @param bool $shouldCache Body param: If true, the server captures a cache entry and returns it to the client
      * @param \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|value-of<\Stagehand\Sessions\SessionExecuteParams\XStreamResponse> $xStreamResponse Header param: Whether to stream the response via SSE
      * @param RequestOpts|null $requestOptions
      *
@@ -136,6 +139,7 @@ public function executeStream(
         AgentConfig|array $agentConfig,
         ExecuteOptions|array $executeOptions,
         ?string $frameID = null,
+        ?bool $shouldCache = null,
         \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|string|null $xStreamResponse = null,
         RequestOptions|array|null $requestOptions = null,
     ): BaseStream;

src/Services/SessionsRawService.php

@@ -200,6 +200,7 @@ public function end(
      *   agentConfig: AgentConfig|AgentConfigShape,
      *   executeOptions: ExecuteOptions|ExecuteOptionsShape,
      *   frameID?: string|null,
+     *   shouldCache?: bool,
      *   xStreamResponse?: SessionExecuteParams\XStreamResponse|value-of<SessionExecuteParams\XStreamResponse>,
      * }|SessionExecuteParams $params
      * @param RequestOpts|null $requestOptions
@@ -244,6 +245,7 @@ public function execute(
      *   agentConfig: AgentConfig|AgentConfigShape,
      *   executeOptions: ExecuteOptions|ExecuteOptionsShape,
      *   frameID?: string|null,
+     *   shouldCache?: bool,
      *   xStreamResponse?: SessionExecuteParams\XStreamResponse|value-of<SessionExecuteParams\XStreamResponse>,
      * }|SessionExecuteParams $params
      * @param RequestOpts|null $requestOptions

src/Services/SessionsService.php

@@ -160,6 +160,7 @@ public function end(
      * @param AgentConfig|AgentConfigShape $agentConfig Body param
      * @param ExecuteOptions|ExecuteOptionsShape $executeOptions Body param
      * @param string|null $frameID Body param: Target frame ID for the agent
+     * @param bool $shouldCache Body param: If true, the server captures a cache entry and returns it to the client
      * @param \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|value-of<\Stagehand\Sessions\SessionExecuteParams\XStreamResponse> $xStreamResponse Header param: Whether to stream the response via SSE
      * @param RequestOpts|null $requestOptions
      *
@@ -170,6 +171,7 @@ public function execute(
         AgentConfig|array $agentConfig,
         ExecuteOptions|array $executeOptions,
         ?string $frameID = null,
+        ?bool $shouldCache = null,
         \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|string|null $xStreamResponse = null,
         RequestOptions|array|null $requestOptions = null,
     ): SessionExecuteResponse {
@@ -178,6 +180,7 @@ public function execute(
                 'agentConfig' => $agentConfig,
                 'executeOptions' => $executeOptions,
                 'frameID' => $frameID,
+                'shouldCache' => $shouldCache,
                 'xStreamResponse' => $xStreamResponse,
             ],
         );
@@ -195,6 +198,7 @@ public function execute(
      * @param AgentConfig|AgentConfigShape $agentConfig Body param
      * @param ExecuteOptions|ExecuteOptionsShape $executeOptions Body param
      * @param string|null $frameID Body param: Target frame ID for the agent
+     * @param bool $shouldCache Body param: If true, the server captures a cache entry and returns it to the client
      * @param \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|value-of<\Stagehand\Sessions\SessionExecuteParams\XStreamResponse> $xStreamResponse Header param: Whether to stream the response via SSE
      * @param RequestOpts|null $requestOptions
      *
@@ -207,6 +211,7 @@ public function executeStream(
         AgentConfig|array $agentConfig,
         ExecuteOptions|array $executeOptions,
         ?string $frameID = null,
+        ?bool $shouldCache = null,
         \Stagehand\Sessions\SessionExecuteParams\XStreamResponse|string|null $xStreamResponse = null,
         RequestOptions|array|null $requestOptions = null,
     ): BaseStream {
@@ -215,6 +220,7 @@ public function executeStream(
                 'agentConfig' => $agentConfig,
                 'executeOptions' => $executeOptions,
                 'frameID' => $frameID,
+                'shouldCache' => $shouldCache,
                 'xStreamResponse' => $xStreamResponse,
             ],
         );

src/Sessions/SessionExecuteParams.php

@@ -25,6 +25,7 @@
  *   agentConfig: AgentConfig|AgentConfigShape,
  *   executeOptions: ExecuteOptions|ExecuteOptionsShape,
  *   frameID?: string|null,
+ *   shouldCache?: bool|null,
  *   xStreamResponse?: null|XStreamResponse|value-of<XStreamResponse>,
  * }
  */
@@ -46,6 +47,12 @@ final class SessionExecuteParams implements BaseModel
     #[Optional('frameId', nullable: true)]
     public ?string $frameID;
 
+    /**
+     * If true, the server captures a cache entry and returns it to the client.
+     */
+    #[Optional]
+    public ?bool $shouldCache;
+
     /**
      * Whether to stream the response via SSE.
      *
@@ -86,6 +93,7 @@ public static function with(
         AgentConfig|array $agentConfig,
         ExecuteOptions|array $executeOptions,
         ?string $frameID = null,
+        ?bool $shouldCache = null,
         XStreamResponse|string|null $xStreamResponse = null,
     ): self {
         $self = new self;
@@ -94,6 +102,7 @@ public static function with(
         $self['executeOptions'] = $executeOptions;
 
         null !== $frameID && $self['frameID'] = $frameID;
+        null !== $shouldCache && $self['shouldCache'] = $shouldCache;
         null !== $xStreamResponse && $self['xStreamResponse'] = $xStreamResponse;
 
         return $self;
@@ -133,6 +142,17 @@ public function withFrameID(?string $frameID): self
         return $self;
     }
 
+    /**
+     * If true, the server captures a cache entry and returns it to the client.
+     */
+    public function withShouldCache(bool $shouldCache): self
+    {
+        $self = clone $this;
+        $self['shouldCache'] = $shouldCache;
+
+        return $self;
+    }
+
     /**
      * Whether to stream the response via SSE.
      *

src/Sessions/SessionExecuteResponse/Data.php

@@ -4,15 +4,20 @@
 
 namespace Stagehand\Sessions\SessionExecuteResponse;
 
+use Stagehand\Core\Attributes\Optional;
 use Stagehand\Core\Attributes\Required;
 use Stagehand\Core\Concerns\SdkModel;
 use Stagehand\Core\Contracts\BaseModel;
+use Stagehand\Sessions\SessionExecuteResponse\Data\CacheEntry;
 use Stagehand\Sessions\SessionExecuteResponse\Data\Result;
 
 /**
  * @phpstan-import-type ResultShape from \Stagehand\Sessions\SessionExecuteResponse\Data\Result
+ * @phpstan-import-type CacheEntryShape from \Stagehand\Sessions\SessionExecuteResponse\Data\CacheEntry
  *
- * @phpstan-type DataShape = array{result: Result|ResultShape}
+ * @phpstan-type DataShape = array{
+ *   result: Result|ResultShape, cacheEntry?: null|CacheEntry|CacheEntryShape
+ * }
  */
 final class Data implements BaseModel
 {
@@ -22,6 +27,9 @@ final class Data implements BaseModel
     #[Required]
     public Result $result;
 
+    #[Optional]
+    public ?CacheEntry $cacheEntry;
+
     /**
      * `new Data()` is missing required properties by the API.
      *
@@ -47,13 +55,18 @@ public function __construct()
      * You must use named parameters to construct any parameters with a default value.
      *
      * @param Result|ResultShape $result
+     * @param CacheEntry|CacheEntryShape|null $cacheEntry
      */
-    public static function with(Result|array $result): self
-    {
+    public static function with(
+        Result|array $result,
+        CacheEntry|array|null $cacheEntry = null
+    ): self {
         $self = new self;
 
         $self['result'] = $result;
 
+        null !== $cacheEntry && $self['cacheEntry'] = $cacheEntry;
+
         return $self;
     }
 
@@ -67,4 +80,15 @@ public function withResult(Result|array $result): self
 
         return $self;
     }
+
+    /**
+     * @param CacheEntry|CacheEntryShape $cacheEntry
+     */
+    public function withCacheEntry(CacheEntry|array $cacheEntry): self
+    {
+        $self = clone $this;
+        $self['cacheEntry'] = $cacheEntry;
+
+        return $self;
+    }
 }

src/Sessions/SessionExecuteResponse/Data/CacheEntry.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stagehand\Sessions\SessionExecuteResponse\Data;
+
+use Stagehand\Core\Attributes\Required;
+use Stagehand\Core\Concerns\SdkModel;
+use Stagehand\Core\Contracts\BaseModel;
+
+/**
+ * @phpstan-type CacheEntryShape = array{cacheKey: string, entry: mixed}
+ */
+final class CacheEntry implements BaseModel
+{
+    /** @use SdkModel<CacheEntryShape> */
+    use SdkModel;
+
+    /**
+     * Opaque cache identifier computed from instruction, URL, options, and config.
+     */
+    #[Required]
+    public string $cacheKey;
+
+    /**
+     * Serialized cache entry that can be written to disk.
+     */
+    #[Required]
+    public mixed $entry;
+
+    /**
+     * `new CacheEntry()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * CacheEntry::with(cacheKey: ..., entry: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new CacheEntry)->withCacheKey(...)->withEntry(...)
+     * ```
+     */
+    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.
+     */
+    public static function with(string $cacheKey, mixed $entry): self
+    {
+        $self = new self;
+
+        $self['cacheKey'] = $cacheKey;
+        $self['entry'] = $entry;
+
+        return $self;
+    }
+
+    /**
+     * Opaque cache identifier computed from instruction, URL, options, and config.
+     */
+    public function withCacheKey(string $cacheKey): self
+    {
+        $self = clone $this;
+        $self['cacheKey'] = $cacheKey;
+
+        return $self;
+    }
+
+    /**
+     * Serialized cache entry that can be written to disk.
+     */
+    public function withEntry(mixed $entry): self
+    {
+        $self = clone $this;
+        $self['entry'] = $entry;
+
+        return $self;
+    }
+}

tests/Services/SessionsTest.php

@@ -142,6 +142,7 @@ public function testExecuteWithOptionalParams(): void
                 'maxSteps' => 20,
             ],
             frameID: 'frameId',
+            shouldCache: true,
             xStreamResponse: 'true',
         );