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

package/dist/cjs/tests/timeout-handlers.test.js

@@ -0,0 +1,864 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+var import_actHandler = require("../lib/v3/handlers/actHandler.js");
+var import_extractHandler = require("../lib/v3/handlers/extractHandler.js");
+var import_observeHandler = require("../lib/v3/handlers/observeHandler.js");
+var import_timeoutGuard = require("../lib/v3/handlers/handlerUtils/timeoutGuard.js");
+var import_actHandlerUtils = require("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+var import_snapshot = require("../lib/v3/understudy/a11y/snapshot/index.js");
+var import_sdkErrors = require("../lib/v3/types/public/sdkErrors.js");
+var import_inference = require("../lib/inference.js");
+var import_methods = require("../lib/v3/types/public/methods.js");
+import_vitest.vi.mock("../lib/v3/handlers/handlerUtils/timeoutGuard", () => ({
+  createTimeoutGuard: import_vitest.vi.fn()
+}));
+import_vitest.vi.mock("../lib/v3/handlers/handlerUtils/actHandlerUtils", () => ({
+  waitForDomNetworkQuiet: import_vitest.vi.fn(),
+  performUnderstudyMethod: import_vitest.vi.fn()
+}));
+import_vitest.vi.mock("../lib/v3/understudy/a11y/snapshot", () => ({
+  captureHybridSnapshot: import_vitest.vi.fn(),
+  diffCombinedTrees: import_vitest.vi.fn()
+}));
+import_vitest.vi.mock("../lib/inference", () => ({
+  act: import_vitest.vi.fn(),
+  extract: import_vitest.vi.fn(),
+  observe: import_vitest.vi.fn()
+}));
+(0, import_vitest.describe)("ActHandler timeout guard", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError when timeout expires before snapshot", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ActTimeoutError);
+    (0, import_vitest.expect)(waitForDomNetworkQuietMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError when timeout expires before LLM call", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 3) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ActTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(actInferenceMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError with correct message format", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const timeoutMs = 100;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return import_vitest.vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new import_sdkErrors.ActTimeoutError(ms);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.act({
+        instruction: "do something",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ActTimeoutError to be thrown");
+    } catch (error) {
+      (0, import_vitest.expect)(error).toBeInstanceOf(import_sdkErrors.ActTimeoutError);
+      (0, import_vitest.expect)(error.message).toContain("act()");
+      (0, import_vitest.expect)(error.message).toContain(`${timeoutMs}ms`);
+      (0, import_vitest.expect)(error.name).toBe("ActTimeoutError");
+    }
+  });
+});
+(0, import_vitest.describe)("ActHandler two-step timeout", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError during step 2; step 2 action does not run", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValueOnce({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: true,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    const diffCombinedTreesMock = import_vitest.vi.mocked(
+      (await import("../lib/v3/understudy/a11y/snapshot/index.js")).diffCombinedTrees
+    );
+    diffCombinedTreesMock.mockReturnValue("diff tree");
+    let callCount = 0;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return import_vitest.vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 7) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.act({
+        instruction: "click then type",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(import_sdkErrors.ActTimeoutError);
+    (0, import_vitest.expect)(performUnderstudyMethodMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(actInferenceMock).toHaveBeenCalledTimes(1);
+  });
+});
+(0, import_vitest.describe)("ActHandler self-heal timeout", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError during self-heal snapshot; no retry action executes", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockRejectedValueOnce(
+      new Error("Element not found")
+    );
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    let callCount = 0;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return import_vitest.vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 7) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler({ selfHeal: true });
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.act({
+        instruction: "click button",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(import_sdkErrors.ActTimeoutError);
+    (0, import_vitest.expect)(performUnderstudyMethodMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(actInferenceMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ActTimeoutError during self-heal LLM inference; no retry action executes", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockRejectedValueOnce(
+      new Error("Element not found")
+    );
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValueOnce({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    let callCount = 0;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return import_vitest.vi.fn(() => {
+          callCount += 1;
+          if (callCount >= 8) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ActTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildActHandler({ selfHeal: true });
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.act({
+        instruction: "click button",
+        page: fakePage,
+        timeout: 50
+      })
+    ).rejects.toThrow(import_sdkErrors.ActTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).toHaveBeenCalledTimes(2);
+    (0, import_vitest.expect)(actInferenceMock).toHaveBeenCalledTimes(1);
+  });
+});
+(0, import_vitest.describe)("ExtractHandler timeout guard", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("throws ExtractTimeoutError when timeout expires before snapshot", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = import_vitest.vi.mocked(import_inference.extract);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return import_vitest.vi.fn(() => {
+          throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ExtractTimeoutError(timeoutMs);
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ExtractTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).not.toHaveBeenCalled();
+    (0, import_vitest.expect)(extractInferenceMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ExtractTimeoutError when timeout expires before LLM call", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = import_vitest.vi.mocked(import_inference.extract);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ExtractTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ExtractTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(extractInferenceMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ExtractTimeoutError with correct message format", async () => {
+    const timeoutMs = 200;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return import_vitest.vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new import_sdkErrors.ExtractTimeoutError(ms);
+      });
+    });
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.extract({
+        instruction: "extract title",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ExtractTimeoutError to be thrown");
+    } catch (error) {
+      (0, import_vitest.expect)(error).toBeInstanceOf(import_sdkErrors.ExtractTimeoutError);
+      (0, import_vitest.expect)(error.message).toContain("extract()");
+      (0, import_vitest.expect)(error.message).toContain(
+        `${timeoutMs}ms`
+      );
+      (0, import_vitest.expect)(error.name).toBe("ExtractTimeoutError");
+    }
+  });
+  (0, import_vitest.it)("stops LLM and post-processing when timeout expires", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: { "1-0": "https://example.com" }
+    });
+    const extractInferenceMock = import_vitest.vi.mocked(import_inference.extract);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ExtractTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildExtractHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.extract({
+        instruction: "extract links",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ExtractTimeoutError);
+    (0, import_vitest.expect)(extractInferenceMock).not.toHaveBeenCalled();
+  });
+});
+(0, import_vitest.describe)("ObserveHandler timeout guard", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("throws ObserveTimeoutError when timeout expires before snapshot", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = import_vitest.vi.mocked(import_inference.observe);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        return import_vitest.vi.fn(() => {
+          throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ObserveTimeoutError(timeoutMs);
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ObserveTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).not.toHaveBeenCalled();
+    (0, import_vitest.expect)(observeInferenceMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ObserveTimeoutError when timeout expires before LLM call", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = import_vitest.vi.mocked(import_inference.observe);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ObserveTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ObserveTimeoutError);
+    (0, import_vitest.expect)(captureHybridSnapshotMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(observeInferenceMock).not.toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("throws ObserveTimeoutError with correct message format", async () => {
+    const timeoutMs = 150;
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation((ms, errorFactory) => {
+      return import_vitest.vi.fn(() => {
+        throw errorFactory ? errorFactory(ms) : new import_sdkErrors.ObserveTimeoutError(ms);
+      });
+    });
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    try {
+      await handler.observe({
+        instruction: "find buttons",
+        page: fakePage,
+        timeout: timeoutMs
+      });
+      throw new Error("Expected ObserveTimeoutError to be thrown");
+    } catch (error) {
+      (0, import_vitest.expect)(error).toBeInstanceOf(import_sdkErrors.ObserveTimeoutError);
+      (0, import_vitest.expect)(error.message).toContain("observe()");
+      (0, import_vitest.expect)(error.message).toContain(
+        `${timeoutMs}ms`
+      );
+      (0, import_vitest.expect)(error.name).toBe("ObserveTimeoutError");
+    }
+  });
+  (0, import_vitest.it)("aborts result processing when timeout expires", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = import_vitest.vi.mocked(import_inference.observe);
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(
+      (timeoutMs, errorFactory) => {
+        let calls = 0;
+        return import_vitest.vi.fn(() => {
+          calls += 1;
+          if (calls >= 2) {
+            throw errorFactory ? errorFactory(timeoutMs) : new import_sdkErrors.ObserveTimeoutError(timeoutMs);
+          }
+        });
+      }
+    );
+    const handler = buildObserveHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    await (0, import_vitest.expect)(
+      handler.observe({
+        instruction: "find all interactive elements",
+        page: fakePage,
+        timeout: 5
+      })
+    ).rejects.toThrow(import_sdkErrors.ObserveTimeoutError);
+    (0, import_vitest.expect)(observeInferenceMock).not.toHaveBeenCalled();
+  });
+});
+(0, import_vitest.describe)("No-timeout success paths", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.clearAllMocks();
+  });
+  (0, import_vitest.it)("act() completes successfully without timeout and records metrics", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      reasoning_tokens: 10,
+      cached_input_tokens: 5,
+      inference_time_ms: 500
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(() => {
+      return import_vitest.vi.fn(() => {
+      });
+    });
+    const metricsCallback = import_vitest.vi.fn();
+    const handler = buildActHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage
+      // No timeout specified
+    });
+    (0, import_vitest.expect)(result.success).toBe(true);
+    (0, import_vitest.expect)(metricsCallback).toHaveBeenCalledWith(
+      import_methods.V3FunctionName.ACT,
+      100,
+      50,
+      10,
+      5,
+      500
+    );
+  });
+  (0, import_vitest.it)("extract() completes successfully without timeout and records metrics", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: {},
+      combinedUrlMap: {}
+    });
+    const extractInferenceMock = import_vitest.vi.mocked(import_inference.extract);
+    extractInferenceMock.mockResolvedValue({
+      title: "Test Title",
+      metadata: { completed: true, progress: "100%" },
+      prompt_tokens: 200,
+      completion_tokens: 100,
+      reasoning_tokens: 20,
+      cached_input_tokens: 10,
+      inference_time_ms: 800
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(() => {
+      return import_vitest.vi.fn(() => {
+      });
+    });
+    const metricsCallback = import_vitest.vi.fn();
+    const handler = buildExtractHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    const result = await handler.extract({
+      instruction: "extract title",
+      page: fakePage
+      // No timeout specified
+    });
+    (0, import_vitest.expect)(result).toHaveProperty("title", "Test Title");
+    (0, import_vitest.expect)(metricsCallback).toHaveBeenCalledWith(
+      import_methods.V3FunctionName.EXTRACT,
+      200,
+      100,
+      20,
+      10,
+      800
+    );
+  });
+  (0, import_vitest.it)("observe() completes successfully without timeout and records metrics", async () => {
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const observeInferenceMock = import_vitest.vi.mocked(import_inference.observe);
+    observeInferenceMock.mockResolvedValue({
+      elements: [
+        {
+          elementId: "1-0",
+          description: "Submit button"
+        }
+      ],
+      prompt_tokens: 150,
+      completion_tokens: 75,
+      reasoning_tokens: 15,
+      cached_input_tokens: 8,
+      inference_time_ms: 600
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation(() => {
+      return import_vitest.vi.fn(() => {
+      });
+    });
+    const metricsCallback = import_vitest.vi.fn();
+    const handler = buildObserveHandler({ onMetrics: metricsCallback });
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    const result = await handler.observe({
+      instruction: "find buttons",
+      page: fakePage
+      // No timeout specified
+    });
+    (0, import_vitest.expect)(result).toHaveLength(1);
+    (0, import_vitest.expect)(result[0]).toHaveProperty("description", "Submit button");
+    (0, import_vitest.expect)(metricsCallback).toHaveBeenCalledWith(
+      import_methods.V3FunctionName.OBSERVE,
+      150,
+      75,
+      15,
+      8,
+      600
+    );
+  });
+  (0, import_vitest.it)("act() with zero timeout behaves as no timeout", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation((timeoutMs) => {
+      if (!timeoutMs || timeoutMs <= 0) {
+        return import_vitest.vi.fn(() => {
+        });
+      }
+      return import_vitest.vi.fn(() => {
+        throw new import_sdkErrors.ActTimeoutError(timeoutMs);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage,
+      timeout: 0
+      // Zero timeout should be treated as "no timeout"
+    });
+    (0, import_vitest.expect)(result.success).toBe(true);
+  });
+  (0, import_vitest.it)("act() with negative timeout behaves as no timeout", async () => {
+    const waitForDomNetworkQuietMock = import_vitest.vi.mocked(import_actHandlerUtils.waitForDomNetworkQuiet);
+    waitForDomNetworkQuietMock.mockResolvedValue(void 0);
+    const captureHybridSnapshotMock = import_vitest.vi.mocked(import_snapshot.captureHybridSnapshot);
+    captureHybridSnapshotMock.mockResolvedValue({
+      combinedTree: "tree content",
+      combinedXpathMap: { "1-0": "/html/body/button" },
+      combinedUrlMap: {}
+    });
+    const { performUnderstudyMethod } = await import("../lib/v3/handlers/handlerUtils/actHandlerUtils.js");
+    const performUnderstudyMethodMock = import_vitest.vi.mocked(performUnderstudyMethod);
+    performUnderstudyMethodMock.mockResolvedValue(void 0);
+    const actInferenceMock = import_vitest.vi.mocked(import_inference.act);
+    actInferenceMock.mockResolvedValue({
+      element: {
+        elementId: "1-0",
+        description: "click button",
+        method: "click",
+        arguments: []
+      },
+      twoStep: false,
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      inference_time_ms: 500
+    });
+    import_vitest.vi.mocked(import_timeoutGuard.createTimeoutGuard).mockImplementation((timeoutMs) => {
+      if (!timeoutMs || timeoutMs <= 0) {
+        return import_vitest.vi.fn(() => {
+        });
+      }
+      return import_vitest.vi.fn(() => {
+        throw new import_sdkErrors.ActTimeoutError(timeoutMs);
+      });
+    });
+    const handler = buildActHandler();
+    const fakePage = {
+      mainFrame: import_vitest.vi.fn().mockReturnValue({})
+    };
+    const result = await handler.act({
+      instruction: "click button",
+      page: fakePage,
+      timeout: -100
+      // Negative timeout should be treated as "no timeout"
+    });
+    (0, import_vitest.expect)(result.success).toBe(true);
+  });
+});
+function buildActHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = import_vitest.vi.fn().mockReturnValue(fakeClient);
+  return new import_actHandler.ActHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    options.selfHeal ?? false,
+    options.onMetrics,
+    void 0
+  );
+}
+function buildExtractHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = import_vitest.vi.fn().mockReturnValue(fakeClient);
+  return new import_extractHandler.ExtractHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    false,
+    options.onMetrics
+  );
+}
+function buildObserveHandler(options = {}) {
+  const defaultClientOptions = {};
+  const fakeClient = {
+    type: "openai",
+    modelName: "gpt-4o",
+    clientOptions: defaultClientOptions
+  };
+  const resolveLlmClient = import_vitest.vi.fn().mockReturnValue(fakeClient);
+  return new import_observeHandler.ObserveHandler(
+    fakeClient,
+    "gpt-4o",
+    defaultClientOptions,
+    resolveLlmClient,
+    void 0,
+    false,
+    false,
+    options.onMetrics
+  );
+}
+//# sourceMappingURL=timeout-handlers.test.js.map