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

package/dist/esm/lib/v3/handlers/handlerUtils/actHandlerUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actHandlerUtils.js","sourceRoot":"","sources":["../../../../../../lib/v3/handlers/handlerUtils/actHandlerUtils.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/handlerUtils/actHandlerUtils.ts\nimport { Protocol } from \"devtools-protocol\";\nimport { Frame } from \"../../understudy/frame.js\";\nimport { Locator } from \"../../understudy/locator.js\";\nimport { MouseButton } from \"../../types/public/locator.js\";\nimport { resolveLocatorWithHops } from \"../../understudy/deepLocator.js\";\nimport type { Page } from \"../../understudy/page.js\";\nimport { v3Logger } from \"../../logger.js\";\nimport { SessionFileLogger } from \"../../flowLogger.js\";\nimport { StagehandClickError } from \"../../types/public/sdkErrors.js\";\n\nexport class UnderstudyCommandException extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"UnderstudyCommandException\";\n  }\n}\n\nexport interface UnderstudyMethodHandlerContext {\n  method: string;\n  locator: Locator;\n  xpath: string;\n  args: ReadonlyArray<string>;\n  frame: Frame;\n  page: Page;\n  initialUrl: string;\n  domSettleTimeoutMs?: number;\n}\n\n// Normalize cases where the XPath is the root \"/\" to point to the HTML element.\nfunction normalizeRootXPath(input: string): string {\n  const s = String(input ?? \"\").trim();\n  if (s === \"/\") return \"/html\";\n  if (/^xpath=\\/$/i.test(s)) return \"xpath=/html\";\n  return s;\n}\n\nexport async function performUnderstudyMethod(\n  page: Page,\n  frame: Frame,\n  method: string,\n  rawXPath: string,\n  args: ReadonlyArray<unknown>,\n  domSettleTimeoutMs?: number,\n): Promise<void> {\n  const selectorRaw = normalizeRootXPath(rawXPath);\n  // Unified resolver: supports '>>' hops and XPath across iframes\n  const locator: Locator = await resolveLocatorWithHops(\n    page,\n    frame,\n    selectorRaw,\n  );\n\n  const initialUrl = await getFrameUrl(frame);\n\n  v3Logger({\n    category: \"action\",\n    message: \"performing understudy method\",\n    level: 2,\n    auxiliary: {\n      xpath: { value: selectorRaw, type: \"string\" },\n      method: { value: method, type: \"string\" },\n      url: { value: initialUrl, type: \"string\" },\n    },\n  });\n\n  const ctx: UnderstudyMethodHandlerContext = {\n    method,\n    locator,\n    xpath: selectorRaw,\n    args: args.map((a) => (a == null ? \"\" : String(a))),\n    frame,\n    page,\n    initialUrl,\n    domSettleTimeoutMs,\n  };\n\n  SessionFileLogger.logUnderstudyActionEvent({\n    actionType: `Understudy.${method}`,\n    target: selectorRaw,\n    args: Array.from(args),\n  });\n\n  try {\n    const handler = METHOD_HANDLER_MAP[method] ?? null;\n\n    if (handler) {\n      await handler(ctx);\n    } else {\n      // Accept a few common locator method aliases\n      switch (method) {\n        case \"click\":\n          await clickElement(ctx);\n          break;\n        case \"fill\":\n          await fillOrType(ctx);\n          break;\n        case \"type\":\n          await typeText(ctx);\n          break;\n        default:\n          v3Logger({\n            category: \"action\",\n            message: \"chosen method is invalid\",\n            level: 1,\n            auxiliary: { method: { value: method, type: \"string\" } },\n          });\n          throw new UnderstudyCommandException(\n            `Method ${method} not supported`,\n          );\n      }\n    }\n\n    await handlePossibleNavigation(\"action\", selectorRaw, initialUrl, frame);\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    const stack = e instanceof Error ? e.stack : undefined;\n    v3Logger({\n      category: \"action\",\n      message: \"error performing method\",\n      level: 1,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        trace: { value: stack ?? \"\", type: \"string\" },\n        method: { value: method, type: \"string\" },\n        xpath: { value: selectorRaw, type: \"string\" },\n        args: { value: JSON.stringify(args), type: \"object\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  } finally {\n    SessionFileLogger.logUnderstudyActionCompleted();\n  }\n}\n\n/* ===================== Handlers & Map ===================== */\n\nconst METHOD_HANDLER_MAP: Record<\n  string,\n  (ctx: UnderstudyMethodHandlerContext) => Promise<void>\n> = {\n  scrollIntoView,\n  scrollByPixelOffset,\n  scrollTo: scrollElementToPercentage,\n  scroll: scrollElementToPercentage,\n  \"mouse.wheel\": wheelScroll,\n  fill: fillOrType,\n  type: typeText,\n  press: pressKey,\n  click: clickElement,\n  doubleClick,\n  dragAndDrop,\n  nextChunk: scrollToNextChunk,\n  prevChunk: scrollToPreviousChunk,\n  selectOptionFromDropdown: selectOption,\n  selectOption: selectOption,\n  hover: hover,\n};\n\nexport async function selectOption(ctx: UnderstudyMethodHandlerContext) {\n  const { locator, xpath, args } = ctx;\n  try {\n    const text = args[0]?.toString() || \"\";\n    await locator.selectOption(text);\n  } catch (e) {\n    v3Logger({\n      category: \"action\",\n      message: \"error selecting option\",\n      level: 0,\n      auxiliary: {\n        error: { value: e.message, type: \"string\" },\n        trace: { value: e.stack, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(e.message);\n  }\n}\n\nasync function scrollIntoView(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  const { locator, xpath } = ctx;\n  v3Logger({\n    category: \"action\",\n    message: \"scrolling element into view\",\n    level: 2,\n    auxiliary: { xpath: { value: xpath, type: \"string\" } },\n  });\n  const { objectId } = await locator.resolveNode();\n  const ownerSession = locator.getFrame().session;\n  await ownerSession.send(\"DOM.scrollIntoViewIfNeeded\", { objectId });\n  await ownerSession\n    .send(\"Runtime.releaseObject\", { objectId })\n    .catch(() => {});\n}\n\nasync function scrollElementToPercentage(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  const { locator, xpath, args } = ctx;\n  v3Logger({\n    category: \"action\",\n    message: \"scrolling element vertically to specified percentage\",\n    level: 2,\n    auxiliary: {\n      xpath: { value: xpath, type: \"string\" },\n      coordinate: { value: JSON.stringify(args), type: \"string\" },\n    },\n  });\n\n  const [yArg = \"0%\"] = args;\n  await locator.scrollTo(yArg);\n}\n\n/** Scroll the page by pixel offset, starting from the element's center. */\nasync function scrollByPixelOffset(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  const { locator, page, args } = ctx;\n  const dx = Number(args[0] ?? 0);\n  const dy = Number(args[1] ?? 0);\n\n  try {\n    const { x, y } = await locator.centroid();\n    await page.scroll(x, y, dx, dy);\n  } catch (e) {\n    throw new UnderstudyCommandException(e.message);\n  }\n}\n\nasync function wheelScroll(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { frame, args } = ctx;\n  const deltaY = Number(args[0] ?? 200);\n  v3Logger({\n    category: \"action\",\n    message: \"dispatching mouse wheel\",\n    level: 2,\n    auxiliary: { deltaY: { value: String(deltaY), type: \"string\" } },\n  });\n  await frame.session.send<never>(\"Input.dispatchMouseEvent\", {\n    type: \"mouseWheel\",\n    x: 0,\n    y: 0,\n    deltaY,\n    deltaX: 0,\n  } as Protocol.Input.DispatchMouseEventRequest);\n}\n\nasync function fillOrType(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { locator, xpath, args } = ctx;\n  try {\n    await locator.fill(\"\"); // clear\n    await locator.fill(args[0] ?? \"\");\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error filling element\",\n      level: 1,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  }\n}\n\nasync function typeText(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { locator, xpath, args } = ctx;\n  try {\n    await locator.type(args[0] ?? \"\");\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error typing into element\",\n      level: 1,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  }\n}\n\nasync function pressKey(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { args, xpath, page } = ctx;\n  const key = args[0] ?? \"\";\n  try {\n    v3Logger({\n      category: \"action\",\n      message: \"pressing key\",\n      level: 1,\n      auxiliary: {\n        key: { value: key, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    await page.keyPress(key);\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error pressing key\",\n      level: 1,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        key: { value: key, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  }\n}\n\nasync function clickElement(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  const { locator, xpath, args } = ctx;\n  try {\n    await locator.click({ button: (args[0] as MouseButton) || undefined });\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error performing click\",\n      level: 0,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new StagehandClickError(ctx.xpath, msg);\n  }\n}\n\nasync function doubleClick(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { locator, xpath } = ctx;\n  try {\n    await locator.click({ clickCount: 2 });\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error performing doubleClick\",\n      level: 0,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  }\n}\n\nasync function dragAndDrop(ctx: UnderstudyMethodHandlerContext): Promise<void> {\n  const { page, frame, locator, args, xpath } = ctx;\n  const toXPath = String(args[0] ?? \"\").trim();\n  if (!toXPath)\n    throw new UnderstudyCommandException(\n      \"dragAndDrop requires a target XPath arg\",\n    );\n\n  const targetLocator = await resolveLocatorWithHops(page, frame, toXPath);\n\n  try {\n    // 1) Centers in local (owning-frame) viewport\n    const { x: fromLocalX, y: fromLocalY } = await locator.centroid();\n    const { x: toLocalX, y: toLocalY } = await targetLocator.centroid();\n\n    // 2) Convert to main-viewport absolute coordinates\n    const fromAbs = await locator\n      .getFrame()\n      .evaluate<{ x: number; y: number }, { x: number; y: number }>(\n        ({ x, y }: { x: number; y: number }) => {\n          let X = x;\n          let Y = y;\n          let w: Window = window;\n          while (w !== w.top) {\n            const fe = w.frameElement as HTMLElement | null;\n            if (!fe) break;\n            const r = fe.getBoundingClientRect();\n            X += r.left;\n            Y += r.top;\n            w = w.parent as Window;\n          }\n          return { x: Math.round(X), y: Math.round(Y) };\n        },\n        { x: fromLocalX, y: fromLocalY },\n      );\n\n    const toAbs = await targetLocator\n      .getFrame()\n      .evaluate<{ x: number; y: number }, { x: number; y: number }>(\n        ({ x, y }: { x: number; y: number }) => {\n          let X = x;\n          let Y = y;\n          let w: Window = window;\n          while (w !== w.top) {\n            const fe = w.frameElement as HTMLElement | null;\n            if (!fe) break;\n            const r = fe.getBoundingClientRect();\n            X += r.left;\n            Y += r.top;\n            w = w.parent as Window;\n          }\n          return { x: Math.round(X), y: Math.round(Y) };\n        },\n        { x: toLocalX, y: toLocalY },\n      );\n\n    // 3) Perform drag in main session\n    await page.dragAndDrop(fromAbs.x, fromAbs.y, toAbs.x, toAbs.y, {\n      steps: 10,\n      delay: 5,\n    });\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    v3Logger({\n      category: \"action\",\n      message: \"error performing dragAndDrop\",\n      level: 0,\n      auxiliary: {\n        error: { value: msg, type: \"string\" },\n        from: { value: xpath, type: \"string\" },\n        to: { value: toXPath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(msg);\n  }\n}\n\nasync function scrollToNextChunk(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  await scrollByElementHeight(ctx, /*dir=*/ 1);\n}\n\nasync function scrollToPreviousChunk(\n  ctx: UnderstudyMethodHandlerContext,\n): Promise<void> {\n  await scrollByElementHeight(ctx, /*dir=*/ -1);\n}\n\nasync function scrollByElementHeight(\n  ctx: UnderstudyMethodHandlerContext,\n  direction: 1 | -1,\n): Promise<void> {\n  const { locator, xpath } = ctx;\n  v3Logger({\n    category: \"action\",\n    message:\n      direction > 0 ? \"scrolling to next chunk\" : \"scrolling to previous chunk\",\n    level: 2,\n    auxiliary: { xpath: { value: xpath, type: \"string\" } },\n  });\n\n  const { objectId } = await locator.resolveNode();\n  try {\n    const ownerSession = locator.getFrame().session;\n    await ownerSession.send<Protocol.Runtime.CallFunctionOnResponse>(\n      \"Runtime.callFunctionOn\",\n      {\n        objectId,\n        functionDeclaration: `\n          function(dir) {\n            const waitForScrollEnd = (el) => new Promise((resolve) => {\n              let last = el.scrollTop ?? 0;\n              const check = () => {\n                const cur = el.scrollTop ?? 0;\n                if (cur === last) return resolve();\n                last = cur;\n                requestAnimationFrame(check);\n              };\n              requestAnimationFrame(check);\n            });\n\n            const tag = this.tagName?.toLowerCase();\n            if (tag === \"html\" || tag === \"body\") {\n              const h = window.visualViewport?.height ?? window.innerHeight;\n              window.scrollBy({ top: h * dir, left: 0, behavior: \"smooth\" });\n              const root = document.scrollingElement ?? document.documentElement;\n              return waitForScrollEnd(root);\n            }\n            const h = this.getBoundingClientRect().height;\n            this.scrollBy({ top: h * dir, left: 0, behavior: \"smooth\" });\n            return waitForScrollEnd(this);\n          }\n        `,\n        arguments: [{ value: direction }],\n        awaitPromise: true,\n        returnByValue: true,\n      },\n    );\n  } finally {\n    const ownerSession = locator.getFrame().session;\n    await ownerSession\n      .send(\"Runtime.releaseObject\", { objectId })\n      .catch(() => {});\n  }\n}\n\nexport async function hover(ctx: UnderstudyMethodHandlerContext) {\n  const { locator, xpath } = ctx;\n  try {\n    await locator.hover();\n  } catch (e) {\n    v3Logger({\n      category: \"action\",\n      message: \"error attempting to hover\",\n      level: 0,\n      auxiliary: {\n        error: { value: e.message, type: \"string\" },\n        trace: { value: e.stack, type: \"string\" },\n        xpath: { value: xpath, type: \"string\" },\n      },\n    });\n    throw new UnderstudyCommandException(e.message);\n  }\n}\n\n/* ===================== Helpers ===================== */\n\nasync function getFrameUrl(frame: Frame): Promise<string> {\n  // Evaluate from within the frame's isolated world\n  const url = await frame.evaluate<string>(\"location.href\");\n  return url;\n}\n\n/**\n * More robust DOM settle using Network + Page events to detect network quiet.\n * Closely modeled after the provided snippet, adapted to our Frame/session + logger.\n */\nexport async function waitForDomNetworkQuiet(\n  frame: Frame,\n  timeoutMs?: number,\n): Promise<void> {\n  const overallTimeout =\n    typeof timeoutMs === \"number\" && Number.isFinite(timeoutMs)\n      ? Math.max(0, timeoutMs)\n      : 5_000;\n  const client = frame.session;\n  const settleStart = Date.now();\n\n  // Ensure a document exists; if not, wait for DOMContentLoaded on this frame.\n  let hasDoc: boolean;\n  try {\n    const rs = await frame.evaluate<string>(\"document.readyState\");\n    hasDoc = rs === \"interactive\" || rs === \"complete\";\n  } catch {\n    hasDoc = false;\n  }\n  if (!hasDoc && overallTimeout > 0) {\n    await frame\n      .waitForLoadState(\"domcontentloaded\", overallTimeout)\n      .catch(() => {});\n  }\n\n  const elapsed = Date.now() - settleStart;\n  const remainingBudget = Math.max(0, overallTimeout - elapsed);\n  if (remainingBudget === 0) {\n    return;\n  }\n\n  await client.send(\"Network.enable\").catch(() => {});\n  await client.send(\"Page.enable\").catch(() => {});\n  // Best-effort; some sessions may not support Target.setAutoAttach here.\n  await client\n    .send(\"Target.setAutoAttach\", {\n      autoAttach: true,\n      waitForDebuggerOnStart: false,\n      flatten: true,\n      filter: [\n        { type: \"worker\", exclude: true },\n        { type: \"shared_worker\", exclude: true },\n      ],\n    })\n    .catch(() => {});\n\n  return new Promise<void>((resolve) => {\n    const inflight = new Set<string>();\n    const meta = new Map<string, { url: string; start: number }>();\n    const docByFrame = new Map<string, string>();\n\n    let quietTimer: NodeJS.Timeout | null = null;\n    let stalledRequestSweepTimer: NodeJS.Timeout | null = null;\n\n    const clearQuiet = () => {\n      if (quietTimer) {\n        clearTimeout(quietTimer);\n        quietTimer = null;\n      }\n    };\n\n    const maybeQuiet = () => {\n      if (inflight.size === 0 && !quietTimer)\n        quietTimer = setTimeout(() => resolveDone(), 500);\n    };\n\n    const finishReq = (id: string) => {\n      if (!inflight.delete(id)) return;\n      meta.delete(id);\n      for (const [fid, rid] of docByFrame)\n        if (rid === id) docByFrame.delete(fid);\n      clearQuiet();\n      maybeQuiet();\n    };\n\n    const onRequest = (p: Protocol.Network.RequestWillBeSentEvent) => {\n      // Ignore long-lived streams\n      // ResourceType includes: Document, XHR, Fetch, WebSocket, EventSource, etc.\n      if (p.type === \"WebSocket\" || p.type === \"EventSource\") return;\n\n      inflight.add(p.requestId);\n      meta.set(p.requestId, { url: p.request.url, start: Date.now() });\n\n      if (p.type === \"Document\" && p.frameId)\n        docByFrame.set(p.frameId, p.requestId);\n\n      clearQuiet();\n    };\n\n    const onFinish = (p: { requestId: string }) => finishReq(p.requestId);\n    const onCached = (p: { requestId: string }) => finishReq(p.requestId);\n    const onDataUrl = (p: Protocol.Network.ResponseReceivedEvent) => {\n      if (p.response.url?.startsWith(\"data:\")) finishReq(p.requestId);\n    };\n\n    const onFrameStop = (f: Protocol.Page.FrameStoppedLoadingEvent) => {\n      const id = docByFrame.get(f.frameId);\n      if (id) finishReq(id);\n    };\n\n    client.on(\"Network.requestWillBeSent\", onRequest);\n    client.on(\"Network.loadingFinished\", onFinish);\n    client.on(\"Network.loadingFailed\", onFinish);\n    client.on(\"Network.requestServedFromCache\", onCached);\n    client.on(\"Network.responseReceived\", onDataUrl);\n    client.on(\"Page.frameStoppedLoading\", onFrameStop);\n\n    stalledRequestSweepTimer = setInterval(() => {\n      const now = Date.now();\n      for (const [id, m] of meta) {\n        if (now - m.start > 2_000) {\n          inflight.delete(id);\n          meta.delete(id);\n          v3Logger({\n            category: \"dom\",\n            message: \"⏳ forcing completion of stalled iframe document\",\n            level: 1,\n            auxiliary: {\n              url: { value: (m.url ?? \"\").slice(0, 120), type: \"string\" },\n            },\n          });\n        }\n      }\n      maybeQuiet();\n    }, 500);\n\n    maybeQuiet();\n\n    const guard = setTimeout(() => {\n      if (inflight.size) {\n        v3Logger({\n          category: \"dom\",\n          message:\n            \"⚠️ DOM-settle timeout reached – network requests still pending\",\n          level: 1,\n          auxiliary: {\n            count: { value: String(inflight.size), type: \"integer\" },\n          },\n        });\n      }\n      resolveDone();\n    }, remainingBudget);\n\n    const resolveDone = () => {\n      client.off(\"Network.requestWillBeSent\", onRequest);\n      client.off(\"Network.loadingFinished\", onFinish);\n      client.off(\"Network.loadingFailed\", onFinish);\n      client.off(\"Network.requestServedFromCache\", onCached);\n      client.off(\"Network.responseReceived\", onDataUrl);\n      client.off(\"Page.frameStoppedLoading\", onFrameStop);\n      if (quietTimer) clearTimeout(quietTimer);\n      if (stalledRequestSweepTimer) clearInterval(stalledRequestSweepTimer);\n      clearTimeout(guard);\n      resolve();\n    };\n  });\n}\n\nasync function handlePossibleNavigation(\n  actionDescription: string,\n  xpath: string,\n  initialUrl: string,\n  frame: Frame,\n): Promise<void> {\n  v3Logger({\n    category: \"action\",\n    message: `${actionDescription}, checking for page navigation`,\n    level: 1,\n    auxiliary: { xpath: { value: xpath, type: \"string\" } },\n  });\n\n  // We only have a frame-scoped session, so detect navigation by URL change.\n  const afterUrl = await getFrameUrl(frame);\n\n  if (afterUrl !== initialUrl) {\n    v3Logger({\n      category: \"action\",\n      message: \"new page (frame) URL detected\",\n      level: 1,\n      auxiliary: { url: { value: afterUrl, type: \"string\" } },\n    });\n  } else {\n    v3Logger({\n      category: \"action\",\n      message: \"no new (frame) URL detected\",\n      level: 1,\n      auxiliary: { url: { value: afterUrl, type: \"string\" } },\n    });\n  }\n}\n"]}

