@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/tests/public-api/public-types.test.js

@@ -0,0 +1,74 @@
+import { describe, expectTypeOf, it } from "vitest";
+describe("Stagehand public API types", () => {
+  describe("AnyPage", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("ActOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("ActResult", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("ExtractOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("ObserveOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("Action", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentAction", () => {
+    it("has type field", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentExecuteOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentStreamExecuteOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentExecutionOptions", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentResult", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("AgentConfig", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toExtend();
+    });
+  });
+  describe("AgentToolMode", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("HistoryEntry", () => {
+    it("matches expected type shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+});
+//# sourceMappingURL=public-types.test.js.map

package/dist/esm/tests/public-api/public-types.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/public-types.test.ts"],
+  "sourcesContent": ["import { describe, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\n// Type-level manifest of all expected exported types\n// Since these types don't exist at runtime, we currently need to manually add new publicly exported types\n// to this list ourselves - it's not automatically going to catch changes like our export-surface.test.ts does.\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype ExpectedExportedTypes = {\n  // Types from model.ts\n  AvailableModel: Stagehand.AvailableModel;\n  AvailableCuaModel: Stagehand.AvailableCuaModel;\n  ModelProvider: Stagehand.ModelProvider;\n  ClientOptions: Stagehand.ClientOptions;\n  ModelConfiguration: Stagehand.ModelConfiguration;\n  AnthropicJsonSchemaObject: Stagehand.AnthropicJsonSchemaObject;\n  AISDKProvider: Stagehand.AISDKProvider;\n  AISDKCustomProvider: Stagehand.AISDKCustomProvider;\n  LLMTool: Stagehand.LLMTool;\n  // Types from methods.ts\n  ActOptions: Stagehand.ActOptions;\n  ActResult: Stagehand.ActResult;\n  ExtractResult: Stagehand.ExtractResult<Stagehand.StagehandZodSchema>;\n  Action: Stagehand.Action;\n  HistoryEntry: Stagehand.HistoryEntry;\n  ExtractOptions: Stagehand.ExtractOptions;\n  ObserveOptions: Stagehand.ObserveOptions;\n  V3FunctionName: Stagehand.V3FunctionName;\n  // Types from agent.ts\n  Tool: Stagehand.Tool;\n  AgentAction: Stagehand.AgentAction;\n  AgentResult: Stagehand.AgentResult;\n  AgentExecuteOptions: Stagehand.AgentExecuteOptions;\n  AgentType: Stagehand.AgentType;\n  AgentExecutionOptions: Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>;\n  AgentHandlerOptions: Stagehand.AgentHandlerOptions;\n  ActionExecutionResult: Stagehand.ActionExecutionResult;\n  ToolUseItem: Stagehand.ToolUseItem;\n  AnthropicMessage: Stagehand.AnthropicMessage;\n  AnthropicContentBlock: Stagehand.AnthropicContentBlock;\n  AnthropicTextBlock: Stagehand.AnthropicTextBlock;\n  AnthropicToolResult: Stagehand.AnthropicToolResult;\n  ResponseItem: Stagehand.ResponseItem;\n  ComputerCallItem: Stagehand.ComputerCallItem;\n  FunctionCallItem: Stagehand.FunctionCallItem;\n  ResponseInputItem: Stagehand.ResponseInputItem;\n  AgentInstance: Stagehand.AgentInstance;\n  AgentProviderType: Stagehand.AgentProviderType;\n  AgentModelConfig: Stagehand.AgentModelConfig;\n  AgentConfig: Stagehand.AgentConfig;\n  AgentToolMode: Stagehand.AgentToolMode;\n  AgentCallbacks: Stagehand.AgentCallbacks;\n  AgentExecuteCallbacks: Stagehand.AgentExecuteCallbacks;\n  AgentStreamCallbacks: Stagehand.AgentStreamCallbacks;\n  AgentExecuteOptionsBase: Stagehand.AgentExecuteOptionsBase;\n  AgentStreamExecuteOptions: Stagehand.AgentStreamExecuteOptions;\n  ModelMessage: Stagehand.ModelMessage;\n  // Types from agent/tools\n  AgentTools: Stagehand.AgentTools;\n  AgentToolTypesMap: Stagehand.AgentToolTypesMap;\n  AgentUITools: Stagehand.AgentUITools;\n  AgentToolCall: Stagehand.AgentToolCall;\n  AgentToolResult: Stagehand.AgentToolResult;\n  // Types from logs.ts\n  LogLevel: Stagehand.LogLevel;\n  LogLine: Stagehand.LogLine;\n  Logger: Stagehand.Logger;\n  // Types from metrics.ts\n  StagehandMetrics: Stagehand.StagehandMetrics;\n  // Types from options.ts\n  V3Env: Stagehand.V3Env;\n  LocalBrowserLaunchOptions: Stagehand.LocalBrowserLaunchOptions;\n  V3Options: Stagehand.V3Options;\n  // Types from page.ts\n  AnyPage: Stagehand.AnyPage;\n  Page: Stagehand.Page;\n  PlaywrightPage: Stagehand.PlaywrightPage;\n  PatchrightPage: Stagehand.PatchrightPage;\n  PuppeteerPage: Stagehand.PuppeteerPage;\n  ConsoleListener: Stagehand.ConsoleListener;\n  LoadState: Stagehand.LoadState;\n  // Types from LLMClient.ts\n  ChatMessage: Stagehand.ChatMessage;\n  ChatMessageContent: Stagehand.ChatMessageContent;\n  ChatMessageImageContent: Stagehand.ChatMessageImageContent;\n  ChatMessageTextContent: Stagehand.ChatMessageTextContent;\n  ChatCompletionOptions: Stagehand.ChatCompletionOptions;\n  LLMResponse: Stagehand.LLMResponse;\n  CreateChatCompletionOptions: Stagehand.CreateChatCompletionOptions;\n  LLMUsage: Stagehand.LLMUsage;\n  LLMParsedResponse: Stagehand.LLMParsedResponse<Record<string, unknown>>;\n  // Types from zodCompat.ts\n  StagehandZodSchema: Stagehand.StagehandZodSchema;\n  StagehandZodObject: Stagehand.StagehandZodObject;\n  InferStagehandSchema: Stagehand.InferStagehandSchema<Stagehand.StagehandZodSchema>;\n  JsonSchemaDocument: Stagehand.JsonSchemaDocument;\n  // Types from utils.ts\n  JsonSchema: Stagehand.JsonSchema;\n  JsonSchemaProperty: Stagehand.JsonSchemaProperty;\n};\n\ndescribe(\"Stagehand public API types\", () => {\n  describe(\"AnyPage\", () => {\n    type ExpectedAnyPage =\n      | Stagehand.PlaywrightPage\n      | Stagehand.PuppeteerPage\n      | Stagehand.PatchrightPage\n      | Stagehand.Page;\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AnyPage>().toEqualTypeOf<ExpectedAnyPage>();\n    });\n  });\n\n  describe(\"ActOptions\", () => {\n    type ExpectedActOptions = {\n      model?: Stagehand.ModelConfiguration;\n      variables?: Record<string, string>;\n      timeout?: number;\n      page?: Stagehand.AnyPage;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActOptions>().toEqualTypeOf<ExpectedActOptions>();\n    });\n  });\n\n  describe(\"ActResult\", () => {\n    type ExpectedActResult = {\n      success: boolean;\n      message: string;\n      actionDescription: string;\n      actions: Stagehand.Action[];\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ActResult>().toEqualTypeOf<ExpectedActResult>();\n    });\n  });\n\n  describe(\"ExtractOptions\", () => {\n    type ExpectedExtractOptions = {\n      model?: Stagehand.ModelConfiguration;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ExtractOptions>().toEqualTypeOf<ExpectedExtractOptions>();\n    });\n  });\n\n  describe(\"ObserveOptions\", () => {\n    type ExpectedObserveOptions = {\n      model?: Stagehand.ModelConfiguration;\n      timeout?: number;\n      selector?: string;\n      page?: Stagehand.AnyPage;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.ObserveOptions>().toEqualTypeOf<ExpectedObserveOptions>();\n    });\n  });\n\n  describe(\"Action\", () => {\n    type ExpectedAction = {\n      selector: string;\n      description: string;\n      method?: string;\n      arguments?: string[];\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.Action>().toEqualTypeOf<ExpectedAction>();\n    });\n  });\n\n  describe(\"AgentAction\", () => {\n    // AgentAction is a separate type from Action, not an extension\n    // It has additional fields like type, reasoning, taskCompleted, etc.\n    it(\"has type field\", () => {\n      type TestAction = { type: string } & Stagehand.AgentAction;\n      expectTypeOf<TestAction[\"type\"]>().toEqualTypeOf<string>();\n    });\n  });\n\n  describe(\"AgentExecuteOptions\", () => {\n    type ExpectedAgentExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentExecuteCallbacks;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentExecuteOptions>().toEqualTypeOf<ExpectedAgentExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentStreamExecuteOptions\", () => {\n    type ExpectedAgentStreamExecuteOptions = {\n      instruction: string;\n      maxSteps?: number;\n      page?: Stagehand.AnyPage;\n      highlightCursor?: boolean;\n      messages?: Stagehand.ModelMessage[];\n      signal?: AbortSignal;\n      excludeTools?: string[];\n      output?: Stagehand.StagehandZodObject;\n      callbacks?: Stagehand.AgentStreamCallbacks;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentStreamExecuteOptions>().toEqualTypeOf<ExpectedAgentStreamExecuteOptions>();\n    });\n  });\n\n  describe(\"AgentExecutionOptions\", () => {\n    type ExpectedAgentExecutionOptions<T = Stagehand.AgentExecuteOptions> = {\n      options: T;\n      logger: (message: Stagehand.LogLine) => void;\n      retries?: number;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<\n        Stagehand.AgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >().toEqualTypeOf<\n        ExpectedAgentExecutionOptions<Stagehand.AgentExecuteOptions>\n      >();\n    });\n  });\n\n  describe(\"AgentResult\", () => {\n    type ExpectedAgentResult = {\n      success: boolean;\n      message: string;\n      actions: Stagehand.AgentAction[];\n      completed: boolean;\n      metadata?: Record<string, unknown>;\n      usage?: {\n        input_tokens: number;\n        output_tokens: number;\n        reasoning_tokens?: number;\n        cached_input_tokens?: number;\n        inference_time_ms: number;\n      };\n      messages?: Stagehand.ModelMessage[];\n      output?: Record<string, unknown>;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentResult>().toEqualTypeOf<ExpectedAgentResult>();\n    });\n  });\n\n  describe(\"AgentConfig\", () => {\n    type ExpectedAgentConfig = {\n      systemPrompt?: string;\n      integrations?: (unknown | string)[];\n      tools?: unknown;\n      cua?: boolean;\n      model?: string | Stagehand.AgentModelConfig<string>;\n      executionModel?: string | Stagehand.AgentModelConfig<string>;\n      stream?: boolean;\n      mode?: Stagehand.AgentToolMode;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentConfig>().toExtend<ExpectedAgentConfig>();\n    });\n  });\n\n  describe(\"AgentToolMode\", () => {\n    type ExpectedAgentToolMode = \"dom\" | \"hybrid\" | \"cua\";\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.AgentToolMode>().toEqualTypeOf<ExpectedAgentToolMode>();\n    });\n  });\n\n  describe(\"HistoryEntry\", () => {\n    type ExpectedHistoryEntry = {\n      method: \"act\" | \"extract\" | \"observe\" | \"navigate\" | \"agent\";\n      parameters: unknown;\n      result: unknown;\n      timestamp: string;\n    };\n\n    it(\"matches expected type shape\", () => {\n      expectTypeOf<Stagehand.HistoryEntry>().toEqualTypeOf<ExpectedHistoryEntry>();\n    });\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,cAAc,UAAU;AAqG3C,SAAS,8BAA8B,MAAM;AAC3C,WAAS,WAAW,MAAM;AAOxB,OAAG,+BAA+B,MAAM;AACtC,mBAAgC,EAAE,cAA+B;AAAA,IACnE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,cAAc,MAAM;AAQ3B,OAAG,+BAA+B,MAAM;AACtC,mBAAmC,EAAE,cAAkC;AAAA,IACzE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,aAAa,MAAM;AAQ1B,OAAG,+BAA+B,MAAM;AACtC,mBAAkC,EAAE,cAAiC;AAAA,IACvE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAQ/B,OAAG,+BAA+B,MAAM;AACtC,mBAAuC,EAAE,cAAsC;AAAA,IACjF,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAQ/B,OAAG,+BAA+B,MAAM;AACtC,mBAAuC,EAAE,cAAsC;AAAA,IACjF,CAAC;AAAA,EACH,CAAC;AAED,WAAS,UAAU,MAAM;AAQvB,OAAG,+BAA+B,MAAM;AACtC,mBAA+B,EAAE,cAA8B;AAAA,IACjE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,eAAe,MAAM;AAG5B,OAAG,kBAAkB,MAAM;AAEzB,mBAAiC,EAAE,cAAsB;AAAA,IAC3D,CAAC;AAAA,EACH,CAAC;AAED,WAAS,uBAAuB,MAAM;AAapC,OAAG,+BAA+B,MAAM;AACtC,mBAA4C,EAAE,cAA2C;AAAA,IAC3F,CAAC;AAAA,EACH,CAAC;AAED,WAAS,6BAA6B,MAAM;AAa1C,OAAG,+BAA+B,MAAM;AACtC,mBAAkD,EAAE,cAAiD;AAAA,IACvG,CAAC;AAAA,EACH,CAAC;AAED,WAAS,yBAAyB,MAAM;AAOtC,OAAG,+BAA+B,MAAM;AACtC,mBAEE,EAAE,cAEF;AAAA,IACJ,CAAC;AAAA,EACH,CAAC;AAED,WAAS,eAAe,MAAM;AAkB5B,OAAG,+BAA+B,MAAM;AACtC,mBAAoC,EAAE,cAAmC;AAAA,IAC3E,CAAC;AAAA,EACH,CAAC;AAED,WAAS,eAAe,MAAM;AAY5B,OAAG,+BAA+B,MAAM;AACtC,mBAAoC,EAAE,SAA8B;AAAA,IACtE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,iBAAiB,MAAM;AAG9B,OAAG,+BAA+B,MAAM;AACtC,mBAAsC,EAAE,cAAqC;AAAA,IAC/E,CAAC;AAAA,EACH,CAAC;AAED,WAAS,gBAAgB,MAAM;AAQ7B,OAAG,+BAA+B,MAAM;AACtC,mBAAqC,EAAE,cAAoC;AAAA,IAC7E,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/public-api/runtime-utils.test.js

@@ -0,0 +1,31 @@
+import { describe, expectTypeOf, it } from "vitest";
+import * as Stagehand from "@browserbasehq/stagehand";
+describe("Runtime Utils public API types", () => {
+  describe("injectUrls", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.injectUrls
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("isRunningInBun", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.isRunningInBun
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("loadApiKeyFromEnv", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.loadApiKeyFromEnv
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("providerEnvVarMap", () => {
+    it("maps providers to environment variable names", () => {
+      expectTypeOf().toExtend();
+    });
+  });
+});
+//# sourceMappingURL=runtime-utils.test.js.map

package/dist/esm/tests/public-api/runtime-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/runtime-utils.test.ts"],
+  "sourcesContent": ["import { describe, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\ndescribe(\"Runtime Utils public API types\", () => {\n  describe(\"injectUrls\", () => {\n    type ExpectedInjectUrlsParams = [\n      unknown,\n      Array<string | number>,\n      Record<string, string>,\n    ];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.injectUrls,\n      ).parameters.branded.toEqualTypeOf<ExpectedInjectUrlsParams>();\n    });\n  });\n\n  describe(\"isRunningInBun\", () => {\n    type ExpectedIsRunningInBunParams = [];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.isRunningInBun,\n      ).parameters.branded.toEqualTypeOf<ExpectedIsRunningInBunParams>();\n    });\n  });\n\n  describe(\"loadApiKeyFromEnv\", () => {\n    type ExpectedLoadApiKeyFromEnvParams = [\n      string | undefined,\n      (logLine: Stagehand.LogLine) => void,\n    ];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.loadApiKeyFromEnv,\n      ).parameters.branded.toEqualTypeOf<ExpectedLoadApiKeyFromEnvParams>();\n    });\n  });\n\n  describe(\"providerEnvVarMap\", () => {\n    type ExpectedProviderEnvVarMap = Partial<\n      Record<string, string | Array<string>>\n    >;\n\n    it(\"maps providers to environment variable names\", () => {\n      expectTypeOf<\n        typeof Stagehand.providerEnvVarMap\n      >().toExtend<ExpectedProviderEnvVarMap>();\n    });\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,cAAc,UAAU;AAC3C,YAAY,eAAe;AAE3B,SAAS,kCAAkC,MAAM;AAC/C,WAAS,cAAc,MAAM;AAO3B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAAwC;AAAA,IAC/D,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAG/B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA4C;AAAA,IACnE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,qBAAqB,MAAM;AAMlC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA+C;AAAA,IACtE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,qBAAqB,MAAM;AAKlC,OAAG,gDAAgD,MAAM;AACvD,mBAEE,EAAE,SAAoC;AAAA,IAC1C,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/public-api/schema-utils.test.js

@@ -0,0 +1,78 @@
+import { describe, expectTypeOf, it } from "vitest";
+import * as Stagehand from "@browserbasehq/stagehand";
+describe("Schema Utils public API types", () => {
+  describe("defaultExtractSchema", () => {
+    it("infers to the correct type", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("getZodType", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.getZodType
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("isZod3Schema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.isZod3Schema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("isZod4Schema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.isZod4Schema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("jsonSchemaToZod", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.jsonSchemaToZod
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("pageTextSchema", () => {
+    it("infers to the correct type", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("toGeminiSchema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.toGeminiSchema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("toJsonSchema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.toJsonSchema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("transformSchema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.transformSchema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("trimTrailingTextNode", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.trimTrailingTextNode
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("validateZodSchema", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.validateZodSchema
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+});
+//# sourceMappingURL=schema-utils.test.js.map

package/dist/esm/tests/public-api/schema-utils.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/schema-utils.test.ts"],
+  "sourcesContent": ["import { describe, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\ndescribe(\"Schema Utils public API types\", () => {\n  describe(\"defaultExtractSchema\", () => {\n    type ExpectedInferredType = { extraction: string };\n\n    it(\"infers to the correct type\", () => {\n      expectTypeOf<\n        Stagehand.InferStagehandSchema<typeof Stagehand.defaultExtractSchema>\n      >().toEqualTypeOf<ExpectedInferredType>();\n    });\n  });\n\n  describe(\"getZodType\", () => {\n    type ExpectedGetZodTypeParams = [Stagehand.StagehandZodSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.getZodType,\n      ).parameters.branded.toEqualTypeOf<ExpectedGetZodTypeParams>();\n    });\n  });\n\n  describe(\"isZod3Schema\", () => {\n    type ExpectedIsZod3SchemaParams = [Stagehand.StagehandZodSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.isZod3Schema,\n      ).parameters.branded.toEqualTypeOf<ExpectedIsZod3SchemaParams>();\n    });\n  });\n\n  describe(\"isZod4Schema\", () => {\n    type ExpectedIsZod4SchemaParams = [Stagehand.StagehandZodSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.isZod4Schema,\n      ).parameters.branded.toEqualTypeOf<ExpectedIsZod4SchemaParams>();\n    });\n  });\n\n  describe(\"jsonSchemaToZod\", () => {\n    type ExpectedJsonSchemaToZodParams = [Stagehand.JsonSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.jsonSchemaToZod,\n      ).parameters.branded.toEqualTypeOf<ExpectedJsonSchemaToZodParams>();\n    });\n  });\n\n  describe(\"pageTextSchema\", () => {\n    type ExpectedInferredType = { pageText: string };\n\n    it(\"infers to the correct type\", () => {\n      expectTypeOf<\n        Stagehand.InferStagehandSchema<typeof Stagehand.pageTextSchema>\n      >().toEqualTypeOf<ExpectedInferredType>();\n    });\n  });\n\n  describe(\"toGeminiSchema\", () => {\n    type ExpectedToGeminiSchemaParams = [Stagehand.StagehandZodSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.toGeminiSchema,\n      ).parameters.branded.toEqualTypeOf<ExpectedToGeminiSchemaParams>();\n    });\n  });\n\n  describe(\"toJsonSchema\", () => {\n    type ExpectedToJsonSchemaParams = [Stagehand.StagehandZodSchema];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.toJsonSchema,\n      ).parameters.branded.toEqualTypeOf<ExpectedToJsonSchemaParams>();\n    });\n  });\n\n  describe(\"transformSchema\", () => {\n    type ExpectedTransformSchemaParams = [\n      Stagehand.StagehandZodSchema,\n      Array<string | number>,\n    ];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.transformSchema,\n      ).parameters.branded.toEqualTypeOf<ExpectedTransformSchemaParams>();\n    });\n  });\n\n  describe(\"trimTrailingTextNode\", () => {\n    type ExpectedTrimTrailingTextNodeParams = [string | undefined];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.trimTrailingTextNode,\n      ).parameters.branded.toEqualTypeOf<ExpectedTrimTrailingTextNodeParams>();\n    });\n  });\n\n  describe(\"validateZodSchema\", () => {\n    type ExpectedValidateZodSchemaParams = [\n      Stagehand.StagehandZodSchema,\n      unknown,\n    ];\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.validateZodSchema,\n      ).parameters.branded.toEqualTypeOf<ExpectedValidateZodSchemaParams>();\n    });\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,cAAc,UAAU;AAC3C,YAAY,eAAe;AAE3B,SAAS,iCAAiC,MAAM;AAC9C,WAAS,wBAAwB,MAAM;AAGrC,OAAG,8BAA8B,MAAM;AACrC,mBAEE,EAAE,cAAoC;AAAA,IAC1C,CAAC;AAAA,EACH,CAAC;AAED,WAAS,cAAc,MAAM;AAG3B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAAwC;AAAA,IAC/D,CAAC;AAAA,EACH,CAAC;AAED,WAAS,gBAAgB,MAAM;AAG7B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA0C;AAAA,IACjE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,gBAAgB,MAAM;AAG7B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA0C;AAAA,IACjE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,mBAAmB,MAAM;AAGhC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA6C;AAAA,IACpE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAG/B,OAAG,8BAA8B,MAAM;AACrC,mBAEE,EAAE,cAAoC;AAAA,IAC1C,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAG/B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA4C;AAAA,IACnE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,gBAAgB,MAAM;AAG7B,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA0C;AAAA,IACjE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,mBAAmB,MAAM;AAMhC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA6C;AAAA,IACpE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,wBAAwB,MAAM;AAGrC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAAkD;AAAA,IACzE,CAAC;AAAA,EACH,CAAC;AAED,WAAS,qBAAqB,MAAM;AAMlC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAA+C;AAAA,IACtE,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/public-api/timeout-error-types.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import * as Stagehand from "@browserbasehq/stagehand";
+describe("Public timeout error types runtime behavior", () => {
+  describe("ActTimeoutError", () => {
+    it("is exported and extends Error", () => {
+      const error = new Stagehand.ActTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(Stagehand.ActTimeoutError);
+      expect(error.name).toBe("ActTimeoutError");
+    });
+    it("contains timeout value in milliseconds in message", () => {
+      const error = new Stagehand.ActTimeoutError(500);
+      expect(error.message).toContain("500ms");
+    });
+    it("contains operation name in message", () => {
+      const error = new Stagehand.ActTimeoutError(100);
+      expect(error.message).toContain("act()");
+    });
+    it("extends TimeoutError", () => {
+      const error = new Stagehand.ActTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Stagehand.TimeoutError);
+    });
+  });
+  describe("ExtractTimeoutError", () => {
+    it("is exported and extends Error", () => {
+      const error = new Stagehand.ExtractTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(Stagehand.ExtractTimeoutError);
+      expect(error.name).toBe("ExtractTimeoutError");
+    });
+    it("contains timeout value in milliseconds in message", () => {
+      const error = new Stagehand.ExtractTimeoutError(1e3);
+      expect(error.message).toContain("1000ms");
+    });
+    it("contains operation name in message", () => {
+      const error = new Stagehand.ExtractTimeoutError(100);
+      expect(error.message).toContain("extract()");
+    });
+    it("extends TimeoutError", () => {
+      const error = new Stagehand.ExtractTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Stagehand.TimeoutError);
+    });
+  });
+  describe("ObserveTimeoutError", () => {
+    it("is exported and extends Error", () => {
+      const error = new Stagehand.ObserveTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(Stagehand.ObserveTimeoutError);
+      expect(error.name).toBe("ObserveTimeoutError");
+    });
+    it("contains timeout value in milliseconds in message", () => {
+      const error = new Stagehand.ObserveTimeoutError(1500);
+      expect(error.message).toContain("1500ms");
+    });
+    it("contains operation name in message", () => {
+      const error = new Stagehand.ObserveTimeoutError(100);
+      expect(error.message).toContain("observe()");
+    });
+    it("extends TimeoutError", () => {
+      const error = new Stagehand.ObserveTimeoutError(1e3);
+      expect(error).toBeInstanceOf(Stagehand.TimeoutError);
+    });
+  });
+  describe("TimeoutError (base class)", () => {
+    it("is exported and extends Error", () => {
+      const error = new Stagehand.TimeoutError("custom operation", 2e3);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(Stagehand.TimeoutError);
+    });
+    it("contains operation name and timeout in message", () => {
+      const error = new Stagehand.TimeoutError("custom operation", 2e3);
+      expect(error.message).toContain("custom operation");
+      expect(error.message).toContain("2000ms");
+    });
+    it("extends StagehandError", () => {
+      const error = new Stagehand.TimeoutError("operation", 1e3);
+      expect(error).toBeInstanceOf(Stagehand.StagehandError);
+    });
+  });
+});
+//# sourceMappingURL=timeout-error-types.test.js.map

package/dist/esm/tests/public-api/timeout-error-types.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/timeout-error-types.test.ts"],
+  "sourcesContent": ["import { describe, expect, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\n// ============================================================================\n// Public Timeout Error Types Runtime Tests\n// ============================================================================\n// These tests verify the runtime behavior of exported timeout error types,\n// complementing the type-level tests in public-error-types.test.ts\n\ndescribe(\"Public timeout error types runtime behavior\", () => {\n  describe(\"ActTimeoutError\", () => {\n    it(\"is exported and extends Error\", () => {\n      const error = new Stagehand.ActTimeoutError(1000);\n      expect(error).toBeInstanceOf(Error);\n      expect(error).toBeInstanceOf(Stagehand.ActTimeoutError);\n      expect(error.name).toBe(\"ActTimeoutError\");\n    });\n\n    it(\"contains timeout value in milliseconds in message\", () => {\n      const error = new Stagehand.ActTimeoutError(500);\n      expect(error.message).toContain(\"500ms\");\n    });\n\n    it(\"contains operation name in message\", () => {\n      const error = new Stagehand.ActTimeoutError(100);\n      expect(error.message).toContain(\"act()\");\n    });\n\n    it(\"extends TimeoutError\", () => {\n      const error = new Stagehand.ActTimeoutError(1000);\n      expect(error).toBeInstanceOf(Stagehand.TimeoutError);\n    });\n  });\n\n  describe(\"ExtractTimeoutError\", () => {\n    it(\"is exported and extends Error\", () => {\n      const error = new Stagehand.ExtractTimeoutError(1000);\n      expect(error).toBeInstanceOf(Error);\n      expect(error).toBeInstanceOf(Stagehand.ExtractTimeoutError);\n      expect(error.name).toBe(\"ExtractTimeoutError\");\n    });\n\n    it(\"contains timeout value in milliseconds in message\", () => {\n      const error = new Stagehand.ExtractTimeoutError(1000);\n      expect(error.message).toContain(\"1000ms\");\n    });\n\n    it(\"contains operation name in message\", () => {\n      const error = new Stagehand.ExtractTimeoutError(100);\n      expect(error.message).toContain(\"extract()\");\n    });\n\n    it(\"extends TimeoutError\", () => {\n      const error = new Stagehand.ExtractTimeoutError(1000);\n      expect(error).toBeInstanceOf(Stagehand.TimeoutError);\n    });\n  });\n\n  describe(\"ObserveTimeoutError\", () => {\n    it(\"is exported and extends Error\", () => {\n      const error = new Stagehand.ObserveTimeoutError(1000);\n      expect(error).toBeInstanceOf(Error);\n      expect(error).toBeInstanceOf(Stagehand.ObserveTimeoutError);\n      expect(error.name).toBe(\"ObserveTimeoutError\");\n    });\n\n    it(\"contains timeout value in milliseconds in message\", () => {\n      const error = new Stagehand.ObserveTimeoutError(1500);\n      expect(error.message).toContain(\"1500ms\");\n    });\n\n    it(\"contains operation name in message\", () => {\n      const error = new Stagehand.ObserveTimeoutError(100);\n      expect(error.message).toContain(\"observe()\");\n    });\n\n    it(\"extends TimeoutError\", () => {\n      const error = new Stagehand.ObserveTimeoutError(1000);\n      expect(error).toBeInstanceOf(Stagehand.TimeoutError);\n    });\n  });\n\n  describe(\"TimeoutError (base class)\", () => {\n    it(\"is exported and extends Error\", () => {\n      const error = new Stagehand.TimeoutError(\"custom operation\", 2000);\n      expect(error).toBeInstanceOf(Error);\n      expect(error).toBeInstanceOf(Stagehand.TimeoutError);\n    });\n\n    it(\"contains operation name and timeout in message\", () => {\n      const error = new Stagehand.TimeoutError(\"custom operation\", 2000);\n      expect(error.message).toContain(\"custom operation\");\n      expect(error.message).toContain(\"2000ms\");\n    });\n\n    it(\"extends StagehandError\", () => {\n      const error = new Stagehand.TimeoutError(\"operation\", 1000);\n      expect(error).toBeInstanceOf(Stagehand.StagehandError);\n    });\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/tests/public-api/tool-type-export.test.js

@@ -0,0 +1,25 @@
+import { describe, expectTypeOf, it, expect } from "vitest";
+import * as Stagehand from "@browserbasehq/stagehand";
+import { z } from "zod";
+describe("Tool exports from AI SDK", () => {
+  it("exports Tool type that matches AI SDK Tool type", () => {
+    expectTypeOf().toEqualTypeOf();
+  });
+  it("exports tool function", () => {
+    expect(typeof Stagehand.tool).toBe("function");
+  });
+  it("tool function can be used to define custom tools", () => {
+    const customTool = Stagehand.tool({
+      description: "A test tool",
+      inputSchema: z.object({
+        input: z.string()
+      }),
+      execute: async ({ input }) => {
+        return { result: `Processed: ${input}` };
+      }
+    });
+    expect(customTool).toBeDefined();
+    expect(customTool.description).toBe("A test tool");
+  });
+});
+//# sourceMappingURL=tool-type-export.test.js.map

package/dist/esm/tests/public-api/tool-type-export.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/tool-type-export.test.ts"],
+  "sourcesContent": ["import { describe, expectTypeOf, it, expect } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\nimport { type Tool } from \"ai\";\nimport { z } from \"zod\";\n\n/**\n * Test to verify tool-related exports from Stagehand.\n * Users should be able to create custom tools using the exported `tool` function\n * without needing to install the ai package directly.\n */\ndescribe(\"Tool exports from AI SDK\", () => {\n  it(\"exports Tool type that matches AI SDK Tool type\", () => {\n    expectTypeOf<Stagehand.Tool>().toEqualTypeOf<Tool>();\n  });\n\n  it(\"exports tool function\", () => {\n    expect(typeof Stagehand.tool).toBe(\"function\");\n  });\n\n  it(\"tool function can be used to define custom tools\", () => {\n    const customTool = Stagehand.tool({\n      description: \"A test tool\",\n      inputSchema: z.object({\n        input: z.string(),\n      }),\n      execute: async ({ input }) => {\n        return { result: `Processed: ${input}` };\n      },\n    });\n\n    expect(customTool).toBeDefined();\n    expect(customTool.description).toBe(\"A test tool\");\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,cAAc,IAAI,cAAc;AACnD,YAAY,eAAe;AAE3B,SAAS,SAAS;AAOlB,SAAS,4BAA4B,MAAM;AACzC,KAAG,mDAAmD,MAAM;AAC1D,iBAA6B,EAAE,cAAoB;AAAA,EACrD,CAAC;AAED,KAAG,yBAAyB,MAAM;AAChC,WAAO,OAAO,UAAU,IAAI,EAAE,KAAK,UAAU;AAAA,EAC/C,CAAC;AAED,KAAG,oDAAoD,MAAM;AAC3D,UAAM,aAAa,UAAU,KAAK;AAAA,MAChC,aAAa;AAAA,MACb,aAAa,EAAE,OAAO;AAAA,QACpB,OAAO,EAAE,OAAO;AAAA,MAClB,CAAC;AAAA,MACD,SAAS,OAAO,EAAE,MAAM,MAAM;AAC5B,eAAO,EAAE,QAAQ,cAAc,KAAK,GAAG;AAAA,MACzC;AAAA,IACF,CAAC;AAED,WAAO,UAAU,EAAE,YAAY;AAC/B,WAAO,WAAW,WAAW,EAAE,KAAK,aAAa;AAAA,EACnD,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/public-api/v3-core.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import * as Stagehand from "@browserbasehq/stagehand";
+describe("V3 Core public API types", () => {
+  describe("Stagehand", () => {
+    it("has correct public interface shape", () => {
+      expectTypeOf().toExtend();
+    });
+    it("act accepts Action as first parameter", () => {
+      const mockAction = {};
+      expectTypeOf().toBeCallableWith(
+        mockAction,
+        {}
+      );
+    });
+    it("extract accepts instruction and schema", () => {
+      const mockSchema = {};
+      expectTypeOf().toBeCallableWith(
+        "instruction",
+        mockSchema,
+        {}
+      );
+    });
+    it("observe accepts instruction and options", () => {
+      expectTypeOf().toBeCallableWith(
+        "instruction",
+        {}
+      );
+    });
+    it("agent execute accepts page option", () => {
+      const mockPage = {};
+      expectTypeOf().toBeCallableWith({
+        instruction: "test",
+        page: mockPage
+      });
+    });
+  });
+  describe("StagehandMetrics", () => {
+    it("matches the published metrics shape", () => {
+      expectTypeOf().toEqualTypeOf();
+    });
+  });
+  describe("V3", () => {
+    it("is exported", () => {
+      expect(Stagehand.V3).toBeDefined();
+    });
+  });
+  describe("V3Evaluator", () => {
+    it("is exported", () => {
+      expect(Stagehand.V3Evaluator).toBeDefined();
+    });
+    it("has ask method", () => {
+      expectTypeOf().toExtend();
+    });
+    it("has batchAsk method", () => {
+      expectTypeOf().toExtend();
+    });
+  });
+  describe("V3FunctionName", () => {
+    const expectedFunctionNames = [
+      "ACT",
+      "EXTRACT",
+      "OBSERVE",
+      "AGENT"
+    ];
+    it("matches the known function name literals", () => {
+      expectTypeOf().toExtend();
+    });
+  });
+  describe("connectToMCPServer", () => {
+    it("has correct parameter types", () => {
+      expectTypeOf(
+        Stagehand.connectToMCPServer
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  describe("LOG_LEVEL_NAMES", () => {
+    it("maps numeric levels to strings", () => {
+      expectTypeOf().toExtend();
+    });
+  });
+});
+//# sourceMappingURL=v3-core.test.js.map

package/dist/esm/tests/public-api/v3-core.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/v3-core.test.ts"],
+  "sourcesContent": ["import { describe, expect, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\ndescribe(\"V3 Core public API types\", () => {\n  describe(\"Stagehand\", () => {\n    type ExpectedShape = {\n      init: () => Promise<void>;\n      close: (opts?: { force?: boolean }) => Promise<void>;\n      act: (\n        input: string | Stagehand.Action,\n        options?: Stagehand.ActOptions,\n      ) => Promise<Stagehand.ActResult>;\n      extract: (...args: unknown[]) => Promise<unknown>;\n      observe: (...args: unknown[]) => Promise<Stagehand.Action[]>;\n      agent: (config?: Stagehand.AgentConfig) => {\n        execute: (\n          instructionOrOptions: string | Stagehand.AgentExecuteOptions,\n        ) => Promise<Stagehand.AgentResult>;\n      };\n      connectURL: () => string;\n      context: unknown;\n      metrics: Promise<Stagehand.StagehandMetrics>;\n      history: Promise<ReadonlyArray<Stagehand.HistoryEntry>>;\n      llmClient: Stagehand.LLMClient;\n      browserbaseSessionID: string | undefined;\n      browserbaseSessionURL: string | undefined;\n      browserbaseDebugURL: string | undefined;\n      experimental: boolean;\n      logInferenceToFile: boolean;\n      verbose: 0 | 1 | 2;\n      logger: (logLine: Stagehand.LogLine) => void;\n      isAgentReplayActive: () => boolean;\n      recordAgentReplayStep: (step: unknown) => void;\n    };\n\n    type StagehandInstance = InstanceType<typeof Stagehand.Stagehand>;\n\n    it(\"has correct public interface shape\", () => {\n      expectTypeOf<StagehandInstance>().toExtend<ExpectedShape>();\n    });\n\n    it(\"act accepts Action as first parameter\", () => {\n      const mockAction = {} as Stagehand.Action;\n      expectTypeOf<StagehandInstance[\"act\"]>().toBeCallableWith(\n        mockAction,\n        {} as Stagehand.ActOptions,\n      );\n    });\n\n    it(\"extract accepts instruction and schema\", () => {\n      const mockSchema = {} as Stagehand.StagehandZodSchema;\n      expectTypeOf<StagehandInstance[\"extract\"]>().toBeCallableWith(\n        \"instruction\",\n        mockSchema,\n        {} as Stagehand.ExtractOptions,\n      );\n    });\n\n    it(\"observe accepts instruction and options\", () => {\n      expectTypeOf<StagehandInstance[\"observe\"]>().toBeCallableWith(\n        \"instruction\",\n        {} as Stagehand.ObserveOptions,\n      );\n    });\n\n    it(\"agent execute accepts page option\", () => {\n      type AgentReturn = ReturnType<StagehandInstance[\"agent\"]>;\n      const mockPage = {} as Stagehand.AnyPage;\n      expectTypeOf<AgentReturn[\"execute\"]>().toBeCallableWith({\n        instruction: \"test\",\n        page: mockPage,\n      } satisfies Stagehand.AgentExecuteOptions);\n    });\n  });\n\n  describe(\"StagehandMetrics\", () => {\n    type ExpectedStagehandMetrics = {\n      actPromptTokens: number;\n      actCompletionTokens: number;\n      actReasoningTokens: number;\n      actCachedInputTokens: number;\n      actInferenceTimeMs: number;\n      extractPromptTokens: number;\n      extractCompletionTokens: number;\n      extractReasoningTokens: number;\n      extractCachedInputTokens: number;\n      extractInferenceTimeMs: number;\n      observePromptTokens: number;\n      observeCompletionTokens: number;\n      observeReasoningTokens: number;\n      observeCachedInputTokens: number;\n      observeInferenceTimeMs: number;\n      agentPromptTokens: number;\n      agentCompletionTokens: number;\n      agentReasoningTokens: number;\n      agentCachedInputTokens: number;\n      agentInferenceTimeMs: number;\n      totalPromptTokens: number;\n      totalCompletionTokens: number;\n      totalReasoningTokens: number;\n      totalCachedInputTokens: number;\n      totalInferenceTimeMs: number;\n    };\n\n    it(\"matches the published metrics shape\", () => {\n      expectTypeOf<Stagehand.StagehandMetrics>().toEqualTypeOf<ExpectedStagehandMetrics>();\n    });\n  });\n\n  describe(\"V3\", () => {\n    // V3 is the same class as Stagehand, just re-exported with a different name.\n    // The public interface shape is already tested in the \"Stagehand\" test above.\n    it(\"is exported\", () => {\n      expect(Stagehand.V3).toBeDefined();\n    });\n  });\n\n  describe(\"V3Evaluator\", () => {\n    type V3EvaluatorInstance = InstanceType<typeof Stagehand.V3Evaluator>;\n\n    it(\"is exported\", () => {\n      expect(Stagehand.V3Evaluator).toBeDefined();\n    });\n\n    it(\"has ask method\", () => {\n      expectTypeOf<V3EvaluatorInstance[\"ask\"]>().toExtend<\n        (options: unknown) => Promise<unknown>\n      >();\n    });\n\n    it(\"has batchAsk method\", () => {\n      expectTypeOf<V3EvaluatorInstance[\"batchAsk\"]>().toExtend<\n        (options: unknown) => Promise<unknown[]>\n      >();\n    });\n  });\n\n  describe(\"V3FunctionName\", () => {\n    const expectedFunctionNames = [\n      \"ACT\",\n      \"EXTRACT\",\n      \"OBSERVE\",\n      \"AGENT\",\n    ] as const;\n\n    it(\"matches the known function name literals\", () => {\n      expectTypeOf<Stagehand.V3FunctionName>().toExtend<\n        (typeof expectedFunctionNames)[number]\n      >();\n      void expectedFunctionNames; // Mark as used to satisfy ESLint\n    });\n  });\n\n  describe(\"connectToMCPServer\", () => {\n    type ExpectedServerConfig =\n      | string\n      | URL\n      | { command: string; args?: string[]; env?: Record<string, string> }\n      | { serverUrl: string | URL; clientOptions?: unknown };\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.connectToMCPServer,\n      ).parameters.branded.toEqualTypeOf<[ExpectedServerConfig]>();\n    });\n  });\n\n  describe(\"LOG_LEVEL_NAMES\", () => {\n    type ExpectedLOG_LEVEL_NAMES = Record<Stagehand.LogLevel, string>;\n\n    it(\"maps numeric levels to strings\", () => {\n      expectTypeOf<\n        typeof Stagehand.LOG_LEVEL_NAMES\n      >().toExtend<ExpectedLOG_LEVEL_NAMES>();\n    });\n  });\n});\n"],
+  "mappings": "AAAA,SAAS,UAAU,QAAQ,cAAc,UAAU;AACnD,YAAY,eAAe;AAE3B,SAAS,4BAA4B,MAAM;AACzC,WAAS,aAAa,MAAM;AAiC1B,OAAG,sCAAsC,MAAM;AAC7C,mBAAgC,EAAE,SAAwB;AAAA,IAC5D,CAAC;AAED,OAAG,yCAAyC,MAAM;AAChD,YAAM,aAAa,CAAC;AACpB,mBAAuC,EAAE;AAAA,QACvC;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,OAAG,0CAA0C,MAAM;AACjD,YAAM,aAAa,CAAC;AACpB,mBAA2C,EAAE;AAAA,QAC3C;AAAA,QACA;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,OAAG,2CAA2C,MAAM;AAClD,mBAA2C,EAAE;AAAA,QAC3C;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,OAAG,qCAAqC,MAAM;AAE5C,YAAM,WAAW,CAAC;AAClB,mBAAqC,EAAE,iBAAiB;AAAA,QACtD,aAAa;AAAA,QACb,MAAM;AAAA,MACR,CAAyC;AAAA,IAC3C,CAAC;AAAA,EACH,CAAC;AAED,WAAS,oBAAoB,MAAM;AA6BjC,OAAG,uCAAuC,MAAM;AAC9C,mBAAyC,EAAE,cAAwC;AAAA,IACrF,CAAC;AAAA,EACH,CAAC;AAED,WAAS,MAAM,MAAM;AAGnB,OAAG,eAAe,MAAM;AACtB,aAAO,UAAU,EAAE,EAAE,YAAY;AAAA,IACnC,CAAC;AAAA,EACH,CAAC;AAED,WAAS,eAAe,MAAM;AAG5B,OAAG,eAAe,MAAM;AACtB,aAAO,UAAU,WAAW,EAAE,YAAY;AAAA,IAC5C,CAAC;AAED,OAAG,kBAAkB,MAAM;AACzB,mBAAyC,EAAE,SAEzC;AAAA,IACJ,CAAC;AAED,OAAG,uBAAuB,MAAM;AAC9B,mBAA8C,EAAE,SAE9C;AAAA,IACJ,CAAC;AAAA,EACH,CAAC;AAED,WAAS,kBAAkB,MAAM;AAC/B,UAAM,wBAAwB;AAAA,MAC5B;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,OAAG,4CAA4C,MAAM;AACnD,mBAAuC,EAAE,SAEvC;AAAA,IAEJ,CAAC;AAAA,EACH,CAAC;AAED,WAAS,sBAAsB,MAAM;AAOnC,OAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAAsC;AAAA,IAC7D,CAAC;AAAA,EACH,CAAC;AAED,WAAS,mBAAmB,MAAM;AAGhC,OAAG,kCAAkC,MAAM;AACzC,mBAEE,EAAE,SAAkC;AAAA,IACxC,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/esm/tests/safety-confirmation.test.js

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi } from "vitest";
+import { OpenAICUAClient } from "../lib/v3/agent/OpenAICUAClient.js";
+import { GoogleCUAClient } from "../lib/v3/agent/GoogleCUAClient.js";
+const openAISafetyInvoker = OpenAICUAClient.prototype.handleSafetyConfirmation;
+const googleSafetyInvoker = GoogleCUAClient.prototype.handleSafetyConfirmation;
+function createOpenAIClient() {
+  return new OpenAICUAClient(
+    "openai",
+    "openai/computer-use-preview",
+    "test instructions",
+    { apiKey: "test" }
+  );
+}
+function createGoogleClient() {
+  return new GoogleCUAClient(
+    "google",
+    "google/gemini-2.5-computer-use-preview-10-2025",
+    "test instructions",
+    { apiKey: "test" }
+  );
+}
+describe("Safety Confirmation Handler", () => {
+  describe("OpenAI-style (pending_safety_checks)", () => {
+    const mockChecks = [
+      {
+        id: "check-1",
+        code: "malicious_instructions",
+        message: "Potentially harmful action detected"
+      }
+    ];
+    it("returns checks when handler acknowledges", async () => {
+      const client = createOpenAIClient();
+      const handler = vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      expect(handler).toHaveBeenCalledWith(mockChecks);
+      expect(result).toEqual(mockChecks);
+    });
+    it("returns undefined when handler rejects", async () => {
+      const client = createOpenAIClient();
+      const handler = vi.fn(async () => ({
+        acknowledged: false
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      expect(handler).toHaveBeenCalledWith(mockChecks);
+      expect(result).toBeUndefined();
+    });
+    it("auto-acknowledges when no handler is set", async () => {
+      const client = createOpenAIClient();
+      const logger = vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      expect(result).toEqual(mockChecks);
+    });
+  });
+  describe("Google-style (safety_decision)", () => {
+    const mockDecision = {
+      decision: "require_confirmation",
+      explanation: "Cookie consent dialog detected"
+    };
+    it("returns 'true' when handler acknowledges", async () => {
+      const client = createGoogleClient();
+      const handler = vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      expect(handler).toHaveBeenCalledWith([
+        {
+          id: "google-safety-decision",
+          code: "safety_decision",
+          message: JSON.stringify(mockDecision, null, 2)
+        }
+      ]);
+      expect(result).toBe("true");
+    });
+    it("returns undefined when handler rejects", async () => {
+      const client = createGoogleClient();
+      const handler = vi.fn(async () => ({
+        acknowledged: false
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      expect(handler).toHaveBeenCalled();
+      expect(result).toBeUndefined();
+    });
+    it("auto-acknowledges when no handler is set", async () => {
+      const client = createGoogleClient();
+      const logger = vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      expect(result).toBe("true");
+    });
+    it("handles string safety decisions", async () => {
+      const client = createGoogleClient();
+      const handler = vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        "Simple string decision",
+        logger
+      );
+      expect(handler).toHaveBeenCalledWith([
+        {
+          id: "google-safety-decision",
+          code: "safety_decision",
+          message: "Simple string decision"
+        }
+      ]);
+      expect(result).toBe("true");
+    });
+  });
+});
+//# sourceMappingURL=safety-confirmation.test.js.map