@browserbasehq/orca 3.0.7-alpha-1 → 3.0.8-ca-ching

package/README.md

@@ -20,10 +20,10 @@
       <img alt="MIT License" src="../../media/light_license.svg" />
     </picture>
   </a>
-  <a href="https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ">
+  <a href="https://stagehand.dev/discord">
     <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_slack.svg" />
-      <img alt="Slack Community" src="../../media/light_slack.svg" />
+      <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_discord.svg" />
+      <img alt="Discord Community" src="../../media/light_discord.svg" />
     </picture>
   </a>
 </p>
@@ -136,10 +136,10 @@ In your project's `package.json` set:
 
 ## Contributing
 
-> [!NOTE]  
-> We highly value contributions to Stagehand! For questions or support, please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ).
+> [!NOTE]
+> We highly value contributions to Stagehand! For questions or support, please join our [Discord community](https://stagehand.dev/discord).
 
-At a high level, we're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, **bug fixes and small improvements are the best way to get started**. For more involved features, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ) before starting to ensure that your contribution aligns with our goals.
+At a high level, we're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, **bug fixes and small improvements are the best way to get started**. For more involved features, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Discord community](https://stagehand.dev/discord) before starting to ensure that your contribution aligns with our goals.
 
 <!-- For more information, please see our [Contributing Guide](https://docs.stagehand.dev/examples/contributing). -->
 

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { ClientOptions as ClientOptions$1 } from 'openai';
 import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
 import * as ai from 'ai';
 import { ToolSet, ModelMessage, PrepareStepFunction, GenerateTextOnStepFinishCallback, StreamTextOnStepFinishCallback, StreamTextOnErrorCallback, StreamTextOnChunkCallback, StreamTextOnFinishCallback, StepResult, StreamTextResult, wrapLanguageModel, generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, InferUITools } from 'ai';
-export { ModelMessage } from 'ai';
+export { ModelMessage, Tool, tool } from 'ai';
 import { Page as Page$1 } from 'playwright-core';
 export { Page as PlaywrightPage } from 'playwright-core';
 import { Page as Page$2 } from 'puppeteer-core';
@@ -712,12 +712,6 @@ declare const SessionHeadersSchema: z$1.ZodObject<{
         true: "true";
         false: "false";
     }>>;
-    "x-language": z$1.ZodOptional<z$1.ZodEnum<{
-        typescript: "typescript";
-        python: "python";
-        playground: "playground";
-    }>>;
-    "x-sdk-version": z$1.ZodOptional<z$1.ZodString>;
     "x-sent-at": z$1.ZodOptional<z$1.ZodString>;
 }, z$1.core.$strip>;
 /** Standard error response */
@@ -1069,6 +1063,10 @@ declare const SessionStartResponseSchema: z$1.ZodObject<{
         available: z$1.ZodBoolean;
     }, z$1.core.$strip>;
 }, z$1.core.$strip>;
+/** Session end request - empty JSON object (required). */
+declare const SessionEndRequestSchema: z$1.ZodObject<{
+    _forceBody: z$1.ZodOptional<z$1.ZodUndefined>;
+}, z$1.core.$strict>;
 declare const SessionEndResultSchema: z$1.ZodObject<{}, z$1.core.$strict>;
 /** Session end response - just success flag, no data wrapper */
 declare const SessionEndResponseSchema: z$1.ZodObject<{
@@ -1330,6 +1328,10 @@ declare const AgentResultDataSchema: z$1.ZodObject<{
         inference_time_ms: z$1.ZodNumber;
     }, z$1.core.$strip>>;
 }, z$1.core.$strip>;
