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

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

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/safety-confirmation.test.ts"],
+  "sourcesContent": ["import { describe, it, expect, vi } from \"vitest\";\nimport { OpenAICUAClient } from \"../lib/v3/agent/OpenAICUAClient.js\";\nimport { GoogleCUAClient } from \"../lib/v3/agent/GoogleCUAClient.js\";\nimport type {\n  SafetyCheck,\n  SafetyConfirmationHandler,\n} from \"../lib/v3/types/public/agent.js\";\nimport type { LogLine } from \"../lib/v3/types/public/logs.js\";\n\ntype LoggerMock = (message: LogLine) => void;\n\nconst openAISafetyInvoker = (\n  OpenAICUAClient.prototype as unknown as {\n    handleSafetyConfirmation: (\n      this: OpenAICUAClient,\n      pendingSafetyChecks: SafetyCheck[],\n      logger: LoggerMock,\n    ) => Promise<SafetyCheck[] | undefined>;\n  }\n).handleSafetyConfirmation;\n\nconst googleSafetyInvoker = (\n  GoogleCUAClient.prototype as unknown as {\n    handleSafetyConfirmation: (\n      this: GoogleCUAClient,\n      safetyDecision: unknown,\n      logger: LoggerMock,\n    ) => Promise<string | undefined>;\n  }\n).handleSafetyConfirmation;\n\nfunction createOpenAIClient(): OpenAICUAClient {\n  return new OpenAICUAClient(\n    \"openai\",\n    \"openai/computer-use-preview\",\n    \"test instructions\",\n    { apiKey: \"test\" },\n  );\n}\n\nfunction createGoogleClient(): GoogleCUAClient {\n  return new GoogleCUAClient(\n    \"google\",\n    \"google/gemini-2.5-computer-use-preview-10-2025\",\n    \"test instructions\",\n    { apiKey: \"test\" },\n  );\n}\n\ndescribe(\"Safety Confirmation Handler\", () => {\n  describe(\"OpenAI-style (pending_safety_checks)\", () => {\n    const mockChecks: SafetyCheck[] = [\n      {\n        id: \"check-1\",\n        code: \"malicious_instructions\",\n        message: \"Potentially harmful action detected\",\n      },\n    ];\n\n    it(\"returns checks when handler acknowledges\", async () => {\n      const client = createOpenAIClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n\n      expect(handler).toHaveBeenCalledWith(mockChecks);\n      expect(result).toEqual(mockChecks);\n    });\n\n    it(\"returns undefined when handler rejects\", async () => {\n      const client = createOpenAIClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: false,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n\n      expect(handler).toHaveBeenCalledWith(mockChecks);\n      expect(result).toBeUndefined();\n    });\n\n    it(\"auto-acknowledges when no handler is set\", async () => {\n      const client = createOpenAIClient();\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n      expect(result).toEqual(mockChecks);\n    });\n  });\n\n  describe(\"Google-style (safety_decision)\", () => {\n    const mockDecision = {\n      decision: \"require_confirmation\",\n      explanation: \"Cookie consent dialog detected\",\n    };\n\n    it(\"returns 'true' when handler acknowledges\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalledWith([\n        {\n          id: \"google-safety-decision\",\n          code: \"safety_decision\",\n          message: JSON.stringify(mockDecision, null, 2),\n        },\n      ]);\n      expect(result).toBe(\"true\");\n    });\n\n    it(\"returns undefined when handler rejects\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: false,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalled();\n      expect(result).toBeUndefined();\n    });\n\n    it(\"auto-acknowledges when no handler is set\", async () => {\n      const client = createGoogleClient();\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n      expect(result).toBe(\"true\");\n    });\n\n    it(\"handles string safety decisions\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        \"Simple string decision\",\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalledWith([\n        {\n          id: \"google-safety-decision\",\n          code: \"safety_decision\",\n          message: \"Simple string decision\",\n        },\n      ]);\n      expect(result).toBe(\"true\");\n    });\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}