package/dist/esm/lib/v3/handlers/handlerUtils/timeoutGuard.d.ts

@@ -0,0 +1,2 @@
+export type TimeoutGuard = () => void;
+export declare function createTimeoutGuard(timeoutMs?: number, errorFactory?: (timeoutMs: number) => Error): TimeoutGuard;

package/dist/esm/lib/v3/handlers/handlerUtils/timeoutGuard.js

@@ -0,0 +1,14 @@
+import { TimeoutError } from "../../types/public/sdkErrors.js";
+export function createTimeoutGuard(timeoutMs, errorFactory) {
+    if (!timeoutMs || timeoutMs <= 0) {
+        return () => { };
+    }
+    const startTime = Date.now();
+    return () => {
+        if (Date.now() - startTime >= timeoutMs) {
+            const err = errorFactory?.(timeoutMs) ?? new TimeoutError("operation", timeoutMs);
+            throw err;
+        }
+    };
+}
+//# sourceMappingURL=timeoutGuard.js.map

package/dist/esm/lib/v3/handlers/handlerUtils/timeoutGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeoutGuard.js","sourceRoot":"","sources":["../../../../../../lib/v3/handlers/handlerUtils/timeoutGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAI/D,MAAM,UAAU,kBAAkB,CAChC,SAAkB,EAClB,YAA2C;IAE3C,IAAI,CAAC,SAAS,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,OAAO,GAAG,EAAE;QACV,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;YACxC,MAAM,GAAG,GACP,YAAY,EAAE,CAAC,SAAS,CAAC,IAAI,IAAI,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YACxE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { TimeoutError } from \"../../types/public/sdkErrors.js\";\n\nexport type TimeoutGuard = () => void;\n\nexport function createTimeoutGuard(\n  timeoutMs?: number,\n  errorFactory?: (timeoutMs: number) => Error,\n): TimeoutGuard {\n  if (!timeoutMs || timeoutMs <= 0) {\n    return () => {};\n  }\n\n  const startTime = Date.now();\n  return () => {\n    if (Date.now() - startTime >= timeoutMs) {\n      const err =\n        errorFactory?.(timeoutMs) ?? new TimeoutError(\"operation\", timeoutMs);\n      throw err;\n    }\n  };\n}\n"]}

package/dist/esm/lib/v3/handlers/observeHandler.d.ts

@@ -0,0 +1,17 @@
+import { V3FunctionName } from "../types/public/methods.js";
+import { LLMClient } from "../llm/LLMClient.js";
+import { ObserveHandlerParams } from "../types/private/handlers.js";
+import { Action } from "../types/public/methods.js";
+import { AvailableModel, ClientOptions, ModelConfiguration } from "../types/public/model.js";
+export declare class ObserveHandler {
+    private readonly llmClient;
+    private readonly defaultModelName;
+    private readonly defaultClientOptions;
+    private readonly resolveLlmClient;
+    private readonly systemPrompt;
+    private readonly logInferenceToFile;
+    private readonly experimental;
+    private readonly onMetrics?;
+    constructor(llmClient: LLMClient, defaultModelName: AvailableModel, defaultClientOptions: ClientOptions, resolveLlmClient: (model?: ModelConfiguration) => LLMClient, systemPrompt?: string, logInferenceToFile?: boolean, experimental?: boolean, onMetrics?: (functionName: V3FunctionName, promptTokens: number, completionTokens: number, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number) => void);
+    observe(params: ObserveHandlerParams): Promise<Action[]>;
+}

package/dist/esm/lib/v3/handlers/observeHandler.js

@@ -0,0 +1,156 @@
+// lib/v3/handlers/observeHandler.ts
+import { observe as runObserve } from "../../inference.js";
+import { trimTrailingTextNode } from "../../utils.js";
+import { v3Logger } from "../logger.js";
+import { V3FunctionName } from "../types/public/methods.js";
+import { captureHybridSnapshot } from "../understudy/a11y/snapshot/index.js";
+import { SupportedUnderstudyAction, } from "../types/private/handlers.js";
+import { ObserveTimeoutError } from "../types/public/sdkErrors.js";
+import { createTimeoutGuard } from "./handlerUtils/timeoutGuard.js";
+export class ObserveHandler {
+    llmClient;
+    defaultModelName;
+    defaultClientOptions;
+    resolveLlmClient;
+    systemPrompt;
+    logInferenceToFile;
+    experimental;
+    onMetrics;
+    constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, experimental, onMetrics) {
+        this.llmClient = llmClient;
+        this.defaultModelName = defaultModelName;
+        this.defaultClientOptions = defaultClientOptions;
+        this.resolveLlmClient = resolveLlmClient;
+        this.systemPrompt = systemPrompt ?? "";
+        this.logInferenceToFile = logInferenceToFile ?? false;
+        this.experimental = experimental ?? false;
+        this.onMetrics = onMetrics;
+    }
+    async observe(params) {
+        const { instruction, page, timeout, selector, model } = params;
+        const llmClient = this.resolveLlmClient(model);
+        const effectiveTimeoutMs = typeof timeout === "number" && timeout > 0 ? timeout : undefined;
+        const ensureTimeRemaining = createTimeoutGuard(effectiveTimeoutMs, (ms) => new ObserveTimeoutError(ms));
+        const effectiveInstruction = instruction ??
+            "Find elements that can be used for any future actions in the page. These may be navigation links, related pages, section/subsection links, buttons, or other interactive elements. Be comprehensive: if there are multiple elements that may be relevant for future actions, return all of them.";
+        v3Logger({
+            category: "observation",
+            message: "starting observation",
+            level: 1,
+            auxiliary: {
+                instruction: {
+                    value: effectiveInstruction,
+                    type: "string",
+                },
+            },
+        });
+        // Build the hybrid snapshot (a11y-centric text tree + lookup maps)
+        const focusSelector = selector?.replace(/^xpath=/i, "") ?? "";
+        ensureTimeRemaining();
+        const snapshot = await captureHybridSnapshot(page, {
+            experimental: this.experimental,
+            focusSelector: focusSelector || undefined,
+        });
+        const combinedTree = snapshot.combinedTree;
+        const combinedXpathMap = snapshot.combinedXpathMap ?? {};
+        v3Logger({
+            category: "observation",
+            message: "Got accessibility tree data",
+            level: 1,
+        });
+        // Call the LLM to propose actionable elements
+        ensureTimeRemaining();
+        const observationResponse = await runObserve({
+            instruction: effectiveInstruction,
+            domElements: combinedTree,
+            llmClient,
+            userProvidedInstructions: this.systemPrompt,
+            logger: v3Logger,
+            logInferenceToFile: this.logInferenceToFile,
+            supportedActions: Object.values(SupportedUnderstudyAction),
+        });
+        const { prompt_tokens = 0, completion_tokens = 0, reasoning_tokens = 0, cached_input_tokens = 0, inference_time_ms = 0, } = observationResponse;
+        // Update OBSERVE metrics from the LLM observation call
+        this.onMetrics?.(V3FunctionName.OBSERVE, prompt_tokens, completion_tokens, reasoning_tokens, cached_input_tokens, inference_time_ms);
+        // Map elementIds -> selectors via combinedXpathMap
+        const elementsWithSelectors = (await Promise.all(observationResponse.elements.map(async (element) => {
+            const { elementId, ...rest } = element; // rest may or may not have method/arguments
+            if (typeof elementId === "string" && elementId.includes("-")) {
+                const lookUpIndex = elementId;
+                const xpath = combinedXpathMap[lookUpIndex];
+                const trimmedXpath = trimTrailingTextNode(xpath);
+                if (!trimmedXpath)
+                    return undefined;
+                // For dragAndDrop, convert element ID in arguments to xpath (target element)
+                let resolvedArgs = rest.arguments;
+                if (rest.method === "dragAndDrop" &&
+                    Array.isArray(rest.arguments) &&
+                    rest.arguments.length > 0) {
+                    const targetArg = rest.arguments[0];
+                    // Check if argument looks like an element ID (e.g., "1-67")
+                    if (typeof targetArg === "string" &&
+                        /^\d+-\d+$/.test(targetArg)) {
+                        const argXpath = combinedXpathMap[targetArg];
+                        const trimmedArgXpath = trimTrailingTextNode(argXpath);
+                        if (trimmedArgXpath) {
+                            resolvedArgs = [
+                                `xpath=${trimmedArgXpath}`,
+                                ...rest.arguments.slice(1),
+                            ];
+                        }
+                        else {
+                            // Target element lookup failed, filter out this action
+                            v3Logger({
+                                category: "observation",
+                                message: "dragAndDrop target element lookup failed",
+                                level: 0,
+                                auxiliary: {
+                                    targetElementId: { value: targetArg, type: "string" },
+                                    sourceElementId: { value: elementId, type: "string" },
+                                },
+                            });
+                            return undefined;
+                        }
+                    }
+                    else {
+                        v3Logger({
+                            category: "observation",
+                            message: "dragAndDrop target element invalid ID format",
+                            level: 0,
+                            auxiliary: {
+                                targetElementId: { value: targetArg, type: "string" },
+                                sourceElementId: { value: elementId, type: "string" },
+                            },
+                        });
+                        return undefined;
+                    }
+                }
+                return {
+                    ...rest,
+                    arguments: resolvedArgs,
+                    selector: `xpath=${trimmedXpath}`,
+                };
+            }
+            // shadow-root fallback:
+            return {
+                description: "an element inside a shadow DOM",
+                method: "not-supported",
+                arguments: [],
+                selector: "not-supported",
+            };
+        }))).filter((e) => e !== undefined);
+        v3Logger({
+            category: "observation",
+            message: "found elements",
+            level: 1,
+            auxiliary: {
+                elements: {
+                    value: JSON.stringify(elementsWithSelectors),
+                    type: "object",
+                },
+            },
+        });
+        return elementsWithSelectors;
+    }
+}
+//# sourceMappingURL=observeHandler.js.map

package/dist/esm/lib/v3/handlers/observeHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observeHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/observeHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/observeHandler.ts\nimport { observe as runObserve } from \"../../inference.js\";\nimport { trimTrailingTextNode } from \"../../utils.js\";\nimport { v3Logger } from \"../logger.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { captureHybridSnapshot } from \"../understudy/a11y/snapshot/index.js\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport {\n  ObserveHandlerParams,\n  SupportedUnderstudyAction,\n} from \"../types/private/handlers.js\";\nimport { EncodedId } from \"../types/private/internal.js\";\nimport { Action } from \"../types/public/methods.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelConfiguration,\n} from \"../types/public/model.js\";\nimport { ObserveTimeoutError } from \"../types/public/sdkErrors.js\";\nimport { createTimeoutGuard } from \"./handlerUtils/timeoutGuard.js\";\n\nexport class ObserveHandler {\n  private readonly llmClient: LLMClient;\n  private readonly defaultModelName: AvailableModel;\n  private readonly defaultClientOptions: ClientOptions;\n  private readonly resolveLlmClient: (model?: ModelConfiguration) => LLMClient;\n  private readonly systemPrompt: string;\n  private readonly logInferenceToFile: boolean;\n  private readonly experimental: boolean;\n  private readonly onMetrics?: (\n    functionName: V3FunctionName,\n    promptTokens: number,\n    completionTokens: number,\n    reasoningTokens: number,\n    cachedInputTokens: number,\n    inferenceTimeMs: number,\n  ) => void;\n\n  constructor(\n    llmClient: LLMClient,\n    defaultModelName: AvailableModel,\n    defaultClientOptions: ClientOptions,\n    resolveLlmClient: (model?: ModelConfiguration) => LLMClient,\n    systemPrompt?: string,\n    logInferenceToFile?: boolean,\n    experimental?: boolean,\n    onMetrics?: (\n      functionName: V3FunctionName,\n      promptTokens: number,\n      completionTokens: number,\n      reasoningTokens: number,\n      cachedInputTokens: number,\n      inferenceTimeMs: number,\n    ) => void,\n  ) {\n    this.llmClient = llmClient;\n    this.defaultModelName = defaultModelName;\n    this.defaultClientOptions = defaultClientOptions;\n    this.resolveLlmClient = resolveLlmClient;\n    this.systemPrompt = systemPrompt ?? \"\";\n    this.logInferenceToFile = logInferenceToFile ?? false;\n    this.experimental = experimental ?? false;\n    this.onMetrics = onMetrics;\n  }\n\n  async observe(params: ObserveHandlerParams): Promise<Action[]> {\n    const { instruction, page, timeout, selector, model } = params;\n\n    const llmClient = this.resolveLlmClient(model);\n\n    const effectiveTimeoutMs =\n      typeof timeout === \"number\" && timeout > 0 ? timeout : undefined;\n    const ensureTimeRemaining = createTimeoutGuard(\n      effectiveTimeoutMs,\n      (ms) => new ObserveTimeoutError(ms),\n    );\n\n    const effectiveInstruction =\n      instruction ??\n      \"Find elements that can be used for any future actions in the page. These may be navigation links, related pages, section/subsection links, buttons, or other interactive elements. Be comprehensive: if there are multiple elements that may be relevant for future actions, return all of them.\";\n\n    v3Logger({\n      category: \"observation\",\n      message: \"starting observation\",\n      level: 1,\n      auxiliary: {\n        instruction: {\n          value: effectiveInstruction,\n          type: \"string\",\n        },\n      },\n    });\n\n    // Build the hybrid snapshot (a11y-centric text tree + lookup maps)\n    const focusSelector = selector?.replace(/^xpath=/i, \"\") ?? \"\";\n    ensureTimeRemaining();\n    const snapshot = await captureHybridSnapshot(page, {\n      experimental: this.experimental,\n      focusSelector: focusSelector || undefined,\n    });\n\n    const combinedTree = snapshot.combinedTree;\n    const combinedXpathMap = snapshot.combinedXpathMap ?? {};\n\n    v3Logger({\n      category: \"observation\",\n      message: \"Got accessibility tree data\",\n      level: 1,\n    });\n\n    // Call the LLM to propose actionable elements\n    ensureTimeRemaining();\n    const observationResponse = await runObserve({\n      instruction: effectiveInstruction,\n      domElements: combinedTree,\n      llmClient,\n      userProvidedInstructions: this.systemPrompt,\n      logger: v3Logger,\n      logInferenceToFile: this.logInferenceToFile,\n      supportedActions: Object.values(SupportedUnderstudyAction),\n    });\n\n    const {\n      prompt_tokens = 0,\n      completion_tokens = 0,\n      reasoning_tokens = 0,\n      cached_input_tokens = 0,\n      inference_time_ms = 0,\n    } = observationResponse;\n\n    // Update OBSERVE metrics from the LLM observation call\n    this.onMetrics?.(\n      V3FunctionName.OBSERVE,\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens,\n      cached_input_tokens,\n      inference_time_ms,\n    );\n\n    // Map elementIds -> selectors via combinedXpathMap\n    const elementsWithSelectors = (\n      await Promise.all(\n        observationResponse.elements.map(async (element) => {\n          const { elementId, ...rest } = element; // rest may or may not have method/arguments\n          if (typeof elementId === \"string\" && elementId.includes(\"-\")) {\n            const lookUpIndex = elementId as EncodedId;\n            const xpath = combinedXpathMap[lookUpIndex];\n            const trimmedXpath = trimTrailingTextNode(xpath);\n            if (!trimmedXpath) return undefined;\n\n            // For dragAndDrop, convert element ID in arguments to xpath (target element)\n            let resolvedArgs = rest.arguments;\n            if (\n              rest.method === \"dragAndDrop\" &&\n              Array.isArray(rest.arguments) &&\n              rest.arguments.length > 0\n            ) {\n              const targetArg = rest.arguments[0];\n              // Check if argument looks like an element ID (e.g., \"1-67\")\n              if (\n                typeof targetArg === \"string\" &&\n                /^\\d+-\\d+$/.test(targetArg)\n              ) {\n                const argXpath = combinedXpathMap[targetArg as EncodedId];\n                const trimmedArgXpath = trimTrailingTextNode(argXpath);\n                if (trimmedArgXpath) {\n                  resolvedArgs = [\n                    `xpath=${trimmedArgXpath}`,\n                    ...rest.arguments.slice(1),\n                  ];\n                } else {\n                  // Target element lookup failed, filter out this action\n                  v3Logger({\n                    category: \"observation\",\n                    message: \"dragAndDrop target element lookup failed\",\n                    level: 0,\n                    auxiliary: {\n                      targetElementId: { value: targetArg, type: \"string\" },\n                      sourceElementId: { value: elementId, type: \"string\" },\n                    },\n                  });\n                  return undefined;\n                }\n              } else {\n                v3Logger({\n                  category: \"observation\",\n                  message: \"dragAndDrop target element invalid ID format\",\n                  level: 0,\n                  auxiliary: {\n                    targetElementId: { value: targetArg, type: \"string\" },\n                    sourceElementId: { value: elementId, type: \"string\" },\n                  },\n                });\n                return undefined;\n              }\n            }\n\n            return {\n              ...rest,\n              arguments: resolvedArgs,\n              selector: `xpath=${trimmedXpath}`,\n            } as {\n              description: string;\n              method?: string;\n              arguments?: string[];\n              selector: string;\n            };\n          }\n          // shadow-root fallback:\n          return {\n            description: \"an element inside a shadow DOM\",\n            method: \"not-supported\",\n            arguments: [],\n            selector: \"not-supported\",\n          };\n        }),\n      )\n    ).filter(<T>(e: T | undefined): e is T => e !== undefined);\n\n    v3Logger({\n      category: \"observation\",\n      message: \"found elements\",\n      level: 1,\n      auxiliary: {\n        elements: {\n          value: JSON.stringify(elementsWithSelectors),\n          type: \"object\",\n        },\n      },\n    });\n\n    return elementsWithSelectors;\n  }\n}\n"]}

package/dist/esm/lib/v3/handlers/v3AgentHandler.d.ts

@@ -0,0 +1,32 @@
+import { LogLine } from "../types/public/logs.js";
+import { V3 } from "../v3.js";
+import { ToolSet } from "ai";
+import { LLMClient } from "../llm/LLMClient.js";
+import { AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, AgentStreamResult, AgentToolMode, AgentModelConfig } from "../types/public/agent.js";
+export declare class V3AgentHandler {
+    private v3;
+    private logger;
+    private llmClient;
+    private executionModel?;
+    private systemInstructions?;
+    private mcpTools?;
+    private mode;
+    constructor(v3: V3, logger: (message: LogLine) => void, llmClient: LLMClient, executionModel?: string | AgentModelConfig, systemInstructions?: string, mcpTools?: ToolSet, mode?: AgentToolMode);
+    private prepareAgent;
+    private createPrepareStep;
+    private createStepHandler;
+    execute(instructionOrOptions: string | AgentExecuteOptions): Promise<AgentResult>;
+    stream(instructionOrOptions: string | AgentStreamExecuteOptions): Promise<AgentStreamResult>;
+    private consolidateMetricsAndResult;
+    private createTools;
+    private handleStop;
+    /**
+     * Ensures the done tool is called at the end of agent execution.
+     * Returns the messages and any extracted output from the done call.
+     */
+    private ensureDone;
+    /**
+     * Capture a screenshot and emit it via the event bus
+     */
+    private captureAndEmitScreenshot;
+}