+declare const AgentCacheEntrySchema: z$1.ZodObject<{
+    cacheKey: z$1.ZodString;
+    entry: z$1.ZodUnknown;
+}, z$1.core.$strip>;
 declare const AgentExecuteOptionsSchema: z$1.ZodObject<{
     instruction: z$1.ZodString;
     maxSteps: z$1.ZodOptional<z$1.ZodNumber>;
@@ -1364,6 +1366,7 @@ declare const AgentExecuteRequestSchema: z$1.ZodObject<{
     }, z$1.core.$strip>;
     frameId: z$1.ZodOptional<z$1.ZodString>;
     streamResponse: z$1.ZodOptional<z$1.ZodBoolean>;
+    shouldCache: z$1.ZodOptional<z$1.ZodBoolean>;
 }, z$1.core.$strip>;
 declare const AgentExecuteResultSchema: z$1.ZodObject<{
     result: z$1.ZodObject<{
@@ -1389,6 +1392,10 @@ declare const AgentExecuteResultSchema: z$1.ZodObject<{
             inference_time_ms: z$1.ZodNumber;
         }, z$1.core.$strip>>;
     }, z$1.core.$strip>;
+    cacheEntry: z$1.ZodOptional<z$1.ZodObject<{
+        cacheKey: z$1.ZodString;
+        entry: z$1.ZodUnknown;
+    }, z$1.core.$strip>>;
 }, z$1.core.$strip>;
 declare const AgentExecuteResponseSchema: z$1.ZodObject<{
     success: z$1.ZodBoolean;
@@ -1416,6 +1423,10 @@ declare const AgentExecuteResponseSchema: z$1.ZodObject<{
                 inference_time_ms: z$1.ZodNumber;
             }, z$1.core.$strip>>;
         }, z$1.core.$strip>;
+        cacheEntry: z$1.ZodOptional<z$1.ZodObject<{
+            cacheKey: z$1.ZodString;
+            entry: z$1.ZodUnknown;
+        }, z$1.core.$strip>>;
     }, z$1.core.$strip>;
 }, z$1.core.$strip>;
 declare const NavigateOptionsSchema: z$1.ZodOptional<z$1.ZodObject<{
@@ -1751,6 +1762,7 @@ declare const api_ActResultDataSchema: typeof ActResultDataSchema;
 declare const api_ActResultSchema: typeof ActResultSchema;
 declare const api_ActionSchema: typeof ActionSchema;
 declare const api_AgentActionSchema: typeof AgentActionSchema;
+declare const api_AgentCacheEntrySchema: typeof AgentCacheEntrySchema;
 declare const api_AgentConfigSchema: typeof AgentConfigSchema;
 declare const api_AgentExecuteOptionsSchema: typeof AgentExecuteOptionsSchema;
 type api_AgentExecuteRequest = AgentExecuteRequest;
@@ -1819,6 +1831,7 @@ type api_ReplayResponse = ReplayResponse;
 declare const api_ReplayResponseSchema: typeof ReplayResponseSchema;
 type api_ReplayResult = ReplayResult;
 declare const api_ReplayResultSchema: typeof ReplayResultSchema;
+declare const api_SessionEndRequestSchema: typeof SessionEndRequestSchema;
 type api_SessionEndResponse = SessionEndResponse;
 declare const api_SessionEndResponseSchema: typeof SessionEndResponseSchema;
 type api_SessionEndResult = SessionEndResult;
@@ -1848,7 +1861,7 @@ declare const api_TokenUsageSchema: typeof TokenUsageSchema;
 declare const api_openApiLinks: typeof openApiLinks;
 declare const api_openApiSecuritySchemes: typeof openApiSecuritySchemes;
 declare namespace api {
-  export { api_ActOptionsSchema as ActOptionsSchema, type api_ActRequest as ActRequest, api_ActRequestSchema as ActRequestSchema, type api_ActResponse as ActResponse, api_ActResponseSchema as ActResponseSchema, type ActResult$1 as ActResult, type api_ActResultData as ActResultData, api_ActResultDataSchema as ActResultDataSchema, api_ActResultSchema as ActResultSchema, type Action$1 as Action, api_ActionSchema as ActionSchema, type AgentAction$1 as AgentAction, api_AgentActionSchema as AgentActionSchema, api_AgentConfigSchema as AgentConfigSchema, api_AgentExecuteOptionsSchema as AgentExecuteOptionsSchema, type api_AgentExecuteRequest as AgentExecuteRequest, api_AgentExecuteRequestSchema as AgentExecuteRequestSchema, type api_AgentExecuteResponse as AgentExecuteResponse, api_AgentExecuteResponseSchema as AgentExecuteResponseSchema, type api_AgentExecuteResult as AgentExecuteResult, api_AgentExecuteResultSchema as AgentExecuteResultSchema, type api_AgentResultData as AgentResultData, api_AgentResultDataSchema as AgentResultDataSchema, type api_AgentUsage as AgentUsage, api_AgentUsageSchema as AgentUsageSchema, type api_BrowserConfig as BrowserConfig, api_BrowserConfigSchema as BrowserConfigSchema, type api_BrowserbaseBrowserSettings as BrowserbaseBrowserSettings, api_BrowserbaseBrowserSettingsSchema as BrowserbaseBrowserSettingsSchema, type api_BrowserbaseContext as BrowserbaseContext, api_BrowserbaseContextSchema as BrowserbaseContextSchema, type api_BrowserbaseFingerprint as BrowserbaseFingerprint, api_BrowserbaseFingerprintSchema as BrowserbaseFingerprintSchema, type api_BrowserbaseFingerprintScreen as BrowserbaseFingerprintScreen, api_BrowserbaseFingerprintScreenSchema as BrowserbaseFingerprintScreenSchema, type api_BrowserbaseProxyConfig as BrowserbaseProxyConfig, api_BrowserbaseProxyConfigSchema as BrowserbaseProxyConfigSchema, type api_BrowserbaseProxyGeolocation as BrowserbaseProxyGeolocation, api_BrowserbaseProxyGeolocationSchema as BrowserbaseProxyGeolocationSchema, type api_BrowserbaseSessionCreateParams as BrowserbaseSessionCreateParams, api_BrowserbaseSessionCreateParamsSchema as BrowserbaseSessionCreateParamsSchema, type api_BrowserbaseViewport as BrowserbaseViewport, api_BrowserbaseViewportSchema as BrowserbaseViewportSchema, api_ErrorResponseSchema as ErrorResponseSchema, type api_ExternalProxyConfig as ExternalProxyConfig, api_ExternalProxyConfigSchema as ExternalProxyConfigSchema, api_ExtractOptionsSchema as ExtractOptionsSchema, type api_ExtractRequest as ExtractRequest, api_ExtractRequestSchema as ExtractRequestSchema, type api_ExtractResponse as ExtractResponse, api_ExtractResponseSchema as ExtractResponseSchema, type ExtractResult$1 as ExtractResult, api_ExtractResultSchema as ExtractResultSchema, api_LocalBrowserLaunchOptionsSchema as LocalBrowserLaunchOptionsSchema, type api_ModelConfig as ModelConfig, api_ModelConfigObjectSchema as ModelConfigObjectSchema, api_ModelConfigSchema as ModelConfigSchema, api_ModelNameSchema as ModelNameSchema, api_NavigateOptionsSchema as NavigateOptionsSchema, type api_NavigateRequest as NavigateRequest, api_NavigateRequestSchema as NavigateRequestSchema, type api_NavigateResponse as NavigateResponse, api_NavigateResponseSchema as NavigateResponseSchema, type api_NavigateResult as NavigateResult, api_NavigateResultSchema as NavigateResultSchema, api_ObserveOptionsSchema as ObserveOptionsSchema, type api_ObserveRequest as ObserveRequest, api_ObserveRequestSchema as ObserveRequestSchema, type api_ObserveResponse as ObserveResponse, api_ObserveResponseSchema as ObserveResponseSchema, type api_ObserveResult as ObserveResult, api_ObserveResultSchema as ObserveResultSchema, api_Operations as Operations, api_ProxyConfigSchema as ProxyConfigSchema, type api_ReplayAction as ReplayAction, api_ReplayActionSchema as ReplayActionSchema, type api_ReplayPage as ReplayPage, api_ReplayPageSchema as ReplayPageSchema, type api_ReplayResponse as ReplayResponse, api_ReplayResponseSchema as ReplayResponseSchema, type api_ReplayResult as ReplayResult, api_ReplayResultSchema as ReplayResultSchema, type api_SessionEndResponse as SessionEndResponse, api_SessionEndResponseSchema as SessionEndResponseSchema, type api_SessionEndResult as SessionEndResult, api_SessionEndResultSchema as SessionEndResultSchema, type api_SessionHeaders as SessionHeaders, api_SessionHeadersSchema as SessionHeadersSchema, type api_SessionIdParams as SessionIdParams, api_SessionIdParamsSchema as SessionIdParamsSchema, type api_SessionStartRequest as SessionStartRequest, api_SessionStartRequestSchema as SessionStartRequestSchema, type api_SessionStartResponse as SessionStartResponse, api_SessionStartResponseSchema as SessionStartResponseSchema, type api_SessionStartResult as SessionStartResult, api_SessionStartResultSchema as SessionStartResultSchema, type api_StreamEvent as StreamEvent, type api_StreamEventLogData as StreamEventLogData, api_StreamEventLogDataSchema as StreamEventLogDataSchema, api_StreamEventSchema as StreamEventSchema, type api_StreamEventStatus as StreamEventStatus, api_StreamEventStatusSchema as StreamEventStatusSchema, type api_StreamEventSystemData as StreamEventSystemData, api_StreamEventSystemDataSchema as StreamEventSystemDataSchema, type api_StreamEventType as StreamEventType, api_StreamEventTypeSchema as StreamEventTypeSchema, type api_TokenUsage as TokenUsage, api_TokenUsageSchema as TokenUsageSchema, api_openApiLinks as openApiLinks, api_openApiSecuritySchemes as openApiSecuritySchemes };
+  export { api_ActOptionsSchema as ActOptionsSchema, type api_ActRequest as ActRequest, api_ActRequestSchema as ActRequestSchema, type api_ActResponse as ActResponse, api_ActResponseSchema as ActResponseSchema, type ActResult$1 as ActResult, type api_ActResultData as ActResultData, api_ActResultDataSchema as ActResultDataSchema, api_ActResultSchema as ActResultSchema, type Action$1 as Action, api_ActionSchema as ActionSchema, type AgentAction$1 as AgentAction, api_AgentActionSchema as AgentActionSchema, api_AgentCacheEntrySchema as AgentCacheEntrySchema, api_AgentConfigSchema as AgentConfigSchema, api_AgentExecuteOptionsSchema as AgentExecuteOptionsSchema, type api_AgentExecuteRequest as AgentExecuteRequest, api_AgentExecuteRequestSchema as AgentExecuteRequestSchema, type api_AgentExecuteResponse as AgentExecuteResponse, api_AgentExecuteResponseSchema as AgentExecuteResponseSchema, type api_AgentExecuteResult as AgentExecuteResult, api_AgentExecuteResultSchema as AgentExecuteResultSchema, type api_AgentResultData as AgentResultData, api_AgentResultDataSchema as AgentResultDataSchema, type api_AgentUsage as AgentUsage, api_AgentUsageSchema as AgentUsageSchema, type api_BrowserConfig as BrowserConfig, api_BrowserConfigSchema as BrowserConfigSchema, type api_BrowserbaseBrowserSettings as BrowserbaseBrowserSettings, api_BrowserbaseBrowserSettingsSchema as BrowserbaseBrowserSettingsSchema, type api_BrowserbaseContext as BrowserbaseContext, api_BrowserbaseContextSchema as BrowserbaseContextSchema, type api_BrowserbaseFingerprint as BrowserbaseFingerprint, api_BrowserbaseFingerprintSchema as BrowserbaseFingerprintSchema, type api_BrowserbaseFingerprintScreen as BrowserbaseFingerprintScreen, api_BrowserbaseFingerprintScreenSchema as BrowserbaseFingerprintScreenSchema, type api_BrowserbaseProxyConfig as BrowserbaseProxyConfig, api_BrowserbaseProxyConfigSchema as BrowserbaseProxyConfigSchema, type api_BrowserbaseProxyGeolocation as BrowserbaseProxyGeolocation, api_BrowserbaseProxyGeolocationSchema as BrowserbaseProxyGeolocationSchema, type api_BrowserbaseSessionCreateParams as BrowserbaseSessionCreateParams, api_BrowserbaseSessionCreateParamsSchema as BrowserbaseSessionCreateParamsSchema, type api_BrowserbaseViewport as BrowserbaseViewport, api_BrowserbaseViewportSchema as BrowserbaseViewportSchema, api_ErrorResponseSchema as ErrorResponseSchema, type api_ExternalProxyConfig as ExternalProxyConfig, api_ExternalProxyConfigSchema as ExternalProxyConfigSchema, api_ExtractOptionsSchema as ExtractOptionsSchema, type api_ExtractRequest as ExtractRequest, api_ExtractRequestSchema as ExtractRequestSchema, type api_ExtractResponse as ExtractResponse, api_ExtractResponseSchema as ExtractResponseSchema, type ExtractResult$1 as ExtractResult, api_ExtractResultSchema as ExtractResultSchema, api_LocalBrowserLaunchOptionsSchema as LocalBrowserLaunchOptionsSchema, type api_ModelConfig as ModelConfig, api_ModelConfigObjectSchema as ModelConfigObjectSchema, api_ModelConfigSchema as ModelConfigSchema, api_ModelNameSchema as ModelNameSchema, api_NavigateOptionsSchema as NavigateOptionsSchema, type api_NavigateRequest as NavigateRequest, api_NavigateRequestSchema as NavigateRequestSchema, type api_NavigateResponse as NavigateResponse, api_NavigateResponseSchema as NavigateResponseSchema, type api_NavigateResult as NavigateResult, api_NavigateResultSchema as NavigateResultSchema, api_ObserveOptionsSchema as ObserveOptionsSchema, type api_ObserveRequest as ObserveRequest, api_ObserveRequestSchema as ObserveRequestSchema, type api_ObserveResponse as ObserveResponse, api_ObserveResponseSchema as ObserveResponseSchema, type api_ObserveResult as ObserveResult, api_ObserveResultSchema as ObserveResultSchema, api_Operations as Operations, api_ProxyConfigSchema as ProxyConfigSchema, type api_ReplayAction as ReplayAction, api_ReplayActionSchema as ReplayActionSchema, type api_ReplayPage as ReplayPage, api_ReplayPageSchema as ReplayPageSchema, type api_ReplayResponse as ReplayResponse, api_ReplayResponseSchema as ReplayResponseSchema, type api_ReplayResult as ReplayResult, api_ReplayResultSchema as ReplayResultSchema, api_SessionEndRequestSchema as SessionEndRequestSchema, type api_SessionEndResponse as SessionEndResponse, api_SessionEndResponseSchema as SessionEndResponseSchema, type api_SessionEndResult as SessionEndResult, api_SessionEndResultSchema as SessionEndResultSchema, type api_SessionHeaders as SessionHeaders, api_SessionHeadersSchema as SessionHeadersSchema, type api_SessionIdParams as SessionIdParams, api_SessionIdParamsSchema as SessionIdParamsSchema, type api_SessionStartRequest as SessionStartRequest, api_SessionStartRequestSchema as SessionStartRequestSchema, type api_SessionStartResponse as SessionStartResponse, api_SessionStartResponseSchema as SessionStartResponseSchema, type api_SessionStartResult as SessionStartResult, api_SessionStartResultSchema as SessionStartResultSchema, type api_StreamEvent as StreamEvent, type api_StreamEventLogData as StreamEventLogData, api_StreamEventLogDataSchema as StreamEventLogDataSchema, api_StreamEventSchema as StreamEventSchema, type api_StreamEventStatus as StreamEventStatus, api_StreamEventStatusSchema as StreamEventStatusSchema, type api_StreamEventSystemData as StreamEventSystemData, api_StreamEventSystemDataSchema as StreamEventSystemDataSchema, type api_StreamEventType as StreamEventType, api_StreamEventTypeSchema as StreamEventTypeSchema, type api_TokenUsage as TokenUsage, api_TokenUsageSchema as TokenUsageSchema, api_openApiLinks as openApiLinks, api_openApiSecuritySchemes as openApiSecuritySchemes };
 }
 
 declare class StagehandAPIError extends Error {
@@ -2009,7 +2022,8 @@ interface V3Options {
 }
 
 declare class StagehandError extends Error {
-    constructor(message: string);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 declare class StagehandDefaultError extends StagehandError {
     constructor(error?: unknown);
@@ -2152,6 +2166,9 @@ declare class AgentAbortError extends StagehandError {
 declare class StagehandClosedError extends StagehandError {
     constructor();
 }
+declare class StagehandSnapshotError extends StagehandError {
+    constructor(cause?: unknown);
+}
 
 declare class AISdkClient extends LLMClient {
     type: "aisdk";
@@ -2219,13 +2236,16 @@ declare class StagehandAPIClient {
     private modelProvider?;
     private logger;
     private fetchWithCookies;
+    private lastFinishedEventData;
+    private latestAgentCacheEntry;
     constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
     init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: ClientSessionStartParams): Promise<SessionStartResult>;
     act({ input, options, frameId, }: ClientActParameters): Promise<ActResult>;
     extract<T extends StagehandZodSchema>({ instruction, schema: zodSchema, options, frameId, }: ClientExtractParameters): Promise<ExtractResult<T>>;
     observe({ instruction, options, frameId, }: ClientObserveParameters): Promise<Action[]>;
     goto(url: string, options?: NavigateRequest["options"], frameId?: string): Promise<SerializableResponse | null>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string, shouldCache?: boolean): Promise<AgentResult>;
+    consumeLatestAgentCacheEntry(): AgentCacheTransferPayload | null;
     end(): Promise<Response>;
     getReplayMetrics(): Promise<StagehandMetrics>;
     /**
@@ -2237,6 +2257,7 @@ declare class StagehandAPIClient {
      * model provider differs from the one used to init the session.
      */
     private prepareModelConfig;
+    private consumeFinishedEventData;
     private execute;
     private request;
 }
@@ -2368,6 +2389,10 @@ declare class V3Context {
     awaitActivePage(timeoutMs?: number): Promise<Page>;
 }
 
+type AgentCacheTransferPayload = {
+    cacheKey: string;
+    entry: CachedAgentEntry;
+};
 type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | AgentReplayKeysStep | {
     type: string;
     [key: string]: unknown;
@@ -2421,6 +2446,20 @@ interface AgentReplayKeysStep {
         times?: number;
     };
 }
+interface SanitizedAgentExecuteOptions {
+    maxSteps?: number;
+    highlightCursor?: boolean;
+}
+interface CachedAgentEntry {
+    version: 1;
+    instruction: string;
+    startUrl: string;
+    options: SanitizedAgentExecuteOptions;
+    configSignature: string;
+    steps: AgentReplayStep[];
+    result: AgentResult;
+    timestamp: string;
+}
 
 /**
  * Response
@@ -2558,6 +2597,12 @@ type AnyPage = Page$1 | Page$2 | Page$3 | Page;
 
 type LoadState = "load" | "domcontentloaded" | "networkidle";
 
+type SnapshotResult = {
+    formattedTree: string;
+    xpathMap: Record<string, string>;
+    urlMap: Record<string, string>;
+};
+
 type ScreenshotAnimationsOption = "disabled" | "allow";
 type ScreenshotCaretOption = "hide" | "initial";
 type ScreenshotScaleOption = "css" | "device";
@@ -2800,6 +2845,30 @@ declare class Page {
      * Mirrors Playwright's API signatures.
      */
     waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for a specified amount of time.
+     *
+     * @param ms The number of milliseconds to wait.
+     */
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Wait for an element matching the selector to appear in the DOM.
+     * Uses MutationObserver for efficiency
+     * Pierces shadow DOM by default.
+     * Supports iframe hop notation with '>>' (e.g., 'iframe#checkout >> .submit-btn').
+     *
+     * @param selector CSS selector to wait for (supports '>>' for iframe hops)
+     * @param options.state Element state to wait for: 'attached' | 'detached' | 'visible' | 'hidden' (default: 'visible')
+     * @param options.timeout Maximum time to wait in milliseconds (default: 30000)
+     * @param options.pierceShadow Whether to search inside shadow DOM (default: true)
+     * @returns True when the condition is met
+     * @throws Error if timeout is reached before the condition is met
+     */
+    waitForSelector(selector: string, options?: {
+        state?: "attached" | "detached" | "visible" | "hidden";
+        timeout?: number;
+        pierceShadow?: boolean;
+    }): Promise<boolean>;
     /**
      * Evaluate a function or expression in the current main frame's main world.
      * - If a string is provided, it is treated as a JS expression.
@@ -2865,6 +2934,7 @@ declare class Page {
     keyPress(key: string, options?: {
         delay?: number;
     }): Promise<void>;
+    snapshot(): Promise<SnapshotResult>;
     private _pressedModifiers;
     /** Press a key down without releasing it */
     private keyDown;
@@ -2944,6 +3014,12 @@ interface AgentResult {
      * @experimental
      */
     messages?: ModelMessage[];
+    /**
+     * Custom output data extracted based on the `output` schema provided in execute options.
+     * Only populated if an `output` schema was provided.
+     * @experimental
+     */
+    output?: Record<string, unknown>;
 }
 type AgentStreamResult = StreamTextResult<ToolSet, never> & {
     result: Promise<AgentResult>;
@@ -3166,6 +3242,26 @@ interface AgentExecuteOptionsBase {
      * ```
      */
     excludeTools?: string[];
+    /**
+     * A Zod schema defining custom output data to return when the task completes.
+     * The agent will populate this data in the final close tool call.
+     *
+     * @experimental
+     * @example
+     * ```typescript
+     * const result = await agent.execute({
+     *   instruction: "Find the cheapest flight from NYC to LA",
+     *   output: z.object({
+     *     price: z.string().describe("The price of the flight"),
+     *     airline: z.string().describe("The airline name"),
+     *     departureTime: z.string().describe("Departure time"),
+     *   }),
+     * });
+     *
+     * console.log(result.output); // { price: "$199", airline: "Delta", departureTime: "8:00 AM" }
+     * ```
+     */
+    output?: StagehandZodObject;
 }
 /**
  * Options for non-streaming agent execution.
@@ -3397,6 +3493,63 @@ interface StreamingAgentInstance {
 interface NonStreamingAgentInstance {
     execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
 }
+/**
+ * Content item type for toModelOutput return values.
+ * Used in tool definitions to return text and/or media to the model.
+ */
+type ModelOutputContentItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "media";
+    mediaType: string;
+    data: string;
+};
+interface ClickToolResult {
+    success: boolean;
+    describe?: string;
+    coordinates?: number[];
+    error?: string;
+    screenshotBase64?: string;
+}
+interface TypeToolResult {
+    success: boolean;
+    describe?: string;
+    text?: string;
+    error?: string;
+    screenshotBase64?: string;
+}
+interface DragAndDropToolResult {
+    success: boolean;
+    describe?: string;
+    error?: string;
+    screenshotBase64?: string;
+}
+interface FillFormField {
+    action: string;
+    value: string;
+    coordinates: {
+        x: number;
+        y: number;
+    };
+}
+interface FillFormVisionToolResult {
+    success: boolean;
+    playwrightArguments?: FillFormField[];
+    error?: string;
+    screenshotBase64?: string;
+}
+interface ScrollVisionToolResult {
+    success: boolean;
+    message: string;
+    scrolledPixels: number;
+    screenshotBase64?: string;
+}
+interface WaitToolResult {
+    success: boolean;
+    waited: number;
+    screenshotBase64?: string;
+}
 
 type OpenAIClientOptions = Pick<ClientOptions$1, "baseURL" | "apiKey">;
 type AnthropicClientOptions = Pick<ClientOptions$2, "baseURL" | "apiKey">;
@@ -3809,12 +3962,9 @@ declare const screenshotTool: (v3: V3) => ai.Tool<Record<string, never>, {
     pageUrl: string;
 }>;
 
-declare const waitTool: (v3: V3) => ai.Tool<{
+declare const waitTool: (v3: V3, mode?: AgentToolMode) => ai.Tool<{
     timeMs: number;
-}, {
-    success: boolean;
-    waited: number;
-}>;
+}, WaitToolResult>;
 
 declare const navBackTool: (v3: V3) => ai.Tool<{
     reasoningText: string;
@@ -3822,15 +3972,6 @@ declare const navBackTool: (v3: V3) => ai.Tool<{
     success: boolean;
 }>;
 
-declare const closeTool: () => ai.Tool<{
-    reasoning: string;
-    taskComplete: boolean;
-}, {
-    success: boolean;
-    reasoning: string;
-    taskComplete: boolean;
-}>;
-
 declare const ariaTreeTool: (v3: V3) => ai.Tool<Record<string, never>, {
     content: string;
     pageUrl: string;
@@ -3867,11 +4008,7 @@ declare const scrollVisionTool: (v3: V3, provider?: string) => ai.Tool<{
     direction: "up" | "down";
     coordinates?: number[];
     percentage?: number;
-}, {
-    success: boolean;
-    message: string;
-    scrolledPixels: number;
-}>;
+}, ScrollVisionToolResult>;
 
 declare const extractTool: (v3: V3, executionModel?: string, logger?: (message: LogLine) => void) => ai.Tool<{
     instruction: string;
@@ -3889,47 +4026,19 @@ declare const extractTool: (v3: V3, executionModel?: string, logger?: (message:
 declare const clickTool: (v3: V3, provider?: string) => ai.Tool<{
     describe: string;
     coordinates: number[];
-}, {
-    success: boolean;
-    describe: string;
-    coordinates: number[];
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-    describe?: undefined;
-    coordinates?: undefined;
-}>;
+}, ClickToolResult>;
 
 declare const typeTool: (v3: V3, provider?: string) => ai.Tool<{
     describe: string;
     text: string;
     coordinates: number[];
-}, {
-    success: boolean;
-    describe: string;
-    text: string;
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-    describe?: undefined;
-    text?: undefined;
-}>;
+}, TypeToolResult>;
 
 declare const dragAndDropTool: (v3: V3, provider?: string) => ai.Tool<{
     describe: string;
     startCoordinates: number[];
     endCoordinates: number[];
-}, {
-    success: boolean;
-    describe: string;
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-    describe?: undefined;
-}>;
+}, DragAndDropToolResult>;
 
 declare const clickAndHoldTool: (v3: V3, provider?: string) => ai.Tool<{
     describe: string;
@@ -3978,22 +4087,7 @@ declare const fillFormVisionTool: (v3: V3, provider?: string) => ai.Tool<{
             y: number;
         };
     }[];
-}, {
-    success: boolean;
-    playwrightArguments: {
-        coordinates: {
-            x: number;
-            y: number;
-        };
-        action: string;
-        value: string;
-    }[];
-    error?: undefined;
-} | {
-    success: boolean;
-    error: string;
-    playwrightArguments?: undefined;
-}>;
+}, FillFormVisionToolResult>;
 
 declare const thinkTool: () => ai.Tool<{
     reasoning: string;
@@ -4047,7 +4141,6 @@ type AgentToolTypesMap = {
     ariaTree: ReturnType<typeof ariaTreeTool>;
     click: ReturnType<typeof clickTool>;
     clickAndHold: ReturnType<typeof clickAndHoldTool>;
-    close: ReturnType<typeof closeTool>;
     dragAndDrop: ReturnType<typeof dragAndDropTool>;
     extract: ReturnType<typeof extractTool>;
     fillForm: ReturnType<typeof fillFormTool>;
@@ -4181,4 +4274,10 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, AgentAbortError, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentToolCall, type AgentToolMode, type AgentToolResult, type AgentToolTypesMap, type AgentTools, type AgentType, type AgentUITools, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, api as Api, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, type SafetyCheck, type SafetyConfirmationHandler, type SafetyConfirmationResponse, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandClosedError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, localBrowserLaunchOptionsSchema, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+interface ServerAgentCacheHandle {
+    complete(): AgentCacheTransferPayload | null;
+    discard(): void;
+}
+declare function __internalCreateInMemoryAgentCacheHandle(stagehand: V3): ServerAgentCacheHandle;
+
+export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, AgentAbortError, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentToolCall, type AgentToolMode, type AgentToolResult, type AgentToolTypesMap, type AgentTools, type AgentType, type AgentUITools, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, api as Api, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClickToolResult, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, type DragAndDropToolResult, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FillFormField, type FillFormVisionToolResult, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelOutputContentItem, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, type SafetyCheck, type SafetyConfirmationHandler, type SafetyConfirmationResponse, type ScrollVisionToolResult, type ServerAgentCacheHandle, type SnapshotResult, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandClosedError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, StagehandSnapshotError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, type TypeToolResult, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, type WaitToolResult, XPathResolutionError, ZodSchemaValidationError, __internalCreateInMemoryAgentCacheHandle, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, localBrowserLaunchOptionsSchema, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };