diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 2437b41..bf0d036 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "3.4.0" + ".": "3.5.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 1c9fda1..babf0f2 100644 --- a/.stats.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index c34efae..069d313 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 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) + +### Features + +* [feat]: add support for local caching of agent when using api (2) ([ee4a13f](https://github.com/browserbase/stagehand-php/commit/ee4a13fd656e552d2f889e5da2be151f4d93c970)) + ## 3.4.0 (2026-01-20) Full Changelog: [v3.3.0...v3.4.0](https://github.com/browserbase/stagehand-php/compare/v3.3.0...v3.4.0) diff --git a/src/ServiceContracts/SessionsContract.php b/src/ServiceContracts/SessionsContract.php index 2cc3e51..0fb46ad 100644 --- a/src/ServiceContracts/SessionsContract.php +++ b/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; diff --git a/src/Services/SessionsRawService.php b/src/Services/SessionsRawService.php index 50c2bea..7319162 100644 --- a/src/Services/SessionsRawService.php +++ b/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 $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 $params * @param RequestOpts|null $requestOptions diff --git a/src/Services/SessionsService.php b/src/Services/SessionsService.php index 82577f7..12ec98b 100644 --- a/src/Services/SessionsService.php +++ b/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, ], ); diff --git a/src/Sessions/SessionExecuteParams.php b/src/Sessions/SessionExecuteParams.php index f244a83..f50aa41 100644 --- a/src/Sessions/SessionExecuteParams.php +++ b/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, * } */ @@ -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. * diff --git a/src/Sessions/SessionExecuteResponse/Data.php b/src/Sessions/SessionExecuteResponse/Data.php index 1e26019..7899672 100644 --- a/src/Sessions/SessionExecuteResponse/Data.php +++ b/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; + } } diff --git a/src/Sessions/SessionExecuteResponse/Data/CacheEntry.php b/src/Sessions/SessionExecuteResponse/Data/CacheEntry.php new file mode 100644 index 0000000..75af2e9 --- /dev/null +++ b/src/Sessions/SessionExecuteResponse/Data/CacheEntry.php @@ -0,0 +1,86 @@ + */ + 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; + } +} diff --git a/src/Version.php b/src/Version.php index e906129..5d53111 100644 --- a/src/Version.php +++ b/src/Version.php @@ -5,5 +5,5 @@ namespace Stagehand; // x-release-please-start-version -const VERSION = '3.4.0'; +const VERSION = '3.5.0'; // x-release-please-end diff --git a/tests/Services/SessionsTest.php b/tests/Services/SessionsTest.php index ab5749d..a582d33 100644 --- a/tests/Services/SessionsTest.php +++ b/tests/Services/SessionsTest.php @@ -142,6 +142,7 @@ public function testExecuteWithOptionalParams(): void 'maxSteps' => 20, ], frameID: 'frameId', + shouldCache: true, xStreamResponse: 'true